CoReason-AI · gowthamrao · Jan 31, 2026 · Jan 31, 2026 · Feb 1, 2026 · Feb 1, 2026
diff --git a/README.md b/README.md
@@ -17,7 +17,7 @@ coreason-maco-builder
 
 ### Dependency on Shared Kernel (coreason-manifest)
 
-The `coreason-maco-builder` explicitly depends on the `coreason-manifest` shared kernel (v0.7.0+) for all output artifact definitions.
+The `coreason-maco-builder` explicitly depends on the `coreason-manifest` shared kernel (v0.9.0+) for all output artifact definitions.
 
 **Why?**
 -   **Contract-First Design**: The Builder acts as a compiler that translates vague user intent into a strict, executable specification. By importing schemas directly from the Kernel, we ensure that the output is always compliant with the Runtime's expectations.
@@ -27,6 +27,13 @@ The `coreason-maco-builder` explicitly depends on the `coreason-manifest` shared
 **Value:**
 This architecture guarantees that any valid output from the Builder is readable by the CoReason Runtime, facilitating robust versioning and protocol upgrades.
 
+## Changes in v0.2.0
+
+- Upgraded `coreason-manifest` dependency to `^0.9.0`.
+- Implemented `Compiler` bridge to ensure strict `RecipeManifest` output with integrity hashing.
+- Refactored `Weaver` to use the `Compiler` for final artifact generation.
+- Updated internal schemas to align with Shared Kernel definitions (e.g., `CouncilConfig`).
+
 ## Getting Started
 
 ### Prerequisites

diff --git a/docs/coreason_manifest_integration.md b/docs/coreason_manifest_integration.md
@@ -0,0 +1,68 @@
+# Coreason Manifest Integration
+
+This document details the integration between `coreason-maco-builder` (The Compiler) and `coreason-manifest` (The Kernel).
+
+## Overview
+
+The `coreason-maco-builder` serves as the Architect and Compiler for the CoReason platform. It converts high-level, natural language intent into a strict, executable specification known as a `RecipeManifest`.
+
+The `RecipeManifest` and its constituent parts are defined in the `coreason-manifest` library, which serves as the Shared Kernel between the Builder (Design Time) and the Runtime (Execution Time).
+
+## Kernel Architecture (v0.9.0+)
+
+### 1. RecipeManifest
+The top-level artifact produced by the Builder.
+- **Class:** `coreason_manifest.recipes.RecipeManifest`
+- **Purpose:** A self-contained, versioned, and immutable definition of a multi-agent strategy.
+- **Key Fields:**
+  - `id`: Unique identifier (UUID or Name).
+  - `version`: SemVer string.
+  - `topology`: The execution graph (`GraphTopology`).
+  - `interface`: Input/Output schema (currently empty in Builder output).
+  - `state`: Internal state schema (currently empty).
+
+### 2. GraphTopology
+The directed graph structure defining the flow of execution.
+- **Class:** `coreason_manifest.definitions.topology.GraphTopology`
+- **Purpose:** Container for Nodes and Edges.
+- **Key Fields:**
+  - `nodes`: List of polymorphic nodes (`AgentNode`, etc.).
+  - `edges`: List of directed connections (`Edge`).
+
+### 3. AgentNode
+A node representing an AI Agent.
+- **Class:** `coreason_manifest.definitions.topology.AgentNode`
+- **Purpose:** Defines the runtime configuration for a specific agent step.
+- **Key Fields:**
+  - `id`: Unique UUID.
+  - `agent_name`: The role/persona identifier (mapped from Builder's `CompiledNode.base_role`).
+  - `council_config`: Optional configuration for voting/consensus logic.
+  - `type`: Literal "agent".
+
+### 4. CouncilConfig
+Configuration for multi-agent decision making (Voting).
+- **Class:** `coreason_manifest.definitions.topology.CouncilConfig`
+- **Purpose:** Defines how a decision is reached when multiple voters are involved.
+- **Key Fields:**
+  - `strategy`: The voting mechanism (e.g., "majority", "consensus").
+  - `voters`: List of agent roles participating in the vote.
+
+## The Compilation Process
+
+The Builder uses a "Compiler Bridge" (`src/coreason_maco_builder/core/compiler/manifest.py`) to transform its internal workspace state (`RecipeDraft`) into the Kernel artifact.
+
+1.  **Drafting:** The user iteratively designs the strategy. The state is stored as a `RecipeDraft`, which allows for incomplete nodes (`RED` status) and flexible structures.
+2.  **Resolution:** The `Weaver` resolves `LogicalNode` intents into `CompiledNode` configurations (Roles, Prompts).
+3.  **Compilation:**
+    -   The `compile_to_manifest` function is called.
+    -   `CompiledNode` objects are mapped to `AgentNode` objects.
+    -   **Note:** Internal Builder metadata (e.g., specific `system_prompt` text) is currently *not* embedded directly into the `AgentNode` in v0.9.0, as the Runtime loads these from the Role Registry based on `agent_name`.
+    -   Topological connections are mapped to `Edge` objects.
+    -   An **Integrity Hash** is computed based on the canonical JSON representation of the topology and metadata.
+    -   The final `RecipeManifest` is returned, ready for deployment.
+
+## Versioning Policy
+
+The Builder is strictly coupled to the `coreason-manifest` version.
+- **Builder v0.2.0** -> **Manifest v0.9.0**
+- Any changes to the Kernel schema require a corresponding update and refactor in the Builder's compiler logic.
diff --git a/docs/coreason_manifest_v0.10.0_proposal.md b/docs/coreason_manifest_v0.10.0_proposal.md
@@ -0,0 +1,83 @@
+# Coreason Manifest v0.10.0 Proposal
+
+**From:** coreason-maco-builder Team
+**To:** coreason-manifest Kernel Team
+**Subject:** Request for Schema Enhancements in v0.10.0
+
+During the refactoring of the Builder to align with v0.9.0, we identified several "friction points" where the Kernel schema constrained our ability to express the full intent of the strategy or forced us to use workarounds.
+
+We propose the following changes for v0.10.0 to better support the Builder's needs while maintaining the Runtime's strictness.
+
+## 1. Enable "Ad-Hoc" Agents (Restore `config` / `system_prompt`)
+
+**Current State:**
+In v0.9.0, `AgentNode` only accepts `agent_name`. The Runtime presumably looks up the actual prompt and configuration from a "Role Registry" using this name.
+
+**Problem:**
+The Builder often creates "Ad-Hoc" agents—specialized variations optimized by the `Optimizer` module—that do not strictly exist in the static Role Registry. Currently, we have to drop the optimized `system_prompt` and `model_config` when compiling, meaning the Runtime executes the generic Role instead of the optimized one.
+
+**Proposal:**
+Add optional `config` and `system_prompt` fields to `AgentNode`. If present, the Runtime should use these *instead of* or *merged with* the registry defaults.
+
+```python
+class AgentNode(Node):
+    # ... existing fields
+    system_prompt: Optional[str] = None  # Override registry prompt
+    config: Optional[Dict[str, Any]] = None  # Runtime-specific config (model, temp, etc.)
+```
+
+## 2. Formalize Integrity Hashing
+
+**Current State:**
+The Builder calculates a cryptographic hash of the recipe to ensure integrity. In v0.9.0, `RecipeManifest` lacks a dedicated `integrity_hash` field, forcing us to append this critical metadata to the human-readable `description` field.
+
+**Problem:**
+Parsing the hash from the description is brittle and not machine-readable.
+
+**Proposal:**
+Add a dedicated, validated `integrity_hash` field to `RecipeManifest`.
+
+```python
+class RecipeManifest(BaseModel):
+    # ... existing fields
+    integrity_hash: Optional[str] = Field(
+        default=None,
+        description="SHA256 hash of the canonical JSON topology"
+    )
+```
+
+## 3. Builder Metadata Channel
+
+**Current State:**
+The compilation process is currently "lossy". Information useful for the *design* process (e.g., `resolution_status`, `optimization_log`, specific UI coordinates) is lost when converting `RecipeDraft` to `RecipeManifest`.
+
+**Problem:**
+If a user wants to "reload" a deployed `RecipeManifest` back into the Builder to edit it, we lack the context to reconstruct the full workspace state.
+
+**Proposal:**
+Add a `metadata` dictionary to `RecipeManifest` and `Node` that is explicitly ignored by the Runtime execution engine but preserved for tooling.
+
+```python
+class RecipeManifest(BaseModel):
+    # ...
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Tooling-specific metadata")
+```
+
+## 4. Flexible Interface Definition
+
+**Current State:**
+The `interface` field requires explicit `inputs` and `outputs` dictionaries.
+
+**Problem:**
+For many dynamic recipes, the interface is implicit or "Open". Requiring an explicit empty definition adds boilerplate.
+
+**Proposal:**
+Make `interface` optional or allow a flag for `dynamic: true`.
+
+---
+
+**Summary of Impact:**
+These changes would allow the Builder to:
+1.  Deploy optimized, ad-hoc agents immediately without registry updates.
+2.  Guarantee artifact integrity in a standard way.
+3.  Support "Round-Trip" engineering (Builder -> Manifest -> Builder).
diff --git a/docs/coreason_manifest_v0.10.0_requirements.md b/docs/coreason_manifest_v0.10.0_requirements.md
@@ -0,0 +1,88 @@
+# Coreason Manifest v0.10.0 Technical Specification
+
+**To:** Coreason Kernel Engineering
+**From:** Coreason MACO Builder Team
+**Priority:** High
+**Context:** The Builder requires these changes to support "Ad-Hoc" optimized agents, strict artifact integrity verification, and "Round-Trip" design workflows (Builder -> Runtime -> Builder).
+
+---
+
+## 1. `AgentNode` Enhancements
+
+**Goal:** Allow the Builder to define "Ad-Hoc" agents (agents with dynamically optimized prompts/configs) that do not exist in the static Role Registry.
+
+**Current Limitation:** `AgentNode` only accepts `agent_name`. The Runtime looks up the prompt from a registry. This prevents the `Optimizer` from deploying improved prompts without a registry update.
+
+**Required Change:**
+Update `coreason_manifest.definitions.topology.AgentNode` to include optional override fields.
+
+```python
+class AgentNode(Node):
+    # ... existing fields
+
+    # NEW FIELDS
+    system_prompt: Optional[str] = Field(
+        default=None,
+        description="Overrides the registry default prompt. Required for ad-hoc/optimized agents."
+    )
+
+    config: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Runtime-specific configuration (e.g., model parameters, temperature). Merged with registry defaults."
+    )
+```
+
+## 2. `RecipeManifest` Integrity & Metadata
+
+**Goal:**
+1.  Standardize artifact verification via a canonical hash.
+2.  Enable the Builder to re-import a compiled Manifest and restore the full design workspace (positions, colors, draft status).
+
+**Current Limitation:**
+-   We currently append the hash to the `description` string (brittle).
+-   We lose all design-time metadata (e.g., "Node X is RED status") during compilation.
+
+**Required Change:**
+Update `coreason_manifest.recipes.RecipeManifest`.
+
+```python
+class RecipeManifest(BaseModel):
+    # ... existing fields
+
+    # NEW FIELD: Integrity
+    integrity_hash: Optional[str] = Field(
+        default=None,
+        description="SHA256 hash of the canonical JSON representation of the topology. Enforced by Builder, verified by Runtime."
+    )
+
+    # NEW FIELD: Tooling Metadata
+    # This field should be explicitly IGNORED by the Runtime execution engine.
+    metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Container for design-time data (UI coordinates, resolution logs, draft status) to support re-hydration."
+    )
+```
+
+## 3. `GraphTopology` State Schema
+
+**Goal:** Reduce boilerplate for "Open Interface" recipes.
+
+**Current Limitation:** `state_schema` is mandatory.
+
+**Required Change:**
+Make `state_schema` optional in `GraphTopology`.
+
+```python
+class GraphTopology(BaseModel):
+    # ...
+    state_schema: Optional[StateSchema] = Field(default=None)
+```
+
+---
+
+## Summary of Success Criteria
+
+The v0.10.0 release will be considered successful if the Builder can:
+1.  Compile a recipe where an agent has a unique, optimizer-generated `system_prompt` that the Runtime actually executes.
+2.  Store the `integrity_hash` in its own field.
+3.  Store UI coordinates in `manifest.metadata["ui_layout"]` and retrieve them later.
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "coreason_maco_builder"
-version = "0.1.0"
+version = "0.2.0"
 description = "coreason-maco-builder"
 authors = ["Gowtham A Rao <gowtham.rao@coreason.ai>"]
 license = "Prosperity-3.0"
@@ -17,7 +17,7 @@ httpx = "^0.28.0"
 networkx = "^3.4.0"
 litellm = "^1.50.0"
 jinja2 = "^3.1.4"
-coreason-manifest = "^0.7.0"
+coreason-manifest = "^0.9.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.2.2"
@@ -33,7 +33,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "coreason_maco_builder"
-version = "0.1.0"
+version = "0.2.0"
 description = "coreason-maco-builder"
 readme = "README.md"
 requires-python = ">=3.11"