Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/pretendhome/mission-canvas

Mission Canvas — Governed Agent OS. AI for work that can't leave the room.
https://github.com/pretendhome/mission-canvas

ai-agents governance governed-ai knowledge-architecture local-first multi-agent voice-ai

Last synced: 6 days ago
JSON representation

Mission Canvas — Governed Agent OS. AI for work that can't leave the room.

Awesome Lists containing this project

README 

          
# Mission Canvas



Local-first AI for private work. A map, a boundary, and a memory.



Mission Canvas is a Structured Knowledge Harness (SKH) — an information architecture that gives an LLM structured context before it reasons, instead of hoping it figures out what's relevant from a flat prompt.



> **"What does the model need from the system to do its best work?"**



## Why This Exists



Most AI tools treat the model as the whole system. You type a question, the model guesses what you need, and you hope it gets it right. Mission Canvas splits the work: the system classifies the problem, retrieves the right evidence, applies governance rules, and builds structured context. The model only reasons AFTER all of that is done.



Private workflows can stay on your machine. External research is gated and sanitized. Every interaction is logged as a traceable decision trail — not a chat log, a structural record of what was asked, what context was used, what boundary applied, and what changed.



## Four Ways to Use It



| Level | For | What You Get | Cost |

|-------|-----|-------------|------|

| **Use It Locally** | Anyone with a computer | Full system on your machine. No cloud, no account. | Free |

| **Add It To Your AI Tool** | Existing Claude/Cursor/Codex users | Paste one file. Your AI gets classification, governance, and audit trails. | Free |

| **Run The Full System** | Developers with API keys | Multi-model routing, governed pipeline, structural path records. | Free (BYOK) |

| **Adapt For Your Org** | Teams and enterprises | Custom ontology, compliance rules, domain knowledge. | Custom |



## Repository Layout



| Path | What lives there |

|------|------------------|

| `src/` | Pipeline, CLI, runtime engines |

| `ontology/` | Node graph, signals, weights |

| `dev/examples/` | Production domain canvases (25) |

| `lenses/` | Core, professional, role lenses |

| `knowledge/` | Evidence-tiered knowledge library |

| `memory/` | Path records, sessions, proposals |

| `sanitizer/` | Boundary enforcement, exit firewall |

| `agents/` | Agent bundles and personas |

| `tests/` | Test suite (flat, pytest) |

| `dev/` | Specs, reports, simulation harnesses |

| `docs/` | Public site, published specs |

| `runtime/` | Hub server, PWA surface |

| `templates/` | Workup and canvas templates |

| `scripts/` | Operational and maintenance scripts |

| `scratch/` | Agent working area (audited) |

| `archive/` | Retired material, heritage ontology |



`dev/INDEX.md` is the spec status index — which of the dev/ specs are active, shipped, or superseded.



## The Governed Execution Loop



Every query flows through exactly this sequence:



```

SCAN → CLASSIFY → TRAVERSE → RETRIEVE → CONTEXT → REASON → RESEARCH → SYNTHESIZE → STORE

```



Of 9 steps, only 2 require model inference. The rest is deterministic computation. The ontology does the planning. The model does the reasoning. They never compete.



| Step | What It Does | Needs a Model? |

|------|-------------|----------------|

| **SCAN** | Detect PII/PHI at first contact | No |

| **CLASSIFY** | Route through 177-node ontology (hybrid LLM + keyword, hallucinated node rejection) | Local LLM or keyword fallback |

| **TRAVERSE** | Walk composability graph — resolve dependencies, check blocked edges, apply cycle guards | No |

| **RETRIEVE** | Pull evidence-tiered knowledge by classified node | No |

| **CONTEXT** | Assemble structured prompt: node + lens + knowledge + path history | No |

| **REASON** | Local model reasoning with full context | Yes (local) |

| **RESEARCH** | Governed external research — gated, sanitized, only when local knowledge is insufficient | Yes (external, when enabled) |

| **SYNTHESIZE** | Merge local + external with confidence scoring and integrity checks | No |

| **STORE** | Append structural path record to memory | No |



## What's Inside



### Ontology — 237 nodes across 17+ domains



Each node is an independently executable atomic operation with signals, failure modes, success conditions, and composability edges:



```yaml

- id: MC-DEPLOY-008

  name: Install Surface Generation

  produces: [install_script, dockerfile, release_workflow, install_test]

  requires: []

  suggests_next: [MC-GOV-006, MC-DEPLOY-005, MC-WORK-007]

  failure_modes:

    silent: [installer reports success while binary crashes on launch]

    loud: [binary download 404 with no source fallback]

```



**82 unique artifact types** produced across all nodes. **7 required artifact types** create dependency chains. **444+ composability edges** across 6 predicates (parent_of, suggests_next, produces, required_by, escalates_to, resolves_to) define how operations chain together.



### Knowledge Library — 189 entries, evidence-tiered



Evidence-tiered: Tier 1 (direct platform publications), Tier 2 (standards/peer-reviewed), Tier 3 (validated open source). Every entry links to specific ontology nodes. No unsourced claims.



### Lenses — 40 reasoning modifiers



Lenses change HOW the model reasons without changing WHICH node executes. They compose — a query can activate multiple lenses simultaneously:



| Lens | Activates On | What It Does |

|------|-------------|-------------|

| architect | work domain | See how pieces connect. Trace dependencies. Surface structural risks. |

| critique | low confidence | Challenge the classification. Look for alternatives. |

| precision | RESEARCH intent | Cite by source. Answer only what evidence supports. |

| protection | sensitive content | Maximum boundary. Strip internal context. |

| legal / clinical / fiduciary | domain-specific | Professional reasoning with domain constraints. |

| gamedev / education / healthcare | domain-specific | Profession-aware reasoning from loaded canvas skins. |

| + 21 role lenses | on request | Product, engineering, security, finance, data science... |



### Canvas Ecosystem



A canvas is a professional operating harness — ontology nodes, knowledge entries, and reasoning lenses packaged for a specific domain. Load a canvas and the system immediately knows your profession:



```bash

mc canvas load ~/my-healthcare-canvas    # Loads HIPAA nodes, PHI protection, clinical lenses

mc canvas load ~/mythfall-dev            # Loads game-dev nodes, NPC framework, balance lens

mc canvas validate canvas.yaml           # Validates manifest against spec

mc canvas list                           # Shows loaded canvases

mc canvas remove grant-writing           # Unloads a canvas cleanly

```



When a canvas is loaded, the classifier applies a **domain bias** — ambiguous queries prefer the canvas's domain. Strong signals still win. The user declared their context; the system respects it.



Canvases are configuration layers, not forks. See `docs/specs/CANVAS_MANIFEST_SPEC.md` for the schema.



### Gates — Entry, Integrity, Exit



Three non-negotiable boundaries:

- **Entry gate**: PII/PHI detection and sanitization before classification

- **Integrity gate**: Validates model output against ontology constraints

- **Exit gate**: Scans external responses for malicious patterns before they enter the system



### Structural Memory



Every query stores a path record: node, confidence, lens, model, duration, gap signals. Memory is append-only (zero forgetting), structurally indexed (zero false recall). This is the external symbolic verifier that escapes the No-Escape Theorem (Barman et al., arXiv:2603.27116).



### Observability Harness



Structural tracing for governed builds. When MC builds something (an install surface, an observability harness), the build process itself is traced, recorded, and stored as a build record. The system learns from its own construction.



## Example: Voice Agent Design



Mission Canvas was used to design and evaluate voice agents — a full-stack example of what the system enables when loaded with domain knowledge.



**What was built:**

- **Tessitura framework** — a methodology for finding the narrow speed range where a brand's voice sounds like itself. 5 emotional states mapped within a measurable band (0.83–1.30 speedAlpha).

- **Live voice agent** — a working bot with state-based pacing, pre-pause empathy (400ms), and pitch-spike elimination (46% reduction).

- **Voice evaluation workbench** — compare and score 16 AI voices across 4 languages with A/B tessitura comparison.

- **OKA** — an adaptive learning companion for a dyslexic child, voice-first, with tiered exercise progression.



**How MC enabled it:**

- Classification routed voice queries to the right domain nodes (deployment, data quality, evaluation)

- Knowledge entries stored the tessitura measurements, iteration results, and failure modes

- Lenses shaped reasoning: `architect` for system design, `critique` for voice quality evaluation

- Path records tracked every design decision as a traceable judgment trail

- The governance bundle ensured sensitive learner data never left the local machine



**See it live:**

- [Voice Demo — Tessitura Framework](https://missioncanvas.ai/voice-demo/)

- [Voice Evaluation Workbench](https://missioncanvas.ai/voice-workbench/)

- [OKA — Adaptive Learning](https://missioncanvas.ai/oka.html)

- [Full Portfolio](https://missioncanvas.ai/portfolio-home.html)



This is one domain. The same pattern applies to legal research, financial analysis, medical decision support, startup strategy — any domain where you need governed reasoning over sensitive, structured knowledge.



## Key Design Decisions



**Pre-reasoning governance, not post-reasoning guardrails.** Classification happens before the model sees the query. If a query is classified under the Legal domain, `blocks_external = true` forces local routing and strips client identifiers. The model never receives information it isn't authorized to reason about.



**Structural retrieval, not semantic similarity.** Knowledge is indexed by problem pattern, not embedding distance. A query classified to MC-LEGAL-001 retrieves privilege assessment knowledge — not whatever has the highest cosine similarity to the word "privilege."



**Three retrieval principles:**

1. **Retrieval ≠ Authorization** — permissions checked BEFORE context window

2. **Memory ≠ Retrieval** — retrieval measures hit rate; memory measures behavioral improvement

3. **Similarity ≠ Relevance** — cosine similarity is an approximation, not truth



**Gap-to-knowledge pipeline.** When classification hits a zero-knowledge node, the system captures the failure, routes via the research gate, and auto-generates a candidate knowledge entry. The ontology self-grows from its own classification gaps.



## Relationship to Palette



Mission Canvas and [Palette](https://github.com/pretendhome/palette) are two implementations of the Structured Knowledge Harness category:



- **Palette** organizes knowledge ABOUT a domain — what we know, how confident we are, where it came from.

- **Mission Canvas** governs how a model INTERACTS with knowledge — what the model should see, what it should never see, and what we learned.



Palette is the library. Mission Canvas is the librarian's governed workflow. They share architectural principles but operate independently.



## Architecture



```

mission-canvas/

├── ontology/             # 237 nodes, 444+ edges, 17+ domains

│   ├── core/             # Intent nodes + MC-native domain nodes

│   ├── domains/          # Domain YAML (legal, data, work, healthcare, gaming, education...)

│   ├── engine.py         # Hybrid LLM + keyword classifier, canvas bias, tiebreak

│   ├── graph.py          # Composability graph with 6 predicates

│   ├── traverse.py       # BFS with produces/requires satisfaction + cycle guards

│   ├── score.py          # Completeness scoring

│   └── learned_weights.py # Online signal adaptation from path outcomes

├── knowledge/            # 189 entries, evidence-tiered

├── memory/               # Path records, build records, observations (append-only)

├── lenses/               # 40 reasoning modifiers + lens engine

├── src/

│   ├── pipeline.py       # 9-step governed execution loop

│   ├── canvas_runtime.py # Canvas load/remove/list — domain canvas activation

│   ├── canvas_validator.py # Canvas manifest validation (19 tests)

│   ├── observe.py        # Observability harness (structural tracing)

│   ├── context_builder.py

│   ├── llm_proxy.py      # Multi-provider routing (Ollama, Anthropic, OpenAI, Mistral)

│   ├── gateway/          # Entry (PII), integrity (output), exit (response) gates

│   ├── workup.py         # Customer Problem Workup (CPW) state engine

│   ├── bdat.py           # Business Development Analysis Tool (BDAT) state engine

│   └── tracers/          # strace, Windows PowerShell, base framework

├── static/               # Localhost UI (PWA-capable)

├── runtime/hub/          # Voice + chat hub (SSE streaming, Rime TTS)

├── docs/                 # Public site (missioncanvas.ai) + voice demos + portfolio

│   └── specs/            # Canvas manifest spec, governance specs

└── tests/                # 449+ tests + health checks + 57/57 golden dataset

```



## Hardware-Adaptive Local Intelligence



MC detects your hardware at setup and picks the best local model automatically — no model names, no configuration. The same pipeline works on every machine; what changes is how much local reasoning happens before cloud synthesis.



| Your Hardware | What Happens | Local Speed |

|---|---|---|

| **GPU ≥ 8GB** (RTX 3060+, M2 Pro+) | Full local reasoning with larger model | 25-50 tok/s |

| **GPU 4-6GB** (RTX 3050, M1) | Fast local reasoning with compact model | 30-55 tok/s |

| **CPU only** (business laptops) | Privacy scan stays local, reasoning goes to cloud | Cloud-speed |



One button handles first download AND future model upgrades. `mc improve` re-evaluates when hardware changes (new GPU, driver update, better model released). The user never makes a technical decision — the system measures what your machine can do and adapts.



## Install



```bash

# Docker

git clone https://github.com/pretendhome/mission-canvas.git

cd mission-canvas && docker compose up --build



# macOS / Linux

curl -fsSL https://missioncanvas.ai/install.sh | sh



# Windows

irm https://missioncanvas.ai/install.ps1 | iex



# Zero-install (paste into any AI tool)

# Download AGENTS.md → paste as system prompt

```



## Verify



```bash

python3 -m pytest tests/ -q          # full suite — zero failures is the invariant

mc health                            # integrity checks — 100% is the invariant

mc setup                             # guided provider wizard (press Enter to stay local)

mc canvas validate canvas.yaml       # Validate a canvas manifest

```



## License



AGPL-3.0 (core engine). MIT (canvas manifest spec + templates). See `LICENSING.md` for details.