cognitive-modules-cli 1.1.0 → 1.2.0

package/README.md

@@ -1,162 +1,86 @@
-# Cognitive Runtime
+# Cognitive Modules CLI (Node.js)
 
-**Structured AI Task Execution**
+[![npm version](https://badge.fury.io/js/cognitive-modules-cli.svg)](https://www.npmjs.com/package/cognitive-modules-cli)
 
-Cognitive Runtime is the next-generation execution engine for Cognitive Modules. It provides a clean, provider-agnostic runtime that treats LLMs as interchangeable backends.
+Node.js/TypeScript 版本的 Cognitive Modules CLI。
 
-## Philosophy
+> 这是 [cognitive-modules](../../README.md) monorepo 的一部分。
 
-Following the **Cognitive Runtime + Provider** architecture:
-
-```
-┌─────────────────────────────────────┐
-│         Cognitive Runtime           │
-│  ┌────────────────────────────────┐ │
-│  │     Module System              │ │
-│  │  (load, parse, validate)       │ │
-│  └────────────────────────────────┘ │
-│  ┌────────────────────────────────┐ │
-│  │     Execution Engine           │ │
-│  │  (prompt, schema, contract)    │ │
-│  └────────────────────────────────┘ │
-│  ┌────────────────────────────────┐ │
-│  │     Provider Abstraction       │ │
-│  │  (gemini, openai, anthropic,   │ │
-│  │   deepseek, minimax, qwen...)  │ │
-│  └────────────────────────────────┘ │
-└─────────────────────────────────────┘
-```
-
-## Installation
+## 安装
 
 ```bash
-npm install -g cognitive-runtime
-```
+# 全局安装（推荐）
+npm install -g cogn
 
-Or run directly:
-
-```bash
-npx cognitive-runtime --help
+# 或使用 npx 零安装
+npx cogn --help
 ```
 
-## Usage
-
-### Run a Module
+## 快速开始
 
 ```bash
-cog run code-reviewer --args "def foo(): pass"
-```
+# 配置 LLM
+export LLM_PROVIDER=openai
+export OPENAI_API_KEY=sk-xxx
 
-### List Modules
+# 运行模块
+cog run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')"
 
-```bash
+# 列出模块
 cog list
-```
 
-### Pipe Mode (stdin/stdout)
-
-```bash
+# 管道模式
 echo "review this code" | cog pipe --module code-reviewer
 ```
 
-### Check Configuration
+## 与 Python 版的区别
 
-```bash
-cog doctor
-```
+| 功能 | Python (`cogn`) | Node.js (`cog`) |
+|------|----------------|-----------------|
+| 包名 | `cognitive-modules` | `cognitive-modules-cli` |
+| 安装 | `pip install` | `npm install -g` |
+| 子代理 | ✅ `@call:module` | ❌ 暂不支持 |
+| MCP Server | ✅ | ❌ 暂不支持 |
+| HTTP Server | ✅ | ❌ 暂不支持 |
 
-## Module Formats
+两个版本共享相同的模块格式和 v2.2 规范。
 
-### v2 (Recommended)
+## 支持的 Provider
 
-```
-my-module/
-├── module.yaml      # Machine-readable manifest
-├── prompt.md        # Human-readable prompt
-├── schema.json      # IO contract
-└── tests/
-    ├── case1.input.json
-    └── case1.expected.json
-```
+| Provider | 环境变量 | 别名 |
+|----------|----------|------|
+| OpenAI | `OPENAI_API_KEY` | - |
+| Anthropic | `ANTHROPIC_API_KEY` | - |
+| Gemini | `GEMINI_API_KEY` | - |
+| DeepSeek | `DEEPSEEK_API_KEY` | - |
+| MiniMax | `MINIMAX_API_KEY` | - |
+| Moonshot | `MOONSHOT_API_KEY` | `kimi` |
+| Qwen | `DASHSCOPE_API_KEY` | `tongyi` |
+| Ollama | `OLLAMA_HOST` | `local` |
 
-**module.yaml**:
-```yaml
-name: my-module
-version: 2.0.0
-responsibility: What this module does
-constraints:
-  no_network: true
-  no_side_effects: true
-output:
-  mode: json_strict
-  require_confidence: true
-  require_rationale: true
-  require_behavior_equivalence: true
-tools:
-  allowed: []
-```
-
-### v1 (Legacy, still supported)
-
-```
-my-module/
-├── MODULE.md        # Frontmatter + prompt combined
-└── schema.json
-```
-
-## Providers
-
-| Provider   | Environment Variable   | Default Model        |
-|------------|------------------------|----------------------|
-| Gemini     | `GEMINI_API_KEY`       | `gemini-3-flash`     |
-| OpenAI     | `OPENAI_API_KEY`       | `gpt-5.2`            |
-| Anthropic  | `ANTHROPIC_API_KEY`    | `claude-sonnet-4.5`  |
-| DeepSeek   | `DEEPSEEK_API_KEY`     | `deepseek-v3.2`      |
-| MiniMax    | `MINIMAX_API_KEY`      | `MiniMax-M2.1`       |
-| Moonshot   | `MOONSHOT_API_KEY`     | `kimi-k2.5`          |
-| Qwen       | `DASHSCOPE_API_KEY`    | `qwen3-max`          |
-| Ollama     | `OLLAMA_HOST`          | `llama4` (local)     |
-
-### Provider Aliases
+## 命令
 
-- `kimi` → Moonshot
-- `tongyi` / `dashscope` → Qwen
-- `local` → Ollama
-
-## Module Search Paths
-
-Modules are searched in order:
-
-1. `./cognitive/modules/` (project-local)
-2. `./.cognitive/modules/` (project-local, hidden)
-3. `~/.cognitive/modules/` (user-global)
-
-## Programmatic API
-
-```typescript
-import { getProvider, findModule, runModule } from 'cognitive-runtime';
-
-const provider = getProvider('gemini');
-const module = await findModule('code-reviewer', ['./cognitive/modules']);
-
-if (module) {
-  const result = await runModule(module, provider, {
-    args: 'def foo(): pass',
-  });
-  console.log(result.output);
-}
+```bash
+cog list                    # 列出模块
+cog run <module> --args "..." # 运行模块
+cog add <url> -m <module>   # 从 GitHub 添加模块
+cog update <module>         # 更新模块
+cog remove <module>         # 删除模块
+cog versions <url>          # 查看可用版本
+cog init <name>             # 创建新模块
+cog pipe --module <name>    # 管道模式
 ```
 
-## Development
+## 开发
 
 ```bash
-# Install dependencies
+# 安装依赖
 npm install
 
-# Build
+# 构建
 npm run build
 
-# Run in development
+# 开发模式运行
 npm run dev -- run code-reviewer --args "..."
 ```
 

package/dist/modules/loader.js

@@ -19,6 +19,18 @@ async function detectFormat(modulePath) {
         return 'v1';
     }
 }
+/**
+ * Detect v2.x sub-version from manifest
+ */
+function detectV2Version(manifest) {
+    if (manifest.tier || manifest.overflow || manifest.enums) {
+        return 'v2.2';
+    }
+    if (manifest.policies || manifest.failure) {
+        return 'v2.1';
+    }
+    return 'v2.0';
+}
 /**
  * Load v2 format module (module.yaml + prompt.md)
  */
@@ -29,6 +41,8 @@ async function loadModuleV2(modulePath) {
     // Read module.yaml
     const manifestContent = await fs.readFile(manifestFile, 'utf-8');
     const manifest = yaml.load(manifestContent);
+    // Detect v2.x version
+    const formatVersion = detectV2Version(manifest);
     // Read prompt.md
     let prompt = '';
     try {
@@ -40,17 +54,61 @@ async function loadModuleV2(modulePath) {
     // Read schema.json
     let inputSchema;
     let outputSchema;
+    let dataSchema;
+    let metaSchema;
     let errorSchema;
     try {
         const schemaContent = await fs.readFile(schemaFile, 'utf-8');
         const schema = JSON.parse(schemaContent);
         inputSchema = schema.input;
-        outputSchema = schema.output;
+        // Support both "data" (v2.2) and "output" (v2.1) aliases
+        dataSchema = schema.data || schema.output;
+        outputSchema = dataSchema; // Backward compat
+        metaSchema = schema.meta;
         errorSchema = schema.error;
     }
     catch {
         // Schema file is optional but recommended
     }
+    // Extract v2.2 fields
+    const tier = manifest.tier;
+    const schemaStrictness = manifest.schema_strictness || 'medium';
+    // Determine default max_items based on strictness (SPEC-v2.2)
+    const strictnessMaxItems = {
+        high: 0,
+        medium: 5,
+        low: 20
+    };
+    const defaultMaxItems = strictnessMaxItems[schemaStrictness] ?? 5;
+    const defaultEnabled = schemaStrictness !== 'high';
+    // Parse overflow config with strictness-based defaults
+    const overflowRaw = manifest.overflow || {};
+    const overflow = {
+        enabled: overflowRaw.enabled ?? defaultEnabled,
+        recoverable: overflowRaw.recoverable ?? true,
+        max_items: overflowRaw.max_items ?? defaultMaxItems,
+        require_suggested_mapping: overflowRaw.require_suggested_mapping ?? true
+    };
+    // Parse enums config
+    const enumsRaw = manifest.enums || {};
+    const enums = {
+        strategy: enumsRaw.strategy ??
+            (tier === 'exec' ? 'strict' : 'extensible'),
+        unknown_tag: enumsRaw.unknown_tag ?? 'custom'
+    };
+    // Parse compat config
+    const compatRaw = manifest.compat || {};
+    const compat = {
+        accepts_v21_payload: compatRaw.accepts_v21_payload ?? true,
+        runtime_auto_wrap: compatRaw.runtime_auto_wrap ?? true,
+        schema_output_alias: compatRaw.schema_output_alias ?? 'data'
+    };
+    // Parse meta config (including risk_rule)
+    const metaRaw = manifest.meta || {};
+    const metaConfig = {
+        required: metaRaw.required,
+        risk_rule: metaRaw.risk_rule,
+    };
     return {
         name: manifest.name || path.basename(modulePath),
         version: manifest.version || '1.0.0',
@@ -62,13 +120,26 @@ async function loadModuleV2(modulePath) {
         output: manifest.output,
         failure: manifest.failure,
         runtimeRequirements: manifest.runtime_requirements,
+        // v2.2 fields
+        tier,
+        schemaStrictness,
+        overflow,
+        enums,
+        compat,
+        metaConfig,
+        // Context and prompt
         context: manifest.context,
         prompt,
+        // Schemas
         inputSchema,
         outputSchema,
+        dataSchema,
+        metaSchema,
         errorSchema,
+        // Metadata
         location: modulePath,
         format: 'v2',
+        formatVersion,
     };
 }
 /**

package/dist/modules/runner.d.ts

@@ -1,6 +1,6 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.1: Envelope format support, clean input mapping
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  */
 import type { Provider, CognitiveModule, ModuleResult, ModuleInput } from '../types.js';
 export interface RunOptions {
@@ -8,5 +8,7 @@ export interface RunOptions {
     args?: string;
     verbose?: boolean;
     useEnvelope?: boolean;
+    useV22?: boolean;
+    enableRepair?: boolean;
 }
 export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;

package/dist/modules/runner.js

@@ -1,11 +1,116 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.1: Envelope format support, clean input mapping
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  */
+import { aggregateRisk, isV22Envelope } from '../types.js';
+// =============================================================================
+// Repair Pass (v2.2)
+// =============================================================================
+/**
+ * Attempt to repair envelope format issues without changing semantics.
+ *
+ * Repairs (lossless only):
+ * - Missing meta fields (fill with conservative defaults)
+ * - Truncate explain if too long
+ * - Trim whitespace from string fields
+ *
+ * Does NOT repair:
+ * - Invalid enum values (treated as validation failure)
+ */
+function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLength = 280) {
+    const repaired = { ...response };
+    // Ensure meta exists
+    if (!repaired.meta || typeof repaired.meta !== 'object') {
+        repaired.meta = {};
+    }
+    const meta = repaired.meta;
+    const data = (repaired.data ?? {});
+    // Repair confidence
+    if (typeof meta.confidence !== 'number') {
+        meta.confidence = data.confidence ?? 0.5;
+    }
+    meta.confidence = Math.max(0, Math.min(1, meta.confidence));
+    // Repair risk using configurable aggregation rule
+    if (!meta.risk) {
+        meta.risk = aggregateRisk(data, riskRule);
+    }
+    // Trim whitespace only (lossless), do NOT invent new values
+    if (typeof meta.risk === 'string') {
+        meta.risk = meta.risk.trim().toLowerCase();
+    }
+    // Repair explain
+    if (typeof meta.explain !== 'string') {
+        const rationale = data.rationale;
+        meta.explain = rationale ? String(rationale).slice(0, maxExplainLength) : 'No explanation provided';
+    }
+    // Trim whitespace (lossless)
+    const explainStr = meta.explain;
+    meta.explain = explainStr.trim();
+    if (meta.explain.length > maxExplainLength) {
+        meta.explain = meta.explain.slice(0, maxExplainLength - 3) + '...';
+    }
+    // Build proper v2.2 response
+    const builtMeta = {
+        confidence: meta.confidence,
+        risk: meta.risk,
+        explain: meta.explain
+    };
+    const result = repaired.ok === false ? {
+        ok: false,
+        meta: builtMeta,
+        error: repaired.error ?? { code: 'UNKNOWN', message: 'Unknown error' },
+        partial_data: repaired.partial_data
+    } : {
+        ok: true,
+        meta: builtMeta,
+        data: repaired.data
+    };
+    return result;
+}
+/**
+ * Wrap v2.1 response to v2.2 format
+ */
+function wrapV21ToV22(response, riskRule = 'max_changes_risk') {
+    if (isV22Envelope(response)) {
+        return response;
+    }
+    if (response.ok) {
+        const data = (response.data ?? {});
+        const confidence = data.confidence ?? 0.5;
+        const rationale = data.rationale ?? '';
+        return {
+            ok: true,
+            meta: {
+                confidence,
+                risk: aggregateRisk(data, riskRule),
+                explain: rationale.slice(0, 280) || 'No explanation provided'
+            },
+            data: data
+        };
+    }
+    else {
+        const errorMsg = response.error?.message ?? 'Unknown error';
+        return {
+            ok: false,
+            meta: {
+                confidence: 0,
+                risk: 'high',
+                explain: errorMsg.slice(0, 280)
+            },
+            error: response.error ?? { code: 'UNKNOWN', message: errorMsg },
+            partial_data: response.partial_data
+        };
+    }
+}
 export async function runModule(module, provider, options = {}) {
-    const { args, input, verbose = false, useEnvelope } = options;
+    const { args, input, verbose = false, useEnvelope, useV22, enableRepair = true } = options;
     // Determine if we should use envelope format
     const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
+    // Determine if we should use v2.2 format
+    const isV22Module = module.tier !== undefined || module.formatVersion === 'v2.2';
+    const shouldUseV22 = useV22 ?? (isV22Module || module.compat?.runtime_auto_wrap === true);
+    // Get risk_rule from module config
+    const riskRule = module.metaConfig?.risk_rule ?? 'max_changes_risk';
     // Build clean input data (v2 style: no $ARGUMENTS pollution)
     const inputData = input || {};
     // Map legacy --args to clean input
@@ -61,11 +166,21 @@ export async function runModule(module, provider, options = {}) {
     }
     // Add envelope format instructions
     if (shouldUseEnvelope) {
-        systemParts.push('', 'RESPONSE FORMAT (Envelope):');
-        systemParts.push('- Wrap your response in the envelope format');
-        systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
-        systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
-        systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+        if (shouldUseV22) {
+            systemParts.push('', 'RESPONSE FORMAT (Envelope v2.2):');
+            systemParts.push('- Wrap your response in the v2.2 envelope format with separate meta and data');
+            systemParts.push('- Success: { "ok": true, "meta": { "confidence": 0.9, "risk": "low", "explain": "short summary" }, "data": { ...payload... } }');
+            systemParts.push('- Error: { "ok": false, "meta": { "confidence": 0.0, "risk": "high", "explain": "error summary" }, "error": { "code": "ERROR_CODE", "message": "..." } }');
+            systemParts.push('- meta.explain must be ≤280 characters. data.rationale can be longer for detailed reasoning.');
+            systemParts.push('- meta.risk must be one of: "none", "low", "medium", "high"');
+        }
+        else {
+            systemParts.push('', 'RESPONSE FORMAT (Envelope):');
+            systemParts.push('- Wrap your response in the envelope format');
+            systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
+            systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
+            systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+        }
         if (module.output?.require_behavior_equivalence) {
             systemParts.push('- Include "behavior_equivalence" (boolean) in data');
         }
@@ -105,10 +220,46 @@ export async function runModule(module, provider, options = {}) {
     }
     // Handle envelope format
     if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
-        return parseEnvelopeResponse(parsed, result.content);
+        let response = parseEnvelopeResponse(parsed, result.content);
+        // Upgrade to v2.2 if needed
+        if (shouldUseV22 && response.ok && !('meta' in response && response.meta)) {
+            const upgraded = wrapV21ToV22(parsed, riskRule);
+            response = {
+                ok: true,
+                meta: upgraded.meta,
+                data: upgraded.data,
+                raw: result.content
+            };
+        }
+        // Apply repair pass if enabled and response needs it
+        if (enableRepair && response.ok && shouldUseV22) {
+            const repaired = repairEnvelope(response, riskRule);
+            response = {
+                ok: true,
+                meta: repaired.meta,
+                data: repaired.data,
+                raw: result.content
+            };
+        }
+        return response;
     }
     // Handle legacy format (non-envelope)
-    return parseLegacyResponse(parsed, result.content);
+    const legacyResult = parseLegacyResponse(parsed, result.content);
+    // Upgrade to v2.2 if requested
+    if (shouldUseV22 && legacyResult.ok) {
+        const data = (legacyResult.data ?? {});
+        return {
+            ok: true,
+            meta: {
+                confidence: data.confidence ?? 0.5,
+                risk: aggregateRisk(data, riskRule),
+                explain: (data.rationale ?? '').slice(0, 280) || 'No explanation provided'
+            },
+            data: legacyResult.data,
+            raw: result.content
+        };
+    }
+    return legacyResult;
 }
 /**
  * Check if response is in envelope format
@@ -120,11 +271,32 @@ function isEnvelopeResponse(obj) {
     return typeof o.ok === 'boolean';
 }
 /**
- * Parse envelope format response
+ * Parse envelope format response (supports both v2.1 and v2.2)
  */
 function parseEnvelopeResponse(response, raw) {
+    // Check if v2.2 format (has meta)
+    if (isV22Envelope(response)) {
+        if (response.ok) {
+            return {
+                ok: true,
+                meta: response.meta,
+                data: response.data,
+                raw,
+            };
+        }
+        else {
+            return {
+                ok: false,
+                meta: response.meta,
+                error: response.error,
+                partial_data: response.partial_data,
+                raw,
+            };
+        }
+    }
+    // v2.1 format
     if (response.ok) {
-        const data = response.data;
+        const data = (response.data ?? {});
         return {
             ok: true,
             data: {

package/dist/types.d.ts

@@ -33,6 +33,8 @@ export type SchemaStrictness = 'high' | 'medium' | 'low';
 export type RiskLevel = 'none' | 'low' | 'medium' | 'high';
 /** Enum extension strategy */
 export type EnumStrategy = 'strict' | 'extensible';
+/** Risk aggregation rule */
+export type RiskRule = 'max_changes_risk' | 'max_issues_risk' | 'explicit';
 export interface CognitiveModule {
     name: string;
     version: string;
@@ -49,6 +51,7 @@ export interface CognitiveModule {
     overflow?: OverflowConfig;
     enums?: EnumConfig;
     compat?: CompatConfig;
+    metaConfig?: MetaConfig;
     context?: 'fork' | 'main';
     prompt: string;
     inputSchema?: object;
@@ -115,6 +118,18 @@ export interface CompatConfig {
     runtime_auto_wrap?: boolean;
     schema_output_alias?: 'data' | 'output';
 }
+/** Meta field configuration (v2.2) */
+export interface MetaConfig {
+    required?: string[];
+    risk_rule?: RiskRule;
+    confidence?: {
+        min?: number;
+        max?: number;
+    };
+    explain?: {
+        max_chars?: number;
+    };
+}
 /**
  * Control plane metadata - unified across all modules.
  * Used for routing, logging, UI cards, and middleware decisions.
@@ -255,10 +270,15 @@ export declare function isV22Envelope<T>(response: EnvelopeResponse<T>): respons
 /** Check if response is successful */
 export declare function isEnvelopeSuccess<T>(response: EnvelopeResponse<T>): response is EnvelopeSuccessV22<T> | EnvelopeSuccessV21<T>;
 /** Extract meta from any envelope response */
-export declare function extractMeta<T>(response: EnvelopeResponse<T>): EnvelopeMeta;
-/** Aggregate risk from list of changes */
-export declare function aggregateRisk(changes: Array<{
-    risk?: RiskLevel;
-}>): RiskLevel;
+export declare function extractMeta<T>(response: EnvelopeResponse<T>, riskRule?: RiskRule): EnvelopeMeta;
+/**
+ * Aggregate risk based on configured rule.
+ *
+ * Rules:
+ * - max_changes_risk: max(data.changes[*].risk) - default
+ * - max_issues_risk: max(data.issues[*].risk) - for review modules
+ * - explicit: return "medium", module should set risk explicitly
+ */
+export declare function aggregateRisk(data: Record<string, unknown>, riskRule?: RiskRule): RiskLevel;
 /** Check if result should be escalated to human review */
 export declare function shouldEscalate<T>(response: EnvelopeResponse<T>, confidenceThreshold?: number): boolean;

package/dist/types.js

@@ -14,17 +14,17 @@ export function isEnvelopeSuccess(response) {
     return response.ok === true;
 }
 /** Extract meta from any envelope response */
-export function extractMeta(response) {
+export function extractMeta(response, riskRule = 'max_changes_risk') {
     if (isV22Envelope(response)) {
         return response.meta;
     }
     // Synthesize meta from v2.1 response
     if (response.ok) {
-        const data = response.data;
+        const data = (response.data ?? {});
         return {
-            confidence: data?.confidence ?? 0.5,
-            risk: 'medium',
-            explain: (data?.rationale ?? '').slice(0, 280) || 'No explanation',
+            confidence: data.confidence ?? 0.5,
+            risk: aggregateRisk(data, riskRule),
+            explain: (data.rationale ?? '').slice(0, 280) || 'No explanation',
         };
     }
     else {
@@ -35,20 +35,44 @@ export function extractMeta(response) {
         };
     }
 }
-/** Aggregate risk from list of changes */
-export function aggregateRisk(changes) {
+/** Aggregate risk from list of items */
+function aggregateRiskFromList(items) {
     const riskLevels = { none: 0, low: 1, medium: 2, high: 3 };
     const riskNames = ['none', 'low', 'medium', 'high'];
-    if (!changes || changes.length === 0) {
+    if (!items || items.length === 0) {
         return 'medium';
     }
     let maxLevel = 0;
-    for (const change of changes) {
-        const level = riskLevels[change.risk ?? 'medium'];
+    for (const item of items) {
+        const level = riskLevels[item.risk ?? 'medium'];
         maxLevel = Math.max(maxLevel, level);
     }
     return riskNames[maxLevel];
 }
+/**
+ * Aggregate risk based on configured rule.
+ *
+ * Rules:
+ * - max_changes_risk: max(data.changes[*].risk) - default
+ * - max_issues_risk: max(data.issues[*].risk) - for review modules
+ * - explicit: return "medium", module should set risk explicitly
+ */
+export function aggregateRisk(data, riskRule = 'max_changes_risk') {
+    if (riskRule === 'max_changes_risk') {
+        const changes = data.changes ?? [];
+        return aggregateRiskFromList(changes);
+    }
+    else if (riskRule === 'max_issues_risk') {
+        const issues = data.issues ?? [];
+        return aggregateRiskFromList(issues);
+    }
+    else if (riskRule === 'explicit') {
+        return 'medium'; // Module should override
+    }
+    // Fallback to changes
+    const changes = data.changes ?? [];
+    return aggregateRiskFromList(changes);
+}
 /** Check if result should be escalated to human review */
 export function shouldEscalate(response, confidenceThreshold = 0.7) {
     const meta = extractMeta(response);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",

package/src/modules/loader.ts

@@ -6,7 +6,21 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
-import type { CognitiveModule, ModuleConstraints, ModulePolicies, ToolsPolicy, OutputContract, FailureContract, RuntimeRequirements } from '../types.js';
+import type { 
+  CognitiveModule, 
+  ModuleConstraints, 
+  ModulePolicies, 
+  ToolsPolicy, 
+  OutputContract, 
+  FailureContract, 
+  RuntimeRequirements,
+  OverflowConfig,
+  EnumConfig,
+  CompatConfig,
+  MetaConfig,
+  ModuleTier,
+  SchemaStrictness
+} from '../types.js';
 
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
 
@@ -23,6 +37,19 @@ async function detectFormat(modulePath: string): Promise<'v1' | 'v2'> {
   }
 }
 
+/**
+ * Detect v2.x sub-version from manifest
+ */
+function detectV2Version(manifest: Record<string, unknown>): string {
+  if (manifest.tier || manifest.overflow || manifest.enums) {
+    return 'v2.2';
+  }
+  if (manifest.policies || manifest.failure) {
+    return 'v2.1';
+  }
+  return 'v2.0';
+}
+
 /**
  * Load v2 format module (module.yaml + prompt.md)
  */
@@ -35,6 +62,9 @@ async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
   const manifestContent = await fs.readFile(manifestFile, 'utf-8');
   const manifest = yaml.load(manifestContent) as Record<string, unknown>;
 
+  // Detect v2.x version
+  const formatVersion = detectV2Version(manifest);
+
   // Read prompt.md
   let prompt = '';
   try {
@@ -46,18 +76,68 @@ async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
   // Read schema.json
   let inputSchema: object | undefined;
   let outputSchema: object | undefined;
+  let dataSchema: object | undefined;
+  let metaSchema: object | undefined;
   let errorSchema: object | undefined;
   
   try {
     const schemaContent = await fs.readFile(schemaFile, 'utf-8');
     const schema = JSON.parse(schemaContent);
     inputSchema = schema.input;
-    outputSchema = schema.output;
+    // Support both "data" (v2.2) and "output" (v2.1) aliases
+    dataSchema = schema.data || schema.output;
+    outputSchema = dataSchema; // Backward compat
+    metaSchema = schema.meta;
     errorSchema = schema.error;
   } catch {
     // Schema file is optional but recommended
   }
 
+  // Extract v2.2 fields
+  const tier = manifest.tier as ModuleTier | undefined;
+  const schemaStrictness = (manifest.schema_strictness as SchemaStrictness) || 'medium';
+  
+  // Determine default max_items based on strictness (SPEC-v2.2)
+  const strictnessMaxItems: Record<SchemaStrictness, number> = {
+    high: 0,
+    medium: 5,
+    low: 20
+  };
+  const defaultMaxItems = strictnessMaxItems[schemaStrictness] ?? 5;
+  const defaultEnabled = schemaStrictness !== 'high';
+  
+  // Parse overflow config with strictness-based defaults
+  const overflowRaw = (manifest.overflow as Record<string, unknown>) || {};
+  const overflow: OverflowConfig = {
+    enabled: (overflowRaw.enabled as boolean) ?? defaultEnabled,
+    recoverable: (overflowRaw.recoverable as boolean) ?? true,
+    max_items: (overflowRaw.max_items as number) ?? defaultMaxItems,
+    require_suggested_mapping: (overflowRaw.require_suggested_mapping as boolean) ?? true
+  };
+  
+  // Parse enums config
+  const enumsRaw = (manifest.enums as Record<string, unknown>) || {};
+  const enums: EnumConfig = {
+    strategy: (enumsRaw.strategy as 'strict' | 'extensible') ?? 
+      (tier === 'exec' ? 'strict' : 'extensible'),
+    unknown_tag: (enumsRaw.unknown_tag as string) ?? 'custom'
+  };
+  
+  // Parse compat config
+  const compatRaw = (manifest.compat as Record<string, unknown>) || {};
+  const compat: CompatConfig = {
+    accepts_v21_payload: (compatRaw.accepts_v21_payload as boolean) ?? true,
+    runtime_auto_wrap: (compatRaw.runtime_auto_wrap as boolean) ?? true,
+    schema_output_alias: (compatRaw.schema_output_alias as 'data' | 'output') ?? 'data'
+  };
+  
+  // Parse meta config (including risk_rule)
+  const metaRaw = (manifest.meta as Record<string, unknown>) || {};
+  const metaConfig: MetaConfig = {
+    required: metaRaw.required as string[] | undefined,
+    risk_rule: metaRaw.risk_rule as 'max_changes_risk' | 'max_issues_risk' | 'explicit' | undefined,
+  };
+
   return {
     name: manifest.name as string || path.basename(modulePath),
     version: manifest.version as string || '1.0.0',
@@ -69,13 +149,26 @@ async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
     output: manifest.output as OutputContract | undefined,
     failure: manifest.failure as FailureContract | undefined,
     runtimeRequirements: manifest.runtime_requirements as RuntimeRequirements | undefined,
+    // v2.2 fields
+    tier,
+    schemaStrictness,
+    overflow,
+    enums,
+    compat,
+    metaConfig,
+    // Context and prompt
     context: manifest.context as 'fork' | 'main' | undefined,
     prompt,
+    // Schemas
     inputSchema,
     outputSchema,
+    dataSchema,
+    metaSchema,
     errorSchema,
+    // Metadata
     location: modulePath,
     format: 'v2',
+    formatVersion,
   };
 }
 

package/src/modules/runner.ts

@@ -1,6 +1,6 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.1: Envelope format support, clean input mapping
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
  */
 
 import type { 
@@ -8,11 +8,17 @@ import type {
   CognitiveModule, 
   ModuleResult, 
   ModuleResultV21,
+  ModuleResultV22,
   Message, 
   ModuleInput,
   EnvelopeResponse,
-  ModuleResultData
+  EnvelopeResponseV22,
+  EnvelopeMeta,
+  ModuleResultData,
+  RiskLevel,
+  RiskRule
 } from '../types.js';
+import { aggregateRisk, isV22Envelope } from '../types.js';
 
 export interface RunOptions {
   // Clean input (v2 style)
@@ -26,6 +32,130 @@ export interface RunOptions {
   
   // Force envelope format (default: auto-detect from module.output.envelope)
   useEnvelope?: boolean;
+  
+  // Force v2.2 format (default: auto-detect from module.tier)
+  useV22?: boolean;
+  
+  // Enable repair pass for validation failures (default: true)
+  enableRepair?: boolean;
+}
+
+// =============================================================================
+// Repair Pass (v2.2)
+// =============================================================================
+
+/**
+ * Attempt to repair envelope format issues without changing semantics.
+ * 
+ * Repairs (lossless only):
+ * - Missing meta fields (fill with conservative defaults)
+ * - Truncate explain if too long
+ * - Trim whitespace from string fields
+ * 
+ * Does NOT repair:
+ * - Invalid enum values (treated as validation failure)
+ */
+function repairEnvelope(
+  response: Record<string, unknown>,
+  riskRule: RiskRule = 'max_changes_risk',
+  maxExplainLength: number = 280
+): EnvelopeResponseV22<unknown> {
+  const repaired = { ...response };
+  
+  // Ensure meta exists
+  if (!repaired.meta || typeof repaired.meta !== 'object') {
+    repaired.meta = {};
+  }
+  
+  const meta = repaired.meta as Record<string, unknown>;
+  const data = (repaired.data ?? {}) as Record<string, unknown>;
+  
+  // Repair confidence
+  if (typeof meta.confidence !== 'number') {
+    meta.confidence = (data.confidence as number) ?? 0.5;
+  }
+  meta.confidence = Math.max(0, Math.min(1, meta.confidence as number));
+  
+  // Repair risk using configurable aggregation rule
+  if (!meta.risk) {
+    meta.risk = aggregateRisk(data, riskRule);
+  }
+  // Trim whitespace only (lossless), do NOT invent new values
+  if (typeof meta.risk === 'string') {
+    meta.risk = meta.risk.trim().toLowerCase();
+  }
+  
+  // Repair explain
+  if (typeof meta.explain !== 'string') {
+    const rationale = data.rationale as string | undefined;
+    meta.explain = rationale ? String(rationale).slice(0, maxExplainLength) : 'No explanation provided';
+  }
+  // Trim whitespace (lossless)
+  const explainStr = meta.explain as string;
+  meta.explain = explainStr.trim();
+  if ((meta.explain as string).length > maxExplainLength) {
+    meta.explain = (meta.explain as string).slice(0, maxExplainLength - 3) + '...';
+  }
+  
+  // Build proper v2.2 response
+  const builtMeta: EnvelopeMeta = {
+    confidence: meta.confidence as number,
+    risk: meta.risk as RiskLevel,
+    explain: meta.explain as string
+  };
+  
+  const result: EnvelopeResponseV22<unknown> = repaired.ok === false ? {
+    ok: false,
+    meta: builtMeta,
+    error: (repaired.error as { code: string; message: string }) ?? { code: 'UNKNOWN', message: 'Unknown error' },
+    partial_data: repaired.partial_data
+  } : {
+    ok: true,
+    meta: builtMeta,
+    data: repaired.data
+  };
+  
+  return result;
+}
+
+/**
+ * Wrap v2.1 response to v2.2 format
+ */
+function wrapV21ToV22(
+  response: EnvelopeResponse<unknown>,
+  riskRule: RiskRule = 'max_changes_risk'
+): EnvelopeResponseV22<unknown> {
+  if (isV22Envelope(response)) {
+    return response;
+  }
+  
+  if (response.ok) {
+    const data = (response.data ?? {}) as Record<string, unknown>;
+    const confidence = (data.confidence as number) ?? 0.5;
+    const rationale = (data.rationale as string) ?? '';
+    
+    return {
+      ok: true,
+      meta: {
+        confidence,
+        risk: aggregateRisk(data, riskRule),
+        explain: rationale.slice(0, 280) || 'No explanation provided'
+      },
+      data: data as ModuleResultData
+    };
+  } else {
+    const errorMsg = response.error?.message ?? 'Unknown error';
+    return {
+      ok: false,
+      meta: {
+        confidence: 0,
+        risk: 'high',
+        explain: errorMsg.slice(0, 280)
+      },
+      error: response.error ?? { code: 'UNKNOWN', message: errorMsg },
+      partial_data: response.partial_data
+    };
+  }
 }
 
 export async function runModule(
@@ -33,10 +163,17 @@ export async function runModule(
   provider: Provider,
   options: RunOptions = {}
 ): Promise<ModuleResult> {
-  const { args, input, verbose = false, useEnvelope } = options;
+  const { args, input, verbose = false, useEnvelope, useV22, enableRepair = true } = options;
 
   // Determine if we should use envelope format
   const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
+  
+  // Determine if we should use v2.2 format
+  const isV22Module = module.tier !== undefined || module.formatVersion === 'v2.2';
+  const shouldUseV22 = useV22 ?? (isV22Module || module.compat?.runtime_auto_wrap === true);
+  
+  // Get risk_rule from module config
+  const riskRule: RiskRule = module.metaConfig?.risk_rule ?? 'max_changes_risk';
 
   // Build clean input data (v2 style: no $ARGUMENTS pollution)
   const inputData: ModuleInput = input || {};
@@ -97,11 +234,20 @@ export async function runModule(
 
   // Add envelope format instructions
   if (shouldUseEnvelope) {
-    systemParts.push('', 'RESPONSE FORMAT (Envelope):');
-    systemParts.push('- Wrap your response in the envelope format');
-    systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
-    systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
-    systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+    if (shouldUseV22) {
+      systemParts.push('', 'RESPONSE FORMAT (Envelope v2.2):');
+      systemParts.push('- Wrap your response in the v2.2 envelope format with separate meta and data');
+      systemParts.push('- Success: { "ok": true, "meta": { "confidence": 0.9, "risk": "low", "explain": "short summary" }, "data": { ...payload... } }');
+      systemParts.push('- Error: { "ok": false, "meta": { "confidence": 0.0, "risk": "high", "explain": "error summary" }, "error": { "code": "ERROR_CODE", "message": "..." } }');
+      systemParts.push('- meta.explain must be ≤280 characters. data.rationale can be longer for detailed reasoning.');
+      systemParts.push('- meta.risk must be one of: "none", "low", "medium", "high"');
+    } else {
+      systemParts.push('', 'RESPONSE FORMAT (Envelope):');
+      systemParts.push('- Wrap your response in the envelope format');
+      systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
+      systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
+      systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+    }
     if (module.output?.require_behavior_equivalence) {
       systemParts.push('- Include "behavior_equivalence" (boolean) in data');
     }
@@ -144,11 +290,55 @@ export async function runModule(
 
   // Handle envelope format
   if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
-    return parseEnvelopeResponse(parsed, result.content);
+    let response = parseEnvelopeResponse(parsed, result.content);
+    
+    // Upgrade to v2.2 if needed
+    if (shouldUseV22 && response.ok && !('meta' in response && response.meta)) {
+      const upgraded = wrapV21ToV22(parsed as EnvelopeResponse<unknown>, riskRule);
+      response = {
+        ok: true,
+        meta: upgraded.meta as EnvelopeMeta,
+        data: (upgraded as { data?: ModuleResultData }).data,
+        raw: result.content
+      } as ModuleResultV22;
+    }
+    
+    // Apply repair pass if enabled and response needs it
+    if (enableRepair && response.ok && shouldUseV22) {
+      const repaired = repairEnvelope(
+        response as unknown as Record<string, unknown>,
+        riskRule
+      );
+      response = {
+        ok: true,
+        meta: repaired.meta as EnvelopeMeta,
+        data: (repaired as { data?: ModuleResultData }).data,
+        raw: result.content
+      } as ModuleResultV22;
+    }
+    
+    return response;
   }
 
   // Handle legacy format (non-envelope)
-  return parseLegacyResponse(parsed, result.content);
+  const legacyResult = parseLegacyResponse(parsed, result.content);
+  
+  // Upgrade to v2.2 if requested
+  if (shouldUseV22 && legacyResult.ok) {
+    const data = (legacyResult.data ?? {}) as Record<string, unknown>;
+    return {
+      ok: true,
+      meta: {
+        confidence: (data.confidence as number) ?? 0.5,
+        risk: aggregateRisk(data, riskRule),
+        explain: ((data.rationale as string) ?? '').slice(0, 280) || 'No explanation provided'
+      },
+      data: legacyResult.data,
+      raw: result.content
+    } as ModuleResultV22;
+  }
+  
+  return legacyResult;
 }
 
 /**
@@ -161,11 +351,32 @@ function isEnvelopeResponse(obj: unknown): obj is EnvelopeResponse {
 }
 
 /**
- * Parse envelope format response
+ * Parse envelope format response (supports both v2.1 and v2.2)
  */
-function parseEnvelopeResponse(response: EnvelopeResponse, raw: string): ModuleResult {
+function parseEnvelopeResponse(response: EnvelopeResponse<unknown>, raw: string): ModuleResult {
+  // Check if v2.2 format (has meta)
+  if (isV22Envelope(response)) {
+    if (response.ok) {
+      return {
+        ok: true,
+        meta: response.meta,
+        data: response.data as ModuleResultData,
+        raw,
+      } as ModuleResultV22;
+    } else {
+      return {
+        ok: false,
+        meta: response.meta,
+        error: response.error,
+        partial_data: response.partial_data,
+        raw,
+      } as ModuleResultV22;
+    }
+  }
+  
+  // v2.1 format
   if (response.ok) {
-    const data = response.data as ModuleResultData;
+    const data = (response.data ?? {}) as ModuleResultData & { confidence?: number };
     return {
       ok: true,
       data: {
@@ -175,14 +386,14 @@ function parseEnvelopeResponse(response: EnvelopeResponse, raw: string): ModuleR
         behavior_equivalence: data.behavior_equivalence,
       },
       raw,
-    };
+    } as ModuleResultV21;
   } else {
     return {
       ok: false,
       error: response.error,
       partial_data: response.partial_data,
       raw,
-    };
+    } as ModuleResultV21;
   }
 }
 

package/src/types.ts

@@ -50,6 +50,9 @@ export type RiskLevel = 'none' | 'low' | 'medium' | 'high';
 /** Enum extension strategy */
 export type EnumStrategy = 'strict' | 'extensible';
 
+/** Risk aggregation rule */
+export type RiskRule = 'max_changes_risk' | 'max_issues_risk' | 'explicit';
+
 // =============================================================================
 // Module Configuration (v2.2)
 // =============================================================================
@@ -94,6 +97,9 @@ export interface CognitiveModule {
   // v2.2: Compatibility configuration
   compat?: CompatConfig;
   
+  // v2.2: Meta configuration (including risk_rule)
+  metaConfig?: MetaConfig;
+  
   // Execution context
   context?: 'fork' | 'main';
   
@@ -181,6 +187,14 @@ export interface CompatConfig {
   schema_output_alias?: 'data' | 'output';
 }
 
+/** Meta field configuration (v2.2) */
+export interface MetaConfig {
+  required?: string[];
+  risk_rule?: RiskRule;
+  confidence?: { min?: number; max?: number };
+  explain?: { max_chars?: number };
+}
+
 // =============================================================================
 // Envelope Types (v2.2)
 // =============================================================================
@@ -386,18 +400,21 @@ export function isEnvelopeSuccess<T>(
 }
 
 /** Extract meta from any envelope response */
-export function extractMeta<T>(response: EnvelopeResponse<T>): EnvelopeMeta {
+export function extractMeta<T>(
+  response: EnvelopeResponse<T>,
+  riskRule: RiskRule = 'max_changes_risk'
+): EnvelopeMeta {
   if (isV22Envelope(response)) {
     return response.meta;
   }
   
   // Synthesize meta from v2.1 response
   if (response.ok) {
-    const data = response.data as Record<string, unknown>;
+    const data = (response.data ?? {}) as Record<string, unknown>;
     return {
-      confidence: (data?.confidence as number) ?? 0.5,
-      risk: 'medium',
-      explain: ((data?.rationale as string) ?? '').slice(0, 280) || 'No explanation',
+      confidence: (data.confidence as number) ?? 0.5,
+      risk: aggregateRisk(data, riskRule),
+      explain: ((data.rationale as string) ?? '').slice(0, 280) || 'No explanation',
     };
   } else {
     return {
@@ -408,24 +425,50 @@ export function extractMeta<T>(response: EnvelopeResponse<T>): EnvelopeMeta {
   }
 }
 
-/** Aggregate risk from list of changes */
-export function aggregateRisk(changes: Array<{ risk?: RiskLevel }>): RiskLevel {
+/** Aggregate risk from list of items */
+function aggregateRiskFromList(items: Array<{ risk?: RiskLevel }>): RiskLevel {
   const riskLevels: Record<RiskLevel, number> = { none: 0, low: 1, medium: 2, high: 3 };
   const riskNames: RiskLevel[] = ['none', 'low', 'medium', 'high'];
   
-  if (!changes || changes.length === 0) {
+  if (!items || items.length === 0) {
     return 'medium';
   }
   
   let maxLevel = 0;
-  for (const change of changes) {
-    const level = riskLevels[change.risk ?? 'medium'];
+  for (const item of items) {
+    const level = riskLevels[item.risk ?? 'medium'];
     maxLevel = Math.max(maxLevel, level);
   }
   
   return riskNames[maxLevel];
 }
 
+/** 
+ * Aggregate risk based on configured rule.
+ * 
+ * Rules:
+ * - max_changes_risk: max(data.changes[*].risk) - default
+ * - max_issues_risk: max(data.issues[*].risk) - for review modules
+ * - explicit: return "medium", module should set risk explicitly
+ */
+export function aggregateRisk(
+  data: Record<string, unknown>,
+  riskRule: RiskRule = 'max_changes_risk'
+): RiskLevel {
+  if (riskRule === 'max_changes_risk') {
+    const changes = (data.changes as Array<{ risk?: RiskLevel }>) ?? [];
+    return aggregateRiskFromList(changes);
+  } else if (riskRule === 'max_issues_risk') {
+    const issues = (data.issues as Array<{ risk?: RiskLevel }>) ?? [];
+    return aggregateRiskFromList(issues);
+  } else if (riskRule === 'explicit') {
+    return 'medium'; // Module should override
+  }
+  // Fallback to changes
+  const changes = (data.changes as Array<{ risk?: RiskLevel }>) ?? [];
+  return aggregateRiskFromList(changes);
+}
+
 /** Check if result should be escalated to human review */
 export function shouldEscalate<T>(
   response: EnvelopeResponse<T>,