Project Model

Projects are the primary unit of work in Nous.

A project is not a chat thread. It is a scoped, persistent execution environment with its own memory, model configuration, tool permissions, and governance policy.

This document defines the project model architecture — how projects are created, how they execute, and how governance is applied.

Project Type Spectrum

Projects exist on a spectrum between two poles.

Protocol Projects (Structured)

Defined workflows with explicit stages, measurable quality gates, and standardized outputs.

Characteristics:

• Workflow is known upfront or proposed by Nous and approved by the user
• Steps are explicit — modeled as a node graph
• Quality gates have measurable thresholds
• Cortex enforces the protocol and routes within it
• Output is predictable and reproducible

Example: A synthetic persona engine with defined identity validation thresholds, gated phase transitions, and standardized artifact outputs.

Intent Projects (Open-ended)

Standing objectives with constraint boundaries. No predefined workflow.

Characteristics:

• User defines a goal and constraints, not steps
• Nous determines how to accomplish the objective
• Behavior is emergent and adaptive
• Cortex has high autonomy within declared guardrails
• Success is judged heuristically, not by binary gates

Example: "Keep my Outlook inbox tidy and notify me of anything urgent."

Hybrid Projects

Most real projects are hybrid. They contain structured protocol segments alongside open-ended sub-tasks.

A protocol project may have exploratory nodes ("find the best negative prompt anchors for this identity"). An intent project may develop internal protocols over time as patterns emerge ("I noticed you always forward messages from X to Y — should I formalize that as a rule?").

Nous must support protocol emergence — the ability to propose formalizing learned patterns into explicit workflow nodes. The protocol crystallizes with confidence, not all-or-nothing.

The Spectrum

Fully Explicit ◄────────────────────────────────► Fully Autonomous
(Protocol)                                          (Intent)

Defined node graph                        Goal + constraints only
Cortex enforces                              Cortex improvises
Predictable steps                         Emergent behavior
Quality gates measured                    Success judged heuristically
Lower Cortex tier sufficient                 Higher Cortex tier required

Every project declares where it sits on this spectrum, or allows individual regions of its workflow to sit at different points.

Visual Workflow Interface

The primary interface for project design and monitoring is a node-based visual editor.

For Protocol Projects

The user builds or approves a workflow graph. Each node represents a discrete step — a model call, a tool execution, a quality gate, a Principal decision point, a branching condition.

Nodes are wired together to define execution order, data flow, and conditional paths.

This is the project's operational blueprint.

For Intent Projects

The visual interface serves a different purpose. There is no upfront graph to build. Instead, the interface provides:

• The standing objective and constraints
• A live view of what Nous is currently doing
• A history of actions taken and decisions made
• Proposed protocol formalizations when patterns emerge

For Hybrid Projects

Both views coexist. Structured segments are displayed as defined node graphs. Open-ended segments are displayed as live activity feeds within the broader workflow.

Node Schema

Every node in a workflow graph declares:

• Name — human-readable identifier
• Type — model call, tool execution, quality gate, Principal decision, condition, transform, etc.
• Inputs — expected data from upstream nodes
• Outputs — data produced for downstream nodes
• Model assignment — which model role or specific provider handles this node (if applicable)
• Governance level — MUST, SHOULD, or MAY (see below)
• Escalation rules — when and how to involve the Principal
• Timeout and retry policy — how long to wait, how many retries, what to do on failure
• Memory access override (optional) — when a node requires more restrictive cross-project memory access than the project default (see Memory Access Policy below)

Phase 9.2 turns that abstract schema into typed node contracts. model-call, tool-execution, condition, transform, quality-gate, human-decision, and subworkflow nodes each validate their own config shape before runtime execution begins. A node whose config.type does not match its declared node type fails closed during workflow-definition validation rather than at execution time.

Project Identity and Memory Access Policy

Every project has a canonical identity and a memory access policy that governs cross-project memory boundaries.

Project Identity

Project identity is deterministic across all surfaces (chat, runtime, MAO/UI):

• id — UUID, stable for the project lifetime
• name — human-readable identifier
• type — protocol, intent, or hybrid

These fields resolve identically regardless of which interface is used.

Installed Packages vs. Live Projects

Phase 14.1 separates installable package stores from live workspace state:

• Installable workflow packages live in .workflows/
• Installable skill packages live in .skills/
• Installable app packages live in .apps/
• Active local project instances live in .projects/

This matters because a live project is not itself the installable package. A project may be created from a workflow package, reference multiple skills, and interact with installed app surfaces, but its runtime state, local configuration, and accumulated work remain project-scoped workspace data. Legacy manifests that still use package_type: project are accepted at ingress and normalized to the canonical workflow package type before they become stored runtime or registry truth.

A project can bind to an installed workflow package through packageBindings in its workflow configuration. When a binding is present, the workflow engine resolves the active definition from the installed package at runtime without copying the installed definition into project-local config or run state. The resolved source is exposed as workflowDefinitionSource in workflow snapshots and monitoring projections so operators can distinguish an installed package definition from a project-authored inline workflow. Inline project-authored definitions remain the fallback when no binding applies.

Memory Access Policy

Each project declares a memory access policy with three fields:

Explicit defaults: When a project is created without an explicit policy, the default is fully open: canReadFrom: all, canBeReadBy: all, inheritsGlobal: true. No implicit trust inheritance from other projects.

Node-level override: Individual nodes can declare a memoryAccessPolicyOverride to restrict memory access below the project default. Overrides can only be more restrictive — a node cannot expand access beyond what the project allows. Used for compliance-sensitive nodes (e.g. validation gates that must not see cross-project context).

Policy decision engine: Cross-project memory operations (read, write, retrieve) are evaluated by the policy decision engine (@nous/memory-access). Denied attempts emit durable evidence with deterministic POL-* reason codes (e.g. POL-CANNOT-READ-FROM, POL-GLOBAL-DENIED, POL-CONTROL-STATE-BLOCKED). When a project is hard_stopped, all cross-project access is blocked.

Enforcement surfaces (Phase 3.3): (1) Core-executor — policy gate before memory write submission for chat-driven turns; (2) PolicyEnforcedRetrievalEngine — wraps retrieval, evaluates policy before delegating; (3) IProjectApi.memory (stub/implementation) — policy gate at API boundary when cross-project or global scope.

Policy observability (Phase 3.4): Every denial/approval traces to PolicyDecisionRecord with reasonCode and traceId. When hard_stopped or paused_review, policy denies with POL-CONTROL-STATE-BLOCKED or POL-PAUSED-BLOCKED. Downstream phase intake (Phase 4 learning loop, Phase 5 workflow foundation) is documented in .worklog/phase-3/phase-3.4/export-hooks.mdx.

Workflow Definition and Runtime State (Phases 9.1-9.2)

Phase 9.1 adds the first canonical workflow-runtime contract layer for protocol and hybrid projects. Phase 9.2 extends that layer into governed node execution, continuation, and checkpointed recovery.

Canonical Workflow Definition

Workflow truth is project-scoped. A project can store one or more inline workflow definitions plus a default workflow reference inside project configuration. A project can also bind to an installed workflow package through packageBindings; when a binding resolves, the installed definition serves as the active graph source without becoming project-local configuration truth.

The canonical definition carries:

• Versioned workflow identity
• Entry nodes
• Node definitions
• Edge definitions
• Mode (protocol or hybrid)

This stored definition is authoritative. The execution graph is derived from it and can be rebuilt at any time. UI surfaces, automation, and future scheduler projections must not invent a competing workflow graph state model.

Admission Before Run Creation

The workflow runtime does not create a run as soon as a request arrives. It first:

1. Resolves the workflow definition from the target project
2. Validates the graph as a deterministic DAG
3. Evaluates project scope, workmode compatibility, authority-chain integrity, and control-state compatibility
4. Mints a run only after those checks pass

Blocked admissions remain reason-coded and evidence-linked. Missing definitions, invalid graph structure, authority mismatch, and blocked control states all fail closed before a new run is created.

Explicit Runtime State

Phase 9.1 makes workflow execution state explicit rather than leaving later surfaces to infer it:

• Run state records workflow ID, graph digest, admission result, ready nodes, completed nodes, and overall status
• Node run state records per-node execution status, reason codes, evidence refs, and last dispatch
• Dispatch lineage records how a node became ready, including parent node, edge linkage, attempt number, and evidence refs

This gives scheduler, chat, Projects UI, and MAO consumers a canonical runtime truth to project from without re-deriving execution history locally.

Phase 14.4 extends that same runtime truth with an additive terminal canceled posture so operators can distinguish intentional cancellation from failure or normal completion without inventing surface-local state.

Canonical Lifecycle Control Boundary (Phase 14.4)

Workflow lifecycle control remains an internal runtime boundary, not a new app-owned control plane.

• workflow_list, workflow_inspect, and workflow_status are canonical read projections exposed through the Internal MCP surface for the approved internal lanes.
• workflow_start, workflow_pause, workflow_resume, and workflow_cancel are Cortex::System-only lifecycle mutations. They remain authority-bound control actions rather than browser, app, or public-edge operations.
• Lifecycle mutations emit witness-linked evidence and preserve the existing workflow-runtime truth, checkpoint posture, wait states, and correction semantics rather than creating a second state store.
• Apps and the public MCP edge remain outside workflow mutation authority. They can project workflow state through approved runtime surfaces, but they do not become the source of lifecycle truth.

Typed Node Contracts and Governed Execution (Phase 9.2)

Phase 9.2 hardens the execution layer in three ways:

1. Typed configs before execution — every executable node is validated against a node-type-specific config schema before the runtime accepts it.
2. Governance through the PFC seam only — node execution posture is derived from the canonical confidence-governance decision engine, not from duplicated local autonomy rules.
3. Explicit execute/continue boundaries — the runtime distinguishes "execute a ready node" from "continue a waiting node" so downstream surfaces can reason about dispatch, waits, and resumes without guesswork.

This preserves determinism at the workflow boundary. A node cannot silently reinterpret its shape, and the runtime cannot bypass governance by invoking handlers directly on an unvalidated or out-of-scope path.

Append-Only Attempts, Waits, and Correction Arcs (Phase 9.2)

Phase 9.2 also makes node execution history durable and projection-friendly:

• Attempts are append-only. Every node execution attempt is preserved with its governance decision, reason code, evidence refs, timestamps, and optional output/checkpoint linkage.
• Wait states are first-class. Nodes can explicitly wait on async_batch, human_decision, retry_backoff, or checkpoint_commit.
• Correction arcs are explicit. When execution is blocked or intentionally redirected, the runtime records whether the corrective posture is resume, retry, reprompt, or rollback.

This matters because downstream surfaces no longer need to infer whether a run is "stuck" or "paused for review." The canonical runtime state already distinguishes waiting from blocked review and preserves the reason-coded path that led there.

Checkpointed Continuation and Branch Truth (Phase 9.2)

Phase 9.2 couples continuation to checkpoint integrity and activated branch paths:

• Prepared vs. committed checkpoints are distinct. The runtime can expose a prepared checkpoint while it is still waiting for durable commit.
• Continuation resumes only from committed checkpoints. A checkpoint_commit wait protects the run from advancing on provisional state.
• Condition branches activate explicit outbound edges. The selected branch key and the set of activated edges are stored in canonical runtime state so joins and successors remain deterministic.

This keeps recovery compatible with external side effects and prevents later projections from inventing alternate branch histories.

Node Governance Levels

Not all steps in a workflow carry equal weight. Even within a strict operational protocol, some steps are critical gates and others are discretionary.

Each node declares its governance level:

MUST

Hard gate. Binary pass/fail. No Cortex discretion.

• The Cortex cannot override a MUST gate
• Failure halts the workflow or triggers the defined failure path
• All MUST evaluations are logged with full provenance
• Used for: quality thresholds, compliance checks, safety boundaries

Example: Identity validation must achieve ≥85% recognizability across the test grid. If it does not pass, the workflow does not proceed.

SHOULD

Strong default. Cortex can deviate with justification.

• The Cortex follows the defined behavior by default
• Deviation is permitted but must include a logged justification
• Deviations are flagged for Principal review (configurable)
• Used for: best practices, standard operating procedures, recommended defaults

Example: Video clips should be 5–10 seconds. The Cortex may produce a 12-second clip if the content warrants it, but the deviation is logged and flagged.

MAY

Discretionary. Cortex uses judgment. Escalates only on low confidence.

• The Cortex operates with full autonomy within the node's declared constraints
• No justification required for choices made
• Escalation occurs only when Cortex confidence drops below a configured threshold
• Used for: creative decisions, optimization choices, non-critical parameter selection

Example: Wardrobe selection for a photo batch. The Cortex chooses based on content calendar context and prior performance. No escalation unless the choice falls outside declared constraints.

Governance Evolution

Governance levels are not static. They are a tuning surface.

A user may start a project with all nodes set to MUST (maximum control). As trust builds in Nous's judgment on specific steps, individual nodes can be relaxed to SHOULD or MAY.

Conversely, if a MAY node produces poor outcomes, it can be tightened to SHOULD or MUST.

This allows governance to evolve with confidence, per-node, without restructuring the workflow.

Runtime Confidence Governance (Phase 8.6)

Node governance is resolved at runtime from the canonical confidence-governance mapping plus the pattern confidence tier, decay state, project control state, and action category. The runtime is deterministic: equivalent inputs resolve to the same outcome with the same evidence-linked explanation.

Additional runtime rules:

• hard_stopped denies execution; paused_review and resuming defer it
• High-risk action categories (tool-execute, memory-write, opctl-command) always defer for explicit confirmation
• Low-confidence, contradiction, staleness, and retirement paths escalate with evidence-linked, reason-coded outcomes

Cortex as Project Supervisor

The Cortex's role extends beyond per-turn evaluation. In the project model, the Cortex is a persistent supervisor for the entire project lifecycle.

Per-Turn Role (Existing)

• Evaluate a single interaction
• Route to the appropriate model
• Authorize tool execution
• Gate memory writes
• Respond and trace

Per-Project Role (Extended)

• Supervise long-running workflow execution
• Make routing decisions continuously as the graph executes
• Enforce governance levels at each node
• Track project state across sessions
• Checkpoint and resume workflows after interruption
• Escalate to Principal through configured channels when required
• Propose protocol formalizations in intent projects
• Learn from outcomes to improve future decisions within the project

Phase 12.1 adds the internal AgentGateway harness beneath this supervisor posture. It provides deterministic multi-turn execution, typed parent-child inbox/outbox messaging, auditable correlation state, and hard budget ceilings for recursive internal agent work, but it does not change which layer owns workflow truth or governance authority.

The Cortex tier determines how much autonomous reasoning the supervisor applies. Protocol projects with explicit graphs may run at lower tiers. Intent projects with emergent workflows require higher tiers.

Principal Escalation

Principal involvement is a first-class concept, not an edge case.

Escalation Triggers

• A MUST gate fails
• A SHOULD deviation is flagged for review
• Cortex confidence drops below the configured threshold on a MAY node
• An intent project encounters ambiguity it cannot resolve
• A workflow reaches a node explicitly typed as "Principal Decision"

Escalation Channels

Nous supports configurable escalation channels per project:

• In-app notification (GUI)
• Push notification (mobile)
• Message (Slack, Discord, SMS, etc.)
• Email
• Voice call (for high-priority escalations)

Each project defines its channel preferences and priority mapping.

Escalation Contract

When Nous escalates, it provides:

• What happened (context)
• Why it is escalating (trigger reason)
• What it recommends (if applicable)
• What it needs from the Principal (decision, approval, clarification)
• What happens if no response is received within the timeout (default action or halt)

Heterogeneous Provider Model

Projects require more than LLMs. The Persona Engine uses diffusion models, image-to-video pipelines, and vision models. The inbox project uses email APIs and classification models.

The provider abstraction must support:

• Text models — LLMs for reasoning, prompt engineering, classification
• Image models — diffusion models (FLUX, SDXL) via ComfyUI, A1111, or direct API
• Video models — I2V pipelines (Wan, HunyuanVideo, CogVideoX) or cloud APIs (Kling, Runway, etc.)
• Vision models — for validation, quality assessment, artifact detection
• Embedding models — for memory retrieval and semantic search
• External APIs — for tool execution (email, social media, scheduling, etc.)

Each provider type has different I/O characteristics:

The model router must handle this heterogeneity. Routing decisions include not just which provider, but what execution model to use.

Artifact Management

Projects produce artifacts beyond text and memory entries. Images, videos, LoRA weights, configuration files, validation reports.

Artifacts are:

• Binary or structured files stored outside the memory system
• Versioned with full provenance (which node produced them, when, with what parameters)
• Project-scoped by default
• Exportable and deletable consistent with Nous memory governance
• Referenceable from workflow nodes and memory entries

The Persona Pack is an example artifact bundle: a versioned collection containing an identity LoRA, prompt templates, negative anchors, pose presets, seed strategy, and validation report — all produced by different nodes in the workflow and packaged as a single deliverable.

Execution Model

Different nodes require different execution patterns.

Synchronous

Standard request-response. Used for text model calls, classification, simple tool execution.

Streaming

Token-by-token output. Used for LLM responses displayed to the user.

Async / Batch

Long-running tasks submitted as jobs. Used for image generation, video generation, LoRA training.

Requirements:

• Job queuing
• Progress tracking
• Timeout and retry policy
• Checkpoint and resume on failure

Scheduled / Recurring

Time-triggered execution. Used for monitoring loops, content scheduling, periodic batch generation.

Requirements:

• Cron-like scheduling
• Standing objective evaluation loops
• Configurable frequency and conditions

The workflow engine must support all four patterns within a single project graph.

Project Lifecycle

1. Create — User creates a project in the GUI. Selects project type (protocol, intent, hybrid). Defines initial configuration.
2. Design — For protocol projects: build or approve the workflow graph. For intent projects: define the objective and constraints.
3. Configure — Assign models per node/role. Set governance levels. Configure escalation channels. Define artifact storage.
4. Execute — Nous Cortex supervises execution. Workflow runs. Escalations occur as needed.
5. Evolve — Governance levels tuned. Protocol emerges from intent. Workflows refined based on outcomes.
6. Archive or Retire — Project completed or deactivated. Artifacts and memory preserved or exported per retention policy.

Relationship to Existing Architecture

This project model extends existing Nous concepts:

• ProjectStore → Becomes the container for project type, workflow graph, governance configuration, artifact references, and Phase 9.1 canonical workflow definitions/default workflow references — not just namespace and config
• Canonical Root Stores → Phase 14.1 separates installable .workflows/, .skills/, and .apps/ stores from live .projects/ workspace state so runtime truth does not confuse package inventory with active project instances
• Cortex Engine → Gains a per-project supervisor mode in addition to per-turn evaluation
• Cortex Core Runtime → Phase 12.1 now hosts the additive AgentGateway execution harness beside CoreExecutor, giving internal agent work a deterministic multi-turn runtime without moving workflow run-state authority out of the Phase 9 workflow engine
• ModelRouter → Must route heterogeneous provider types, not just text model roles
• Tool Interface → Nodes in the workflow are a superset of tools — they include model calls, quality gates, Principal decisions, and transforms alongside tool executions
• MemoryStore → Remains responsible for text and embedding memory. Artifact storage is a separate concern.
• Storage → Must support binary artifact persistence with versioning, in addition to existing memory and trace storage

New architectural components implied:

• Workflow Engine — Phase 9.1 establishes deterministic graph derivation, admission, and explicit run/node/dispatch lineage state. Phase 9.2 adds governed node execution, append-only attempts, wait/correction state, checkpointed continuation, and activated-branch tracking; later phases add broader scheduler integration and artifact persistence
• AgentGateway Runtime Harness — Phase 12.1 adds the deterministic internal agent loop, result-only child returns, typed inbox/outbox messaging, and budget/correlation control surface that later lifecycle-tool and migration work build on
• Artifact Store — versioned binary asset management, project-scoped
• Scheduler — time-triggered execution for recurring and monitoring workflows
• Escalation Service — multi-channel Principal notification with response tracking
• Node Registry — typed node definitions with governance, I/O schemas, and execution model declarations

This document captures the design direction for the Nous project model.

It is a living document. Implementation details will be refined through SDS and ADR artifacts as individual components are designed and built.