MangoMe

New to MangoMe? Start here

If this is your first time using MangoMe, begin with the beginner documentation before diving into the architecture and protocol references:

• Start Here — MangoMe in a few minutes: what it is, what problem it solves, and the basic mental model.

• Getting Started — installation, client setup, first health check, and the first governed task.

• 5-minute Demo — copy/paste smoke test and durable MongoDB handoff.

• Compatibility — what the release suite covers, what managed clients support, and what remains deployment-dependent.

• Troubleshooting — common integration and runtime errors such as STATE_NOT_FOUND, WRONG_MANGOME_DATABASE, WORKSPACE_BINDING_AMBIGUOUS, and Skill/MCP readiness issues.

• Why MangoMe? — concrete agent failure modes and how MangoMe changes the operational behavior.

The rest of this README and the documents under docs/ describe the deeper architecture, protocols, governance model, verification semantics, and research foundations.

Related MCP server: Coordination Memory MCP

MangoMe is not just a state machine

MangoMe is the canonical operational memory underneath long-running AI work.

It combines responsibilities that are usually scattered across chats, repositories, task trackers, reports and agent memory:

DOCUMENT STORE
    +
WORK GRAPH
    +
DURABLE WORK IDENTITY
    +
STATE MACHINE
    +
SPECIFICATION / NORMATIVE BASELINE HISTORY
    +
EVIDENCE / PROVENANCE LEDGER
    +
EXTERNAL EFFECT / RECONCILIATION LEDGER
    +
EXECUTION ECONOMICS
    +
DETERMINISTIC CONTEXT COMPILER
    +
COMPACT SEMANTIC TRANSPORT

A worker is not a truth source. A worker can execute, observe, propose and claim completion. MangoMe persists what the work is, what is expected, what was observed, what was claimed, and what was independently verified.

Workers are ephemeral executors. MangoMe is the canonical operational record within its governed scope.

In the default LOCAL_HOST deployment, that governed scope is a cooperative host boundary. MangoMe does not claim tamper resistance against a process with direct MongoDB/host write access.

The central distinction is:

N = normative truth
    What must be true?

O = observed truth
    What is actually present?

J = worker judgment
    What does the worker conclude from N and O?

V = independent verification
    What has been independently demonstrated?

MangoMe externalizes state so agents spend model capacity on the unresolved delta instead of repeatedly reconstructing history from prompts, filesystem paths or prior agent prose.

Externalize state. Localize uncertainty. Preserve agency. Verify independently.

Why MangoMe exists

Long-running AI work tends to fail in a predictable way: artifacts survive, but the shared operational understanding does not.

A Claude session ends. Codex continues. Another agent sees a different database. A worker says “done”. A specification has changed. A previous test result exists but is stale. Two agents touch related work. A coordinator reconstructs state from a repository instead of reading the canonical system.

MangoMe moves that problem out of the prompt and into durable, inspectable state.

A normal worker should not need to know or expose MangoMe internals to the user. The worker should use MangoMe to organize its execution, persist progress and recover safely.

v0.3.22 — Zero-Touch Work Admission

v0.3.22 removes another agent-facing governance decision. Workspace state is not current-request identity: unrelated admitted work in the same workspace no longer causes a new request to stop and ask the user for a WorkIdentity.

On the normal seven-tool worker surface:

current user productive request
        ↓
RECONCILE_ASSIGNMENT
        ↓
exact admitted request match?
  ├─ yes → internal existing-work continuation path
  └─ no  → CONFLICT (reason NO_MATCH; reconcile never creates work — use an explicit enter_work)
                ↓
          automatic ENTER_WORK
                ↓
          EXECUTE_CURRENT_SLICE

The user is not asked whether MangoMe should create an internal work entry and is not asked to provide an internal work_ref for genuinely new work.

v0.3.21 — Agent-Proof Zero-Touch Runtime

v0.3.21 is a narrow operability repair.

• Managed MCP startup detects older MangoMe generations from the same managed installation and retires only those stale processes.

• HEALTH exposes runtime-generation drift.

• In-place version updates can rebind the expected version when the configured source root still matches.

• If the current user explicitly says a task should run without MangoMe, MangoMe stays out of that task.

• FRAMEWORK_BLOCKED != TASK_BLOCKED.

This release does not change WorkIdentity, MongoDB schema, assurance states, or the LOCAL_HOST trust model.

v0.3.20 — Correctness Recovery

v0.3.20 is a narrow correctness release driven by adversarial evaluation of v0.3.19. It does not add a new subsystem.

Core changes:

• Project, Family and per-Family Slice identities are enforced atomically with production/test-store uniqueness parity. Concurrent enter_work calls can no longer materialize parallel logical identities for the same admitted task.

• Prompt text is no longer treated as durable WorkIdentity. A normalized prompt fingerprint is only an admission/deduplication hint. Existing matches return EXISTING_WORK_CANDIDATE; continuation requires an explicit work_ref.

• Read paths are projections only. status() no longer writes families.current or project_views; materialized views are refreshed on mutation paths. Workspace admission lookup uses direct Project bindings plus a bounded legacy fallback instead of recursive project_overview/status projection.

• LOCAL_HOST is documented honestly as COOPERATIVE_HOST, not a tamper-resistant verifier boundary. Direct same-host/MongoDB writers are inside that trust boundary. The aggregate MANGOME_RUNTIME_ROLE=FULL privilege shortcut is removed.

• Release tests are aligned with the current LOCAL_HOST/semantic-worker architecture, and CI includes a real MongoDB integration job for concurrency and persistence checks.

The central invariant remains unchanged:

DONE_CLAIMED != VERIFIED

But in LOCAL_HOST the separation is a governed workflow property, not proof against hostile direct database mutation. Strong service-isolated verification requires a future deployment boundary and is not claimed by v0.3.20.

v0.3.19 — Compact Human Folder Status

v0.3.19 adds a deliberately small, deterministic human-facing workspace view without creating another source of truth.

The normal worker can request:

mangome_status(scope="WORKSPACE", payload={"human": true})

The result is a display-only summary designed for people rather than agents. It reports only the information needed to understand roughly what MangoMe sees:

MangoMe · workspace
HEALTH      OK
WORKSPACE   KNOWN
DISCOVERY   EXACT · indexed files · no scan triggered
CONTRACTS   known · local · canonical · current / drifted / missing
WORK        active · verified · blocked
WARNINGS    none
FOLDERS
  contracts/  files · contracts · current
  src/        files
  tests/      files

The view is intentionally dumb:

• no LLM call;

• no semantic reconstruction;

• no new canonical state;

• no automatic discovery or structural scan;

• no Contract bodies, Evidence payloads, entity IDs, WorkTurn IDs, actor IDs or hashes;

• no duplication into MAC/1, PCH/1 or UAI/1.

Folder counts reuse the process-local SIM/1 structural cache when it already exists. Contract status is aggregated from canonical MangoMe state and bounded local bindings: known, canonical, current, drifted, or missing. Full machine detail remains available through the existing technical status/query paths when explicitly requested.

v0.3.18 — Bounded User-Intent Execution Authority

v0.3.18 removes an over-strict requirement from ordinary work admission while keeping privileged authority boundaries intact.

For an already-admitted workspace, an explicit current user request may enter bounded ordinary execution without requiring a separate external control-plane actor solely to create the EXECUTE turn.

explicit current user intent
        ↓
existing admitted workspace
        ↓
task-specific WorkIdentity
        ↓
EXECUTE WorkTurn

This authority remains deliberately narrow. It does not grant verification, normative mutation, control, owner acceptance, or routing authority. Existing assurance and privileged-transition boundaries remain unchanged.

v0.3.17 — KeyFile-Safe Zero-Touch LOCAL_HOST

v0.3.17 closes the concrete blocker observed on the managed host after v0.3.16: the local MongoDB service uses security.keyFile. v0.3.16 correctly refused to delete or weaken an unknown cluster/member-authentication mechanism, but that made the promised zero-touch activation stop before MangoMe could become operational.

The supported migration is now topology-preserving:

prove live MongoDB listener is loopback-only
        ↓
inspect active mongod security configuration
        ↓
security.keyFile absent
    → security.authorization: disabled

security.keyFile present
    → KEEP security.keyFile unchanged
    → KEEP replication / clusterAuthMode unchanged
    → security.transitionToAuth: true
        ↓
backup mongod.conf
restart mongod.service once
        ↓
prove loopback-only listener again
        ↓
anonymous LOCAL_HOST ping/list/index readiness
        ↓
remove obsolete MangoMe credential residue
        ↓
READY

MongoDB documents transitionToAuth as a transition mode that accepts authenticated and unauthenticated connections and does not enforce user access controls while an internal authentication mechanism such as a keyFile remains available for member authentication. MangoMe uses that behavior only after proving the listener is loopback-only. It never removes the keyFile, rewrites replica-set membership, edits dbPath, opens MongoDB to the network, or touches unrelated databases.

Command-line --auth/--keyFile/--clusterAuthMode remain fail-closed because MangoMe will not rewrite a systemd service command line implicitly. X.509/cluster-only security without a keyFile also remains fail-closed.

v0.3.16 — Zero-Touch LOCAL_HOST Activation & Cleanup

v0.3.16 closes the remaining deployment gap between the credential-free LOCAL_HOST design and an older host that still runs MongoDB with authorization enabled. The managed root runtime can now complete the one-time transition itself instead of returning an operator checklist.

The zero-touch sequence is deliberately narrow and fail-closed:

remove obsolete MangoMe credential/binding residue
        ↓
prove configured MongoDB endpoint is loopback
        ↓
prove the active TCP listener is loopback-only
        ↓
if authorization is still enabled:
    backup /etc/mongod.conf
    change only security.authorization -> disabled
    restart mongod.service once
        ↓
prove loopback-only listener again
        ↓
anonymous ping/list access
        ↓
ensure canonical MangoMe indexes
        ↓
READY

MangoMe does not edit firewall/network configuration, dbPath, unrelated MongoDB settings, other databases, MongoDB users/roles or application credentials. A non-loopback listener, clustered/key-file security configuration, command-line --auth, unsupported service manager, non-root runtime, or ambiguous mongod.conf stops the migration before authorization is weakened.

The old v0.3.12/v0.3.13 credential lifecycle is now treated strictly as cleanup residue in LOCAL_HOST. Exact obsolete MangoMe files (mongodb-uri, mongodb-maintenance-uri, database-binding.json) and the corresponding legacy MangoMe environment bindings are removed before readiness. Managed Codex/Claude setup then rewrites only the MangoMe MCP block from the clean credential-free environment.

The explicitly confirmed total reset remains scoped to exactly mangome and mangome_uai_eval. It now invokes the same zero-touch readiness path first, so an authorized reset does not require a separate manual host-migration ritual. Legacy databases remain schema-drift fail-closed and are never adopted, repaired or migrated.

v0.3.15 — Native Agent Context Compilation

v0.3.15 moves capacity-aware worker-context compilation into MangoMe itself. CogC remains a separate experimental project; MangoMe does not add a CogC runtime dependency or copy CogC as a second subsystem. Instead, MangoMe adopts the relevant design principles at the canonical-state boundary where it already knows Contract generations, PCH residency, Specifications, Slices, Evidence and truth.

The execution path is now:

canonical Contract generation in MongoDB
        ↓
deterministic clause projection
        ↓
PCH/1 resident Contract selection
        ↓
MAC/1 worker-context compiler
        ↓
capacity-specific cognitive package
        ↓
UAI/1 / normal worker transport
        ↓
agent

The full Contract body remains in the canonical contract_generations collection and in its human-readable local artifact. Routine agent context does not reread the complete local Contract file. MAC/1 reads the current canonical MongoDB generation, projects stable clause handles with source spans and hashes, keeps the critical/relevant text in the worker package, and leaves omitted text outside the active context.

MAC/1 uses deterministic C0–C3 criticality for this release. Explicit Specification constraints, out-of-scope boundaries, acceptance criteria, required Evidence, Slice gates and normative Contract language become worker units. C0/C1 units are never dropped merely to satisfy a model budget. If the critical set itself exceeds the configured capacity, MangoMe reports SPLIT_OR_ROUTE_LARGER_CONTEXT instead of silently truncating normative truth.

Omitted material is represented only by metadata handles such as generation id, clause span and content hash. The omitted text is not embedded behind the handle, avoiding the common failure mode where a supposedly compressed JSON package still contains the full source text.

Target profiles are deployment hints, not model-quality claims. v0.3.15 includes deterministic profiles for generic-small-agent, qwen-4b, qwen-9b, and frontier-specialist, selectable through MANGOME_AGENT_CONTEXT_PROFILE; the token envelope can be overridden through MANGOME_AGENT_CONTEXT_TOKEN_BUDGET. Canonical truth and mutation authority remain independent of that profile.

The trust split is explicit:

MangoMe canonical state  = what is true / binding
PCH/1                    = what is currently resident/relevant
MAC/1                    = what this worker should see
UAI/1                    = how the projection is transported
worker                    = reason / act within existing authority

MAC/1 creates no second truth store, no new authorization layer and no model inference dependency. Contract generation integrity remains fail-closed: a missing, non-canonical or hash-mismatched current generation blocks the clause projection rather than being reconstructed from a local file or agent memory.

v0.3.14 — LOCAL_HOST Trust, Credential Removal & Legacy Schema Fail-Closed

v0.3.14 removes the credential-recovery deadlock from the managed single-host deployment profile.

On a host where that authority did not exist, MangoMe could fail closed without being able to restore its own runtime database access. That was not an acceptable zero-touch outcome for the intended single-host deployment.

The v0.3.14 managed-local model is intentionally simpler:

Linux host / firewall boundary
        ↓
MongoDB bound to loopback only
        ↓
MongoDB authorization disabled
        ↓
MangoMe uses mongodb://127.0.0.1:27017
        ↓
canonical database = mangome

For this profile MangoMe has no MongoDB principal, password, role, credential file, maintenance identity or credential-adoption lifecycle. The host is the trust boundary. This mode is appropriate only when MongoDB is strictly loopback-only and local host processes are inside the deployment trust boundary. It must not be used for a remotely reachable MongoDB listener or an untrusted multi-user host.

The destructive reset path remains tightly bounded:

explicit confirmation
        ↓
verify LOCAL_HOST + loopback + authorization disabled
        ↓
exact allowlist only:
  mangome
  mangome_uai_eval
        ↓
drop exact targets
        ↓
recreate mangome indexes
        ↓
verify every non-target database name is unchanged

No wildcard matching, systemctl stop/start/restart, temporary --noauth process, dbPath access, MongoDB user creation or role provisioning occurs inside MangoMe.

Starting with v0.3.16, a managed root runtime may perform the narrowly bounded one-time LOCAL_HOST authorization transition automatically after proving that the active MongoDB listener is loopback-only. MangoMe still never edits firewall/network configuration or dbPath.

v0.3.13 — P0 Shared-MongoDB Safety Repair

We are sorry for the v0.3.12 reset-path defect. On hosts where MangoMe shares one MongoDB service with other applications or databases, the earlier recovery/reset implementation could stop and restart that shared mongod service and could treat mangome_* as a destructive database scope. That was unsafe for multi-database deployments and could interrupt unrelated workloads.

v0.3.13 makes the boundary explicit and fail-closed:

• mangome database-reset is installed through the real src/mangome package and is available from the normal mangome CLI.

• Accidental root-level shadow modules from the broken hotfix (__init__.py, cli.py, database_admin.py, worker_cli.py, zero_touch.py) are not part of the package and must be removed from the repository root.

• The destructive database allowlist is exact: only mangome and mangome_uai_eval are reset targets. No wildcard or prefix matching is used.

• The reset never stops, starts or restarts the shared MongoDB service, never launches a temporary --noauth MongoDB process, and never touches MongoDB data files directly.

• The reset requires already-available online maintenance authority before the first database mutation. If that authority is unavailable, it aborts before changing MongoDB.

• The fresh runtime principal is mangome_runtime with exactly readWrite on mangome; no admin, root, cluster-wide or global runtime role is created.

• Managed runtime credentials and the persisted database binding are updated only after the fresh runtime user has been verified.

• Automatic local root provisioning is disabled by default so ordinary zero-touch bootstrap cannot stop a shared MongoDB service merely because MangoMe runs as root. Explicit operator opt-in remains possible.

For installations using multiple databases on one MongoDB service, v0.3.13 should be treated as the minimum safe release for the destructive MangoMe database-reset path.

v0.3.12 — v0.3.11 Repair & External Enforcement Boundary

v0.3.12 is intentionally a repair-and-boundary release. It keeps the seven-tool worker facade introduced in v0.3.11, but restores semantic access to all 100 pre-existing advanced MangoMe capabilities. The worker therefore gets a small tool-selection surface without losing admission, WorkIdentity, Plan, Contract, truth, UAI/context, filesystem/discovery, FJD, runtime/delegation, evidence/verification or maintenance functionality.

Structural Intelligence is also hardened against the Python binding variants present in current tree-sitter-language-pack 1.x. The adapter prefers the package's configured parser, tolerates str/bytes and node API differences, and falls back to bounded text parsing rather than turning parser failure into a MangoMe-wide blocker. Structural context remains derived observation only. It is advisory beside PCH/1 and SRA/1; it does not rewrite PCH temperature, the persisted SRA frontier, truth, Evidence or mutation authority.

v0.3.12 also makes the physical runtime boundary explicit without embedding a sandbox into MangoMe:

MangoMe execution_eligibility / authorize_delegation
        -> host-side enforcement policy
        -> worker execution
        -> host audit / outcome reference
        -> record_execution_receipt metadata
        -> Evidence / AV/1 when independent verification is required

The existing execution-receipt metadata field is sufficient for backend/version/policy/audit references, so no schema or second runtime state machine is introduced. The worker must not widen its own filesystem, network, command, credential or tool policy. External enforcement and security-scanner results remain observations or judgments until MangoMe's existing evidence/verification rules establish more.

No HMAC or cryptographic mutation journal is introduced in v0.3.12. There is no MangoMe key lifecycle, no integrity secret and no hidden crypto dependency in this release. External sandboxes/firewalls/eval frameworks remain external components to be evaluated independently before any tighter integration.

Managed-runtime readiness is also zero-touch: the first canonical database access automatically runs the bounded credential-adoption/index-bootstrap path when the MCP process is launched from a managed MangoMe binding. mangome setup remains useful for explicit configuration/repair, but it is no longer a prerequisite for ordinary managed MCP use. Bootstrap success/failure is attempted once per process and reported through HEALTH as sanitized database_bootstrap state.

See docs/worker-facade.md, docs/structural-intelligence.md, docs/runtime-enforcement.md, and docs/v0.3.12-release-notes.md.

v0.3.11 — Structural Intelligence, Small Worker Surface & Graceful Cognition

v0.3.11 adds SIM/1 Structural Intelligence as a lazy, bounded and derived workspace map. Structural observation can identify symbols, relations, relevant files and bounded impact candidates, but it never becomes canonical truth, Evidence, Assurance, authority, WorkIdentity or normative baseline. Bootstrap performs no structural scan; parsing/indexing happens only on explicit structural operations or when bounded structural context is requested.

The normal MCP worker surface is reduced to exactly seven semantic operations:

mangome_status
mangome_observe
mangome_query
mangome_work
mangome_effect
mangome_verify
mangome_control

The existing precise capability surface remains available through mangome.mcp_server / mangome-mcp-advanced. The small facade routes deterministically to those capabilities and returns explicit disposition, recommended_next_action, allowed_next_actions, forbidden_next_actions, and reason_codes, so a weak worker does not need to understand MangoMe internals before acting safely.

Structural context can assist ContextCompiler, PCH relevance and SRA inspection-frontier selection, but cannot expand mutation authority. Structural/parser failure returns STRUCTURAL_CONTEXT_UNAVAILABLE and remains non-blocking. Context pressure degrades from optional structural detail to bounded/minimal viable context before cognition becomes unavailable. Truth/effect mutation gates continue to fail closed.

See docs/structural-intelligence.md, docs/worker-facade.md, and docs/v0.3.11-release-notes.md.

v0.3.10 — Persistent Effect Reconciliation & Slice Closure Semantics

v0.3.10 extends the existing v0.3 WorkIdentity control plane without replacing MangoMe's execution/assurance model. Worker completion is no longer treated as Slice completion: DONE_CLAIMED opens validation, validation may return REWORK_REQUIRED or INCONCLUSIVE, independent AV/1 verification remains separate, and CLOSED is reached only after verification and after every required external effect has been reconciled and satisfied. ACCEPTED remains a separate owner/business decision.

Relevant external effects use PER/1 — Persistent Effect Reconciliation. MangoMe persists durable intent before dispatch, records dispatch attempts and observations, preserves UNKNOWN instead of guessing failure, and reconciles observed external reality before closure. This deliberately does not claim a global ACID transaction across MongoDB, filesystems, APIs, deployments, mail or other external systems.

The architecture is expressed as layers — Domain/Intent → Work/Slice → Validation → Independent Verification → Effect/Reconciliation → Deterministic Enforcement. These are authority/state boundaries, not a requirement that each layer already has its own agent. Specialized layer agents remain a later composition concern.

See docs/agent-os-layer-model.md and docs/effect-reconciliation.md.

v0.3.9 — Observation routing & Codex integration hardening

v0.3.9 closes the live integration failures exposed after v0.3.8. Observation-only commands now stay observation-only: an explicit discover PATH performs one bounded candidate scan for exactly that path and stops. Traversal is bounded by file/depth limits and prunes excluded private/cache/build trees before descent. It does not run IntakeGov, assignment reconciliation, session restore, WorkIdentity admission, runtime eligibility, or candidate reconciliation unless the user explicitly asks for those transitions. bigbang_scan is persistence-free, Git inspection is opt-in, result payloads are bounded, and large reconciliation is available through server-side reconcile_bigbang_scan rather than round-tripping hundreds of records through model context.

Runtime capability governance is also narrowed to its intended boundary. RUNTIME_PROFILE_REQUIRED is a dispatch/host-capability signal, not a blocker for ordinary local reading, reasoning, discovery, or already-authorized execution. The response now states that scope explicitly so a worker does not stop normal work or attempt to self-publish a privileged runtime profile.

Codex managed integration is now user-scoped for the MCP binding, MangoMe Skill, and the small always-on activation rule, so MangoMe does not depend on Codex project-catalog registration. The always-on rule explicitly loads the installed MangoMe SKILL.md before MangoMe work instead of relying only on heuristic Skill selection. Explicit workspace arguments override stale process-global read-only bindings, while canonical rebinding remains fail-closed when multiple compatible workspaces exist. Release checks also tolerate absent optional repository-local Skill mirrors and keep the packaged canonical Skill authoritative.

explicit observation
    → direct bounded observation tool
    → result
    → STOP

productive effect
    → reconcile_assignment
    → governed work

external delegation / capability-sensitive host action
    → execution_eligibility
    → authorize_delegation

v0.3.8 — Codex Skill Discovery & canonical workspace rebinding

v0.3.8 fixes two integration failures found during live Codex operation. First, Codex now receives the MangoMe Agent Skill in the user-scoped location ~/.codex/skills/mangome/SKILL.md, so Skill discovery no longer depends on the current workspace being present in Codex's saved-project catalog. Managed attestation reports SKILL_NOT_INSTALLED or SKILL_VERSION_MISMATCH when that surface is absent or stale.

Second, canonical recovery no longer equates an exact workspace-path hash miss with missing MangoMe state. MangoMe first tries the exact deterministic workspace identity. If that misses, it may rebind read-only to exactly one compatible canonical workspace already persisted in the configured MangoMe database. This resolution uses only canonical MangoMe workspace identity; it never searches host memory, old contracts, Git history, or the filesystem and never creates replacement state.

current cwd / workspace path
        ↓
exact canonical workspace key
        ↓ miss
existing canonical MangoMe workspace identities only
        ↓
1 compatible candidate → CANONICAL_REBOUND
>1 candidates          → STATE_PARTIAL / WORKSPACE_BINDING_AMBIGUOUS
0 candidates           → STATE_NOT_FOUND

Restore and reconciliation results now expose sanitized database_binding and workspace_resolution diagnostics so an operator can distinguish a wrong database from a wrong workspace identity in one call.

v0.3.7 — deterministic runtime database binding

v0.3.7 makes database identity deployment state rather than agent-discovered state. Fresh managed installations default to the local database mangome, but upgrades preserve a verified existing MangoMe database identity instead of silently switching to a new default. A historical name such as mangome_uai_eval may therefore remain the active deployment database when zero-touch proves that it is the existing durable state. Database rename/copy/migration is never implicit. health() exposes process readiness, database readiness and the effective sanitized database binding, while managed MongoDB timeouts prevent a stale or unreachable binding from producing multi-minute startup loops.

v0.3.6 — bitemporal truth + hardened MongoDB trust boundary

v0.3.6 closes the two remaining core gaps identified after the v0.3.x architecture review. BTTM/1 adds non-destructive bitemporal truth maintenance (valid_time vs known_time) with support/assumption/dependency invalidation and PCH revalidation heating. MTB/1 adds an optional fail-closed production trust-boundary profile so canonical MongoDB credentials can live behind a dedicated MangoMe service identity instead of in worker-visible environment/configuration. See docs/bitemporal-truth-maintenance.md and docs/trust-boundary.md.

v0.3.5 — out-of-band control-plane self-maintenance

v0.3.5 closes a real control-plane deadlock found during live Codex operation. An explicit operator request to update/repair MangoMe itself must not require enter_work, a new WorkIdentity, or a self-approval persisted into the same MangoMe control plane being repaired. reconcile_assignment now returns the read-only CPM/1 disposition for explicit MangoMe self-maintenance and short-circuits canonical restore/admission.

CPM/1 is deliberately narrow: it covers only MangoMe source/package/runtime/service maintenance named by the current user. For an explicit install/update/repair request, and for normal managed-runtime readiness, the zero-touch path may adopt an existing MongoDB credential source, preserve a verified existing deployment database identity, and run idempotent ensure_indexes() for MangoMe's declared indexes. Fresh installations default to mangome; upgrades never rename, copy, migrate, or replace an established database merely to normalize its name. Managed runtimes invoke that bounded bootstrap automatically on first database access; it is not treated as a canonical domain/schema migration and does not require a separate mangome setup step. CPM/1 still does not authorize MongoDB user/role changes, registered schema migrations, canonical domain-document mutation, business-data repair, or an explicit database-identity migration; those require separate authority and otherwise stop with DATABASE_CHANGE_REQUIRED. If no reusable database authority exists, runtime/setup stops with BOOTSTRAP_AUTHORITY_REQUIRED.

v0.3.4 — non-blocking bootstrap / lazy discovery hotfix

v0.3.4 fixes a real-world zero-touch failure found during a Codex/MCP run: an explicit session_bootstrap on an unbound workspace could fall through to full workspace attachment, which may perform filesystem inventory and candidate Big-Bang discovery. That made a read-only bootstrap capable of blocking for minutes.

Binding and discovery are now separate operations. Managed startup creates only a volatile READ_ONLY_FAST_PATH workspace binding. No filesystem scan, Big-Bang scan, Git archaeology, or canonical mutation occurs merely because MangoMe starts or a worker requests restore/reconciliation. Canonical restore is lazy at the recovery/effect boundary, while full discovery remains explicit through refresh/onboarding operations.

The operational invariants are:

MANGOME_MUST_NOT_BLOCK_COGNITION
BINDING_IS_NOT_DISCOVERY
BOOTSTRAP_PERFORMS_NO_FILESYSTEM_SCAN
BINDING_FAILURE_BLOCKS_EFFECTS_NOT_REASONING

workspace_status(refresh=True) remains available when a host/operator explicitly wants a full attachment/discovery refresh.

v0.3.3 — zero-touch assignment reconciliation

v0.3.3 removes the worker-facing restore-first ritual from the normal managed workflow. A worker may inspect, search, reason, classify and form a tentative decomposition before MangoMe involvement. MangoMe becomes mandatory at the effect boundary, not at the first thought.

user request
    ↓
free local understanding / tentative decomposition
    ↓
reconcile_assignment
    ↓
existing WorkIdentity / baseline / unfinished state / authority
    ↓
governed productive effect

The governing rule is THINK FREELY, RECONCILE BEFORE EFFECT. Managed clients bind the workspace through a cheap read-only fast path when MangoMe initializes; canonical restore is resolved lazily when reconciliation/recovery or an effect gate actually needs it. Workers therefore do not call session_restore merely because a session started. session_restore remains the explicit recovery/status primitive, while reconcile_assignment is the normal worker-facing bridge from tentative judgment to governed work.

The effect boundary includes durable code/file/database mutation, commits, deployment, external side effects, canonical MangoMe mutations, normative promotion and assurance claims. Tentative reasoning is never promoted automatically, and existing work is still reused before new work is admitted.

v0.3.3 also adds FJD/1 Fast Judgment Decisions, a deliberately small provider-neutral typed-decision layer for cheap repeated judgments. It accepts strict BOOL, SCORE, and CHOICE outputs with explicit confidence and returns USE_SIGNAL, REVIEW, REVIEW_REQUIRED, or ESCALATE. FJD/1 performs no model inference itself; a host may use a heuristic, small local classifier, specialized decision engine, or stronger model. Every result remains WORKER_JUDGMENT: confidence can guide classification, triage, routing, activation, or prioritization, but can never create truth, Evidence, assurance, verification, acceptance, normative promotion, or mutation authority. See docs/fast-judgment.md.

v0.3.2 — scoped recursive audit and impact closure

v0.3.2 adds SRA/1, a bounded recursive audit layer for the normal engineering reality that a worker is competent inside a local assignment but does not and should not need to understand the entire system before acting.

initial scope
    ↓
inspect current frontier
    ↓
persist finding / evidence / assumptions / unknowns
    ↓
material impact?
  no → frontier shrinks
  yes → follow bounded confirmed relations
    ↓
repeat until fixpoint or explicit boundary

SRA/1 separates knowledge, inspection, mutation, and assurance boundaries. The inspection frontier may grow when a finding has material impact; the mutation scope is frozen at audit start and never grows automatically. A closed audit therefore means only that the configured impact frontier has reached FIXPOINT_REACHED or BOUNDED_FIXPOINT. It never means the entire system is correct or that the audited object is VERIFIED.

The active audit frontier is supplied to PCH/1 as additional cognitive roots, so the worker receives the currently relevant impact region without loading the entire historical graph. See docs/scoped-recursive-audit.md.

v0.3.1 — persistent cognitive hygiene and thermal working sets

v0.3.1 adds a deterministic homeostasis layer above MangoMe's durable v0.3 work graph and below the existing ContextCompiler. It does not create another memory system. Canonical MongoDB state remains the historical record; PCH/1 computes only which objects should be cognitively resident for the present task.

Persistent canonical history H_t
        ↓
PCH/1 Cognitive Hygiene
  graph reachability + task relevance
  + authority + freshness + support
        ↓
Bounded active working set A_t
  HOT / WARM / COLD
        ↓
existing ContextCompiler
        ↓
worker / UAI context C_t

The central invariants are:

temperature != truth
temperature != assurance
COLD != deleted
|C_t| <= B_context
|A_t| <= B_active
H_t remains historically recoverable

HOT, WARM, and COLD are buckets over a continuous task-relative temperature in [0,1]. Current canonical execution roots are pinned. Superseded or historical state normally cools, but a targeted historical query can reheat it for inspection/revalidation without restoring normative authority. The GC analogy is deliberately non-destructive: PCH/1 borrows reachability, generations and residency pressure, but "collection" only removes objects from the active worker set.

The full diagnostic surface is available through cognitive_hygiene; normal worker execution receives only the bounded selection summary through ContextCompiler and UAI/1.

v0.3.0 — durable WorkIdentity, progressive persistence, and playbook isolation

v0.3.0 changes MangoMe's primary architectural anchor. Contracts and Specifications remain important normative inputs, but they no longer define the identity of the work. Playbooks remain procedural inputs and are explicitly non-normative.

Playbooks may change.
Specs may evolve.
Workers and sessions may disappear.
The identity of the work and its assurance history must survive them all.

The governing model is:

Intent-first
    ↓
Identity-bound
    ↓
Playbook-guided
    ↓
Spec-governed
    ↓
Assurance-preserving

MangoMe now separates three persistence levels:

VOLATILE
  selected Playbook body / transient execution context

PROGRESSIVE
  crash-recovery checkpoint / working cursor / non-normative selection state

CANONICAL
  WorkIdentity / NormativeBaseline binding / Plan authority / Evidence / Claims / Assurance history

A prompt may admit a durable WorkIdentity, but it does not automatically become a Specification or Contract. Productive Plans are bound to the current immutable NormativeBaseline; if the effective Spec/Contract truth changes, an older Plan stops with BASELINE_DRIFT rather than silently inheriting the new target.

Playbooks are deliberately weaker than canonical state:

Playbook = HOW work is normally performed
Specification = WHAT must become true
MangoMe = WHAT survives: identity, persistence, provenance, execution binding, and independent assurance

The hard recovery rule is therefore:

filesystem / Git / Playbook / prior agent prose
        ↓
may guide or corroborate
        ↓
MUST NOT reconstruct WorkIdentity, current normative truth, or assurance

For managed MCP operation, explicit current user intent may admit bounded ordinary EXECUTE work even when canonical workspace state already exists. Recovered state remains context rather than privileged authority. Verification, normative mutation, control, owner acceptance, and routing remain separately protected. Direct library use remains a lower-level integration boundary and must be isolated from untrusted workers in high-assurance deployments.

The ContextCompiler and UAI projection now expose the persistence boundary explicitly so canonical identity/assurance survives context reduction while volatile Playbook material is trimmed first.

v0.2.2 — execution integrity hardening

v0.2.2 is a hardening release built on the v0.1.9rc4 baseline.

The release addresses an observed failure mode: an agent received an audit assignment, but instead of performing the audit it generated a large new audit/planning artifact and presented that planning output as the result.

MangoMe must allow agents to organize work internally without allowing planning to replace execution.

The v0.2.2 execution rule is therefore:

USER ASSIGNMENT
      ↓
RESTORE CANONICAL STATE
      ↓
RELEVANT SLICES EXIST?
   ┌───────────────┴───────────────┐
  YES                              NO
   ↓                                ↓
REUSE EXISTING                MATERIALIZE MINIMUM
SLICES                        INTERNAL SLICE(S)
   └───────────────┬───────────────┘
                   ↓
              EXECUTE WORK
                   ↓
             OBSERVE REALITY
                   ↓
            PERSIST EVIDENCE
                   ↓
        RECONCILE EXPECTED/ACTUAL
                   ↓
          REPAIR / ADAPT IF NEEDED
                   ↓
              RE-OBSERVE
                   ↓
             CLAIM COMPLETION
                   ↓
          INDEPENDENT VERIFICATION

The user should receive the result of the assignment, not MangoMe's internal decomposition.

Contract-first turn binding and immutable generations

MangoMe treats the current user turn and the recovered work state as different things. Restored ACTIVE work is durable context, not an instruction to continue it. For admitted contract work, an agent first binds the current turn to the intended logical Contract with one of six modes: QUERY, CONTINUE, EXECUTE, VERIFY, MODIFY, or CONTROL.

The recovery priority is therefore:

CURRENT USER TURN
    ↓
EFFECTIVE CONTRACT / SPECIFICATION
    ↓
OBSERVED ARTIFACTS / EVIDENCE
    ↓
UNRESOLVED DELTA
    ↓
DERIVED PLAN / SLICE STATE

Plans and Slices remain durable and useful, but they are execution decomposition rather than normative truth. An active Slice never authorizes the current turn by itself.

Contract bodies can exist in more than one physical location. MangoMe keeps the logical Contract identity separate from those locations and can persist immutable canonical generations of the normative body in MongoDB. A local or Git/DMS copy may change, but that changed file is only an observation until an explicitly bound MODIFY turn promotes it.

Promotion is single-writer and compare-and-swap protected. A generation grant is bound to the Contract, actor, current turn, base generation, and base content hash. Only that grant may create the next immutable generation; concurrent or stale promotion fails closed instead of merging or overwriting silently.

This gives the intended asymmetry:

logical Contract          durable identity
canonical generations    immutable normative history
physical files            mutable working representations / bindings
Plans and Slices          derived execution state

The key invariants are:

MangoMe context never substitutes for current user intent.

A changed contract file is not canonical truth until the authorized MODIFY turn promotes a new generation.

Slices are internal execution state

Slices are durable execution addresses, not normal user-facing deliverables.

For an admitted assignment:

• if suitable Slices already exist, MangoMe reuses them;

• it does not create replacement Slices merely because a new session or agent started;

• if an admitted Family genuinely has no Slice, MangoMe may materialize the minimum internal Slice needed to execute the assignment;

• internal Slice/Plan details are not normal human-facing output;

• a user does not need to ask for, manage, name or approve ordinary internal Slices.

The new prepare_assignment surface exists for this execution path.

prepare_assignment
    ↓
reuse existing Slice(s)
OR
materialize minimum internal Slice
    ↓
create/bind Plan
    ↓
start executable target(s)

It returns internal execution bindings for the client/worker, while the presentation policy explicitly marks Slice details as internal.

Planning is not execution

For audit, review and verification work, a checklist, plan, specification or newly authored contract is not a substitute for executing the requested work.

An audit-like assignment cannot reach DONE_CLAIMED merely because the worker produced planning prose. The Slice must have persisted non-claim Evidence demonstrating that observation actually occurred.

This closes the failure pattern:

AUDIT REQUEST
    ↓
WRITE AN AUDIT PLAN
    ↓
CLAIM SUCCESS

The valid path is:

AUDIT REQUEST
    ↓
OBSERVE
    ↓
EVIDENCE
    ↓
FINDINGS / DELTA
    ↓
OPTIONAL REPAIR
    ↓
RE-OBSERVE
    ↓
DONE_CLAIMED

Observe before repair

Audit/reconciliation work first establishes the delta between normative and observed state. Repair, adaptation or correction is a subsequent action where the assignment permits mutation.

A read-only audit remains read-only.

A repair-capable assignment may continue from findings into correction, but it must not silently rewrite normative Contract/Specification truth merely to make implementation appear compliant.

Zero-touch operation

Zero-touch is a user-interface property, not a weaker truth model.

user gives a normal task
        ↓
worker understands / inspects / forms tentative decomposition
        ↓
reconcile_assignment
        ↓
STATE_FOUND | STATE_PARTIAL | STATE_NOT_FOUND
        ↓
STATE_FOUND   → reconcile with existing WorkIdentity/baseline/work
STATE_PARTIAL → bounded validation/backfill only
STATE_NOT_FOUND → never synthesize recovery state
        ↓
new work?       → enter_work
admitted work?  → bind current turn + prepare_assignment / begin_work
        ↓
Plan-bound internal Slice execution
        ↓
Evidence / claims / verification

The user should not have to say:

• “create a Slice”;

• “start Big Bang”;

• “call begin_work”;

• “create a Plan”;

• or otherwise operate MangoMe vocabulary manually.

The internal machinery remains strict even though the user-facing workflow is simple.

Restore is not creation

Recovery is identity-driven.

STATE_FOUND
STATE_PARTIAL
STATE_NOT_FOUND

STATE_NOT_FOUND is a real state. It does not mean “create replacement state and call it restored”.

For admitted work:

Recovery follows identity. Discovery must never create or reconstruct admitted identity/state.

Filesystem paths, Git/worktree history, contract folders, evidence folders and previous-agent prose may validate a bounded unresolved delta. They are not substitutes for canonical MangoMe state.

GOAL_ACTIVE or an unfinished Family does not itself grant execution permission. Productive work follows canonical executable items and active plan bindings.

MangoMe is infrastructure

Agents may use MangoMe but must not modify MangoMe source, tests, packaging or managed configuration unless the explicit assignment targets MangoMe itself.

A blocked application task, failed verification, missing state or runtime defect is not implicit permission to self-edit the governance substrate.

Hard filesystem/process enforcement remains a host/runtime responsibility.

This distinction is important:

application task fails
      ≠
permission to modify MangoMe

Canonical persistence and runtime binding

MongoDB remains MangoMe's production canonical store.

Production canonical persistence = MongoDB

v0.2.2 strengthens runtime binding because a correct state model is useless if different agents silently connect to different databases.

Managed client configuration now carries the expected database identity:

MANGOME_DATABASE
MANGOME_EXPECTED_DATABASE

For upgrade safety, zero-touch also persists a non-secret deployment binding under the managed MangoMe config directory after it has verified an existing database. That persisted binding can override a newer fresh-install default on later restarts. This is identity preservation, not cross-database migration.

If the configured runtime database does not match the expected managed database, initialization fails closed with:

WRONG_MANGOME_DATABASE

This is intentionally separate from source/version binding:

MANGOME_EXPECTED_VERSION
MANGOME_EXPECTED_SOURCE_ROOT
MANGOME_EXPECTED_DATABASE

The practical invariant is:

GitHub/source identity
        +
runtime package identity
        +
managed MCP target
        +
MongoDB database identity
        =
one intended MangoMe runtime

Direct worker access to MongoDB remains outside MangoMe's service trust boundary. Production deployments should isolate canonical database write credentials from untrusted workers.

Schema evolution fails closed on the future

MangoMe persists a schema_version on canonical documents.

Older known schema versions can be upgraded deterministically by registered migrations.

v0.2.2 adds the opposite boundary as well: an older reader must not silently interpret a future schema it does not understand.

persisted schema <= reader schema
    → normal read / migration path

persisted schema > reader schema
    → UnsupportedSchemaVersion

This protects mixed-version agent environments from quietly treating newer state as if it were older compatible state.

Hard context envelope

Canonical truth is never truncated merely to fit an agent prompt.

MangoMe instead compiles a disposable execution projection.

v0.2.2 adds a deterministic hard byte envelope to ContextCompiler:

ContextCompiler(service).compile(
    family_id,
    slice_id,
    max_bytes=...
)

The compiler follows a deterministic reduction policy when the projection exceeds the envelope:

1. preserve normative and active execution state;

2. compact optional Evidence payload detail;

3. compact optional Contract storage detail;

4. omit older optional Evidence entries where required;

5. fail closed if mandatory state itself cannot fit.

The failure is explicit:

ContextBudgetExceeded

The rule is:

Canonical truth is never compressed destructively. Only the execution projection is bounded.

MangoMe uses a byte envelope rather than pretending it can guarantee provider-specific token counts without the exact tokenizer. Provider-reported token counts continue to belong in Execution Receipts.

Work Graph query hardening

MangoMe does not introduce an in-memory graph truth store in v0.2.2.

Before adding a Change-Stream-driven DAG cache, the repository first removes avoidable broad reads.

Graph lookup now uses indexed edge predicates for incoming and outgoing relationships rather than reading the whole Edge collection and filtering in Python.

MongoDB indexes include the relevant directional access paths, including reverse to_id lookup and Evidence subject access.

The current decision is deliberate:

first: query/index correctness
then: measure
only then: consider an in-memory topology cache

A second live graph representation would add cache invalidation and runtime-consistency failure modes. That is not justified until profiling shows indexed MongoDB traversal to be a real bottleneck.

Core entities

MangoMe gives first-class identity to durable operational objects including:

Request
Project
Contract Family
Contract Contribution
Specification
Plan
Slice
Claim
Evidence
Artifact
Graph Edge
Approval
Model Profile
Execution Receipt
Materialized Status View

Every first-class entity has an immutable internal entity_id.

Human identifiers such as declared contract or Slice IDs may collide without silently overwriting history; ambiguity is surfaced rather than hidden.

Core invariants

1. Work identity is more durable than a session

A chat, prompt, branch or model invocation is not the identity of the work.

2. A prompt is not automatically Contract Truth

User intent may admit operational work. Durable normative contract evolution remains explicit and append-only.

3. Slices are durable internal execution addresses

Execution state and assurance state remain separate dimensions.

Execution examples:

PLANNED
STARTED
ACTIVE
PAUSED
BLOCKED
DONE_CLAIMED
CANCELLED

Assurance examples:

UNVERIFIED
PARTIAL
VERIFIED
ACCEPTED
REJECTED

A normal state is:

DONE_CLAIMED / UNVERIFIED

4. Existing Slices are reused

A new worker/session does not justify duplicate work decomposition.

When an admitted Family already contains relevant Slices, assignment preparation reuses them. Missing internal work structure may be created only where necessary for execution.

5. Plan before mutate

Productive mutations remain bound to a persisted Plan.

submit_plan / prepare_assignment
    ↓
start_slice(plan_id=P)
    ↓
update_slice_progress(plan_id=P)
    ↓
claim_done(plan_id=P)

6. DONE is a claim

worker: "done"
        ↓
DONE_CLAIMED
        ↓
independent Evidence / gates
        ↓
VERIFIED
        ↓
optional authorized acceptance
        ↓
ACCEPTED

DONE_CLAIMED != VERIFIED remains a core invariant.

7. Evidence is not automatically proof

Worker-authored Evidence can support work, but independent verification remains separately authorized.

Audit/review work in v0.2.2 must at minimum persist real observational Evidence before claiming completion; prose planning alone is insufficient.

8. Normative truth is not rewritten to fit implementation

If observed reality conflicts with the current Specification, that conflict is a finding. A worker may repair implementation where authorized or propose an amendment, but it may not silently redefine the requirement.

9. Parallelism is allowed; canonical writes are guarded

MangoMe does not globally serialize agents. It protects canonical document writes through revision / compare-and-swap semantics and surfaces collisions where useful.

Contract evolution

Contract contributions are append-only.

Supported relations include:

ADDS_TO
AMENDS
EXTENDS
REPAIRS
RECOVERS
SUPERSEDES
CONFLICTS_WITH
VALIDATES
IMPLEMENTS
PART_OF
EXPOSED_BY
RELATES_TO

effective_family_view resolves confirmed supersession and exposes conflict/suggestion state without silently merging ambiguous prose.

AV/1 — adversarial completion verification

MangoMe treats worker completion as a claim to inspect.

DONE_CLAIMED
    ↓
completion_review
    ↓
verifier observes / replays / inspects
    ↓
submit_verification_observation
    ↓
attested independent Evidence
    ↓
verify_slice
    ↓
VERIFIED

The verifier path is intentionally separate from worker execution.

A worker may not self-upgrade its completion claim into verified truth.

RB/1 — reproducible Evidence binding

Where Evidence should remain reusable, MangoMe can bind it to concrete execution inputs through RB/1.

A reproduction binding can include:

• command identity;

• caller-supplied exit code;

• relevant input hashes;

• Git commit context;

• output Artifact identity;

• stdout/stderr hashes;

• environment names without secret values;

• a deterministic fingerprint.

Freshness can later become REUSABLE, STALE, UNKNOWN, UNBOUND or INADMISSIBLE, but freshness never creates VERIFIED by itself.

UAI/1 — compact semantic transport

MangoMe can compile canonical state into a compact transport representation for expensive workers.

The key rule remains:

MangoMe does not compress canonical truth. It compiles a disposable execution projection of that truth.

UAI/1 packets include a semantic hash, and UAI/1R worker results bind back to that hash. Decoded results never directly mutate canonical state; actions still flow through normal MangoMe mutation, Evidence and verification paths.

Assignment surfaces

reconcile_assignment

Read-only RAE/1 bridge from tentative worker understanding to governed work. It resolves canonical restore state and returns whether the worker should reconcile with existing work, perform bounded recovery/backfill, or admit genuinely new work. It never canonicalizes the worker's tentative decomposition.

enter_work

Zero-touch admission for genuinely new ordinary work.

prepare_assignment

v0.2.2 execution-preparation surface for already admitted work.

It:

• classifies the assignment;

• uses the current effective Specification;

• reuses existing Slices;

• materializes a minimal internal Slice only when none exist;

• persists a Plan;

• binds executable targets to that Plan;

• exposes a presentation policy that keeps Slices internal.

It is specifically intended to prevent agents from replacing execution with a new user-facing planning artifact.

begin_work

Convenience composition for an already admitted Family/Specification when a specific bounded Slice is being started.

MCP tools

The normal v0.3.19 worker endpoint deliberately exposes only seven semantic tools: mangome_status, mangome_observe, mangome_query, mangome_work, mangome_effect, mangome_verify, and mangome_control. Each tool contains a typed, allow-listed sub-operation rather than exposing dozens of top-level choices.

The detailed capability surface remains available through the explicit advanced endpoint for operators, compatibility and internal integrations. That advanced surface includes:

Session / recovery
  health
  workspace_status
  reconcile_assignment
  session_restore
  session_bootstrap
  recovery_context

Intake / specification
  intake_request
  create_spec
  enter_work
  prepare_assignment
  begin_work

Identity / registry
  resolve
  create_project
  create_family
  register_contract
  import_contract_bundle
  attach_artifact
  link_entities

Planning / execution
  submit_plan
  start_slice
  update_slice_progress
  claim_done
  close_plan

Evidence / assurance
  submit_evidence
  attest_evidence
  completion_review
  submit_verification_observation
  set_gate
  set_gate_controlled
  verify_slice
  request_override
  approve_override
  reject_override
  list_approvals
  accept_slice

Read / truth
  status
  project_overview
  effective_family_view
  read_context
  compile_execution_context
  graph

Compact semantic transport
  compile_uai_context
  expand_uai_context
  decode_uai_result
  render_uai_result

Runtime / delegation
  publish_worker_runtime
  execution_eligibility
  authorize_delegation
  complete_delegation
  delegation_status

Fast judgment / decision gating
  assess_fast_judgment
  record_fast_judgment
  fast_judgment_status

Economics
  register_model
  record_execution_receipt
  model_stats

Discovery / maintenance
  discovery_scopes
  repository_locations
  bigbang_scan
  reconcile_bigbang
  filesystem_scan
  filesystem_references
  build_reproduction_binding
  evidence_freshness
  refresh_views
  maintenance_diagnose
  migrate_schema

Installation

Requirements:

• Python 3.10+

• MongoDB for canonical production persistence

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Managed client setup:

mangome setup --client auto

For Codex, managed setup installs all three MangoMe discovery surfaces user-scoped:

~/.codex/config.toml                 # MCP server binding
~/.codex/skills/mangome/SKILL.md    # MangoMe Agent Skill
~/.codex/AGENTS.md                  # small always-on activation rule

This keeps MangoMe available even when the current workspace is not present in Codex's saved-project catalog. The managed MCP entry still carries the intended workspace root and database identity; user scope only removes project-catalog discovery as a prerequisite. Existing unrelated user configuration is preserved.

Claude Code can use private LOCAL scope by default; project scope remains explicit:

mangome setup --client claude-code --claude-scope project

For deterministic local tests using the normal seven-tool worker facade:

export MANGOME_BACKEND=memory
mangome-mcp

For explicit advanced/internal compatibility use:

mangome-mcp-advanced

For canonical MongoDB persistence:

export MANGOME_BACKEND=mongo
export MANGOME_MONGODB_URI='mongodb://127.0.0.1:27017'
export MANGOME_DATABASE='mangome'
mangome-mcp

Managed clients generated by MangoMe additionally bind the expected database identity.

The default MCP transport is stdio.

Streamable HTTP can be enabled through the existing MANGOME_MCP_TRANSPORT, host and port variables.

Agent Skill

Canonical Skill source:

skill/mangome/SKILL.md

The canonical repository Skill is skill/mangome/SKILL.md; the packaged copy at src/mangome/skill/SKILL.md must be byte-identical. Repository-local .github / .claude mirrors are optional convenience surfaces when present. Managed Codex setup installs the canonical Skill user-scoped at ~/.codex/skills/mangome/SKILL.md and installs the matching user-level MCP binding and activation rule independently of the Codex saved-project catalog.

The Skill teaches the normal worker path:

• think freely and form only a tentative local decomposition;

• reconcile with MangoMe before productive effect;

• use reconcile_assignment instead of a ritual restore-first step;

• resolve/reuse existing WorkIdentity, plans and evidence before creating new work;

• keep Slice/Plan mechanics internal;

• use prepare_assignment for admitted assignments;

• planning is never a substitute for execution;

• audits must persist actual observation Evidence;

• observe the delta before repair;

• do not mutate MangoMe unless MangoMe itself is the assignment target.

Typical lifecycle

Ordinary new work:

understand locally
→ reconcile_assignment
→ STATE_NOT_FOUND for genuinely new work
→ enter_work
→ internal Plan/Slice execution
→ Evidence
→ claim_done
→ independent verification where required

Existing admitted work:

understand locally
→ reconcile_assignment
→ STATE_FOUND
→ bind current turn / prepare_assignment
→ reuse existing Slice(s)
→ execute
→ persist Evidence
→ reconcile
→ repair/adapt if authorized
→ claim_done
→ verify

Audit/review path:

reconcile_assignment
→ prepare_assignment
→ inspect actual system
→ persist observations
→ compare N vs O
→ findings
→ optional authorized repair
→ re-observe
→ DONE_CLAIMED

Repository structure

.
├── src/mangome/
│   ├── service.py            # canonical domain operations / assignment preparation
│   ├── integrity.py          # assurance and authority invariants
│   ├── hygiene.py            # PCH/1 thermal working-set / cognitive homeostasis
│   ├── context.py            # bounded execution context / hard envelope
│   ├── structural.py         # SIM/1 lazy structural observation / bounded map
│   ├── worker_mcp_server.py  # default seven-tool semantic worker facade
│   ├── worker_cli.py         # normal CLI bridge for managed worker bindings
│   ├── interlingua.py        # UAI/1 compile/decode/render
│   ├── importer.py           # Big-Bang discovery/reconciliation
│   ├── filesystem.py         # deterministic filesystem inventory / evidence freshness
│   ├── operability.py        # client bootstrap, identity/database binding, auto-attach
│   ├── maintenance.py        # deterministic diagnostics/migrations
│   ├── schema.py             # schema evolution / future-version fail-closed
│   ├── mcp_server.py         # advanced/precise MCP capability surface
│   └── storage/
│       ├── mongo.py          # canonical MongoDB backend / indexes / OCC
│       └── memory.py         # deterministic test backend
├── skill/mangome/
├── src/mangome/skill/
├── .github/skills/mangome/   # optional repository mirror
├── .claude/skills/mangome/   # optional repository mirror
├── docs/
├── examples/
├── tests/
├── pyproject.toml
└── server.py

Release-layout integrity

v0.2.2 also hardens the repository/package boundary itself. The executable Python package lives under src/mangome/; package modules must not be duplicated into the repository root. Version metadata in pyproject.toml, src/mangome/__init__.py, and the MCP server must agree. Regression tests fail if shadow copies such as root-level runtime.py, service.py, mcp_server.py, operability.py, or duplicate root Skill files appear.

MangoMe setup/doctor code is not a host-network manager. The release guard also rejects source changes that add direct management of resolver/network/firewall surfaces such as /etc/resolv.conf, systemd-resolved, Netplan, iptables/nftables, or UFW to the MangoMe runtime. Host-network repair is outside MangoMe's normal execution scope.

Deliberate v0.2.2 non-goals

v0.2.2 does not:

• replace MongoDB;

• add an in-memory DAG as a second graph truth;

• add MongoDB Change Stream cache synchronization;

• let workers self-verify;

• expose Slices as normal user-facing workflow;

• create recovery state when STATE_NOT_FOUND;

• automatically reinterpret a prompt as a durable Contract contribution;

• let planning artifacts count as execution Evidence;

• guarantee provider-specific token counts from byte budgeting;

• claim that external model dispatch enforcement exists unless the host actually binds to MangoMe authorization.

Current status

v0.3.19 keeps the v0.3.18 authority model and adds a compact display-only folder status for human operators. The view reuses already available structural state, reports aggregate Contract/current-drift health and work readiness, and deliberately omits internal IDs, hashes and Evidence payloads. It performs no automatic structural scan and creates no canonical state.

The current execution architecture is:

user intent
    ↓
seven-tool semantic worker facade
    ├─ status / observe / query → bounded read-only path
    ├─ work / effect            → existing governed mutation gates
    ├─ verify / control         → existing capability/authority gates
    └─ structural sight         → lazy derived observation only

productive work
    ↓
current WorkTurn + immutable NormativeBaseline
    ↓
canonical Project / Family / Spec / Plan / Slice / Evidence graph
    ↓
BTTM/1 supportability + SRA/1 bounded audit frontier (when applicable)
    ↓
PCH/1 thermal working-set selection
    ↓
ContextCompiler hard envelope
    ↓
UAI/1 or normal worker context
    ↓
execution / Evidence / DONE_CLAIMED
    ↓
independent verification
    ↓
VERIFIED / optional ACCEPTED

HOT/WARM/COLD remain task-relative cognitive residency, not truth or assurance. Bitemporal truth maintenance determines supportability over valid/known time; PCH/1 determines activation; the ContextCompiler determines what fits in the worker projection.

Important current limits

• SRA/1 closes bounded impact scope, not whole-system correctness. BOUNDED_FIXPOINT means configured depth/object limits prevented further traversal.

• Audit scope expansion never grants additional mutation authority; external code/filesystem enforcement remains a host/runtime responsibility.

• PCH/1 uses an explicit deterministic heuristic policy; its weights and thresholds are inspectable baselines, not a claim of optimal cognitive allocation.

• Temperature controls activation only. It cannot promote Evidence, change normative authority, verify a Slice, or accept work.

• BTTM/1 provides non-destructive valid-time/known-time truth assertions and revalidation propagation, but it is not a universal external-world temporal database or automatic fact-ingestion engine.

• FJD/1 confidence is advisory worker judgment only; high-impact decisions still require review.

• MangoMe can govern writes that pass through MangoMe, but direct database/admin access outside the service boundary remains outside its protection.

• External model dispatch and verifier command execution remain host responsibilities; MangoMe supplies deterministic policy/authorization state but is not the provider dispatcher.

• Managed Codex setup can make MCP + Skill + activation rule discoverable without project-catalog registration, but the host/client still controls whether the runtime actually starts and invokes them.

• Live MongoDB/MCP integration must still be verified in the deployment environment; deterministic local tests cannot prove the host's active process/database binding.

Product boundaries

MangoMe deliberately does not:

• treat every prompt as a contract;

• infer verification from a worker's DONE statement;

• automatically recover/replay a dead model session;

• serialize all project work behind a global lock;

• use an LLM for ordinary status calculation;

• silently canonicalize ambiguous discovery;

• infer implementation correctness from filesystem presence alone;

• let compact UAI output directly mutate canonical state;

• make an external reviewer a source of truth;

• promise interchangeable production persistence semantics;

• require Scrum, sprints or story points.

License

Apache License 2.0.

See LICENSE.

AI Transparency

This repository contains material created with or materially assisted by generative AI systems. This may include source code, documentation, examples, tests, specifications, project artwork, and other visual assets.

AI-generated or AI-assisted material should not be treated as independently verified solely because it appears in this repository. Visual assets may include AI-generated imagery used for illustrative or branding purposes unless explicitly stated otherwise.

This repository-level disclosure is provided for transparency, including with regard to applicable transparency requirements under the EU AI Act. It does not imply that every file or contribution was generated by AI, nor that every item is subject to a specific statutory labeling obligation.