cognitive-runtime 0.3.0 → 0.4.0

package/dist/cli.js

@@ -10,7 +10,7 @@
 import { parseArgs } from 'node:util';
 import { getProvider, listProviders } from './providers/index.js';
 import { run, list, pipe, init } from './commands/index.js';
-const VERSION = '0.3.0';
+const VERSION = '0.4.0';
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];

package/dist/commands/pipe.js

@@ -36,8 +36,6 @@ export async function pipe(ctx, options) {
         const result = await runModule(module, ctx.provider, {
             args: inputData ? undefined : input,
             input: inputData,
-            validateInput: !options.noValidate,
-            validateOutput: !options.noValidate,
         });
         // Output JSON to stdout
         console.log(JSON.stringify(result.output));

package/dist/commands/run.js

@@ -30,8 +30,6 @@ export async function run(moduleName, ctx, options = {}) {
         const result = await runModule(module, ctx.provider, {
             args: options.args,
             input: inputData,
-            validateInput: !options.noValidate,
-            validateOutput: !options.noValidate,
             verbose: options.verbose || ctx.verbose,
         });
         return {

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Exports all public APIs for programmatic use.
  */
-export type { Provider, InvokeParams, InvokeResult, Message, CognitiveModule, ModuleResult, CommandContext, CommandResult, } from './types.js';
+export type { Provider, InvokeParams, InvokeResult, Message, CognitiveModule, ModuleResult, ModuleInput, ModuleConstraints, ToolsPolicy, OutputContract, FailureContract, CommandContext, CommandResult, } from './types.js';
 export { getProvider, listProviders, GeminiProvider, OpenAIProvider, AnthropicProvider, BaseProvider, } from './providers/index.js';
 export { loadModule, findModule, listModules, getDefaultSearchPaths, runModule, } from './modules/index.js';
 export { run, list, pipe } from './commands/index.js';

package/dist/modules/loader.d.ts

@@ -1,7 +1,11 @@
 /**
  * Module Loader - Load and parse Cognitive Modules
+ * Supports both v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
  */
 import type { CognitiveModule } from '../types.js';
+/**
+ * Load a Cognitive Module (auto-detects format)
+ */
 export declare function loadModule(modulePath: string): Promise<CognitiveModule>;
 export declare function findModule(name: string, searchPaths: string[]): Promise<CognitiveModule | null>;
 export declare function listModules(searchPaths: string[]): Promise<CognitiveModule[]>;

package/dist/modules/loader.js

@@ -1,11 +1,78 @@
 /**
  * Module Loader - Load and parse Cognitive Modules
+ * Supports both v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
-export async function loadModule(modulePath) {
+/**
+ * Detect module format version
+ */
+async function detectFormat(modulePath) {
+    const v2Manifest = path.join(modulePath, 'module.yaml');
+    try {
+        await fs.access(v2Manifest);
+        return 'v2';
+    }
+    catch {
+        return 'v1';
+    }
+}
+/**
+ * Load v2 format module (module.yaml + prompt.md)
+ */
+async function loadModuleV2(modulePath) {
+    const manifestFile = path.join(modulePath, 'module.yaml');
+    const promptFile = path.join(modulePath, 'prompt.md');
+    const schemaFile = path.join(modulePath, 'schema.json');
+    // Read module.yaml
+    const manifestContent = await fs.readFile(manifestFile, 'utf-8');
+    const manifest = yaml.load(manifestContent);
+    // Read prompt.md
+    let prompt = '';
+    try {
+        prompt = await fs.readFile(promptFile, 'utf-8');
+    }
+    catch {
+        // prompt.md is optional, manifest may include inline prompt
+    }
+    // Read schema.json
+    let inputSchema;
+    let outputSchema;
+    let errorSchema;
+    try {
+        const schemaContent = await fs.readFile(schemaFile, 'utf-8');
+        const schema = JSON.parse(schemaContent);
+        inputSchema = schema.input;
+        outputSchema = schema.output;
+        errorSchema = schema.error;
+    }
+    catch {
+        // Schema file is optional but recommended
+    }
+    return {
+        name: manifest.name || path.basename(modulePath),
+        version: manifest.version || '1.0.0',
+        responsibility: manifest.responsibility || '',
+        excludes: manifest.excludes || [],
+        constraints: manifest.constraints,
+        tools: manifest.tools,
+        output: manifest.output,
+        failure: manifest.failure,
+        context: manifest.context,
+        prompt,
+        inputSchema,
+        outputSchema,
+        errorSchema,
+        location: modulePath,
+        format: 'v2',
+    };
+}
+/**
+ * Load v1 format module (MODULE.md with frontmatter)
+ */
+async function loadModuleV1(modulePath) {
     const moduleFile = path.join(modulePath, 'MODULE.md');
     const schemaFile = path.join(modulePath, 'schema.json');
     // Read MODULE.md
@@ -29,29 +96,66 @@ export async function loadModule(modulePath) {
     catch {
         // Schema file is optional
     }
+    // Extract constraints from v1 format
+    const constraints = {};
+    const v1Constraints = frontmatter.constraints;
+    if (v1Constraints) {
+        constraints.no_network = v1Constraints.no_network;
+        constraints.no_side_effects = v1Constraints.no_side_effects;
+        constraints.no_inventing_data = v1Constraints.no_inventing_data;
+    }
     return {
         name: frontmatter.name || path.basename(modulePath),
         version: frontmatter.version || '1.0.0',
         responsibility: frontmatter.responsibility || '',
         excludes: frontmatter.excludes || [],
+        constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
         context: frontmatter.context,
         prompt,
         inputSchema,
         outputSchema,
         location: modulePath,
+        format: 'v1',
     };
 }
+/**
+ * Load a Cognitive Module (auto-detects format)
+ */
+export async function loadModule(modulePath) {
+    const format = await detectFormat(modulePath);
+    if (format === 'v2') {
+        return loadModuleV2(modulePath);
+    }
+    else {
+        return loadModuleV1(modulePath);
+    }
+}
+/**
+ * Check if a directory contains a valid module
+ */
+async function isValidModule(modulePath) {
+    const v2Manifest = path.join(modulePath, 'module.yaml');
+    const v1Module = path.join(modulePath, 'MODULE.md');
+    try {
+        await fs.access(v2Manifest);
+        return true;
+    }
+    catch {
+        try {
+            await fs.access(v1Module);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
 export async function findModule(name, searchPaths) {
     for (const basePath of searchPaths) {
         const modulePath = path.join(basePath, name);
-        const moduleFile = path.join(modulePath, 'MODULE.md');
-        try {
-            await fs.access(moduleFile);
+        if (await isValidModule(modulePath)) {
             return await loadModule(modulePath);
         }
-        catch {
-            // Module not found in this path, continue
-        }
     }
     return null;
 }
@@ -63,14 +167,14 @@ export async function listModules(searchPaths) {
             for (const entry of entries) {
                 if (entry.isDirectory()) {
                     const modulePath = path.join(basePath, entry.name);
-                    const moduleFile = path.join(modulePath, 'MODULE.md');
-                    try {
-                        await fs.access(moduleFile);
-                        const module = await loadModule(modulePath);
-                        modules.push(module);
-                    }
-                    catch {
-                        // Not a valid module, skip
+                    if (await isValidModule(modulePath)) {
+                        try {
+                            const module = await loadModule(modulePath);
+                            modules.push(module);
+                        }
+                        catch {
+                            // Skip invalid modules
+                        }
                     }
                 }
             }

package/dist/modules/runner.d.ts

@@ -1,12 +1,11 @@
 /**
  * Module Runner - Execute Cognitive Modules
+ * v2: Clean input mapping, no CLI pollution
  */
-import type { Provider, CognitiveModule, ModuleResult } from '../types.js';
+import type { Provider, CognitiveModule, ModuleResult, ModuleInput } from '../types.js';
 export interface RunOptions {
+    input?: ModuleInput;
     args?: string;
-    input?: Record<string, unknown>;
-    validateInput?: boolean;
-    validateOutput?: boolean;
     verbose?: boolean;
 }
 export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;

package/dist/modules/runner.js

@@ -1,43 +1,68 @@
 /**
  * Module Runner - Execute Cognitive Modules
+ * v2: Clean input mapping, no CLI pollution
  */
 export async function runModule(module, provider, options = {}) {
     const { args, input, verbose = false } = options;
-    // Build input data
-    let inputData = input || {};
-    if (args) {
-        inputData = { $ARGUMENTS: args, query: args };
+    // Build clean input data (v2 style: no $ARGUMENTS pollution)
+    const inputData = input || {};
+    // Map legacy --args to clean input
+    if (args && !inputData.code && !inputData.query) {
+        // Determine if args looks like code or natural language
+        if (looksLikeCode(args)) {
+            inputData.code = args;
+        }
+        else {
+            inputData.query = args;
+        }
     }
-    // Build prompt
+    // Build prompt with clean substitution
     const prompt = buildPrompt(module, inputData);
     if (verbose) {
+        console.error('--- Module ---');
+        console.error(`Name: ${module.name} (${module.format})`);
+        console.error(`Responsibility: ${module.responsibility}`);
+        console.error('--- Input ---');
+        console.error(JSON.stringify(inputData, null, 2));
         console.error('--- Prompt ---');
         console.error(prompt);
-        console.error('--- End Prompt ---');
+        console.error('--- End ---');
+    }
+    // Build system message based on module config
+    const systemParts = [
+        `You are executing the "${module.name}" Cognitive Module.`,
+        '',
+        `RESPONSIBILITY: ${module.responsibility}`,
+    ];
+    if (module.excludes.length > 0) {
+        systemParts.push('', 'YOU MUST NOT:');
+        module.excludes.forEach(e => systemParts.push(`- ${e}`));
+    }
+    if (module.constraints) {
+        systemParts.push('', 'CONSTRAINTS:');
+        if (module.constraints.no_network)
+            systemParts.push('- No network access');
+        if (module.constraints.no_side_effects)
+            systemParts.push('- No side effects');
+        if (module.constraints.no_file_write)
+            systemParts.push('- No file writes');
+        if (module.constraints.no_inventing_data)
+            systemParts.push('- Do not invent data');
+    }
+    if (module.output?.require_behavior_equivalence) {
+        systemParts.push('', 'BEHAVIOR EQUIVALENCE:');
+        systemParts.push('- You MUST set behavior_equivalence=true ONLY if the output is functionally identical');
+        systemParts.push('- If unsure, set behavior_equivalence=false and explain in rationale');
+    }
+    systemParts.push('', 'OUTPUT FORMAT:');
+    systemParts.push('- Respond with ONLY valid JSON');
+    systemParts.push('- Include "confidence" (0-1) and "rationale" fields');
+    if (module.output?.require_behavior_equivalence) {
+        systemParts.push('- Include "behavior_equivalence" (boolean) field');
     }
-    // Build messages
     const messages = [
-        {
-            role: 'system',
-            content: `You are executing the "${module.name}" Cognitive Module.
-
-RESPONSIBILITY: ${module.responsibility}
-
-YOU MUST NOT:
-${module.excludes.map(e => `- ${e}`).join('\n')}
-
-REQUIRED OUTPUT FORMAT:
-You MUST respond with a valid JSON object. Include these fields:
-- All fields required by the output schema
-- "confidence": a number between 0 and 1
-- "rationale": a string explaining your reasoning
-
-Respond with ONLY valid JSON, no markdown code blocks.`,
-        },
-        {
-            role: 'user',
-            content: prompt,
-        },
+        { role: 'system', content: systemParts.join('\n') },
+        { role: 'user', content: prompt },
     ];
     // Invoke provider
     const result = await provider.invoke({
@@ -53,7 +78,6 @@ Respond with ONLY valid JSON, no markdown code blocks.`,
     // Parse response
     let output;
     try {
-        // Try to extract JSON from markdown code blocks
         const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
         const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
         output = JSON.parse(jsonStr.trim());
@@ -61,33 +85,65 @@ Respond with ONLY valid JSON, no markdown code blocks.`,
     catch {
         throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
     }
-    // Extract confidence and rationale
+    // Extract standard fields
     const outputObj = output;
     const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
     const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
+    const behaviorEquivalence = typeof outputObj.behavior_equivalence === 'boolean'
+        ? outputObj.behavior_equivalence
+        : undefined;
     return {
         output,
         confidence,
         rationale,
+        behaviorEquivalence,
         raw: result.content,
     };
 }
-function buildPrompt(module, inputData) {
+/**
+ * Build prompt with clean variable substitution
+ */
+function buildPrompt(module, input) {
     let prompt = module.prompt;
-    // Substitute $ARGUMENTS
-    const argsValue = String(inputData.$ARGUMENTS || inputData.query || '');
+    // v2 style: substitute ${variable} placeholders
+    for (const [key, value] of Object.entries(input)) {
+        const strValue = typeof value === 'string' ? value : JSON.stringify(value);
+        prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), strValue);
+    }
+    // v1 compatibility: substitute $ARGUMENTS
+    const argsValue = input.code || input.query || '';
     prompt = prompt.replace(/\$ARGUMENTS/g, argsValue);
-    // Substitute $N placeholders
-    const argsList = argsValue.split(/\s+/);
-    argsList.forEach((arg, i) => {
-        prompt = prompt.replace(new RegExp(`\\$${i}`, 'g'), arg);
-        prompt = prompt.replace(new RegExp(`\\$ARGUMENTS\\[${i}\\]`, 'g'), arg);
-    });
-    // Substitute other input fields
-    for (const [key, value] of Object.entries(inputData)) {
-        if (key !== '$ARGUMENTS' && key !== 'query') {
-            prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), String(value));
+    // Substitute $N placeholders (v1 compatibility)
+    if (typeof argsValue === 'string') {
+        const argsList = argsValue.split(/\s+/);
+        argsList.forEach((arg, i) => {
+            prompt = prompt.replace(new RegExp(`\\$${i}\\b`, 'g'), arg);
+        });
+    }
+    // Append input summary if not already in prompt
+    if (!prompt.includes(argsValue) && argsValue) {
+        prompt += '\n\n## Input\n\n';
+        if (input.code) {
+            prompt += '```\n' + input.code + '\n```\n';
+        }
+        if (input.query) {
+            prompt += input.query + '\n';
+        }
+        if (input.language) {
+            prompt += `\nLanguage: ${input.language}\n`;
         }
     }
     return prompt;
 }
+/**
+ * Heuristic to detect if input looks like code
+ */
+function looksLikeCode(str) {
+    const codeIndicators = [
+        /^(def|function|class|const|let|var|import|export|public|private)\s/,
+        /[{};()]/,
+        /=>/,
+        /\.(py|js|ts|go|rs|java|cpp|c|rb)$/,
+    ];
+    return codeIndicators.some(re => re.test(str));
+}

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
+ * Version 2.0 - With tools policy, failure contract, and behavior equivalence
  */
 export interface Provider {
     name: string;
@@ -29,16 +30,41 @@ export interface CognitiveModule {
     version: string;
     responsibility: string;
     excludes: string[];
+    constraints?: ModuleConstraints;
+    tools?: ToolsPolicy;
+    output?: OutputContract;
+    failure?: FailureContract;
     context?: 'fork' | 'main';
     prompt: string;
     inputSchema?: object;
     outputSchema?: object;
+    errorSchema?: object;
     location: string;
+    format: 'v1' | 'v2';
+}
+export interface ModuleConstraints {
+    no_network?: boolean;
+    no_side_effects?: boolean;
+    no_file_write?: boolean;
+    no_inventing_data?: boolean;
+}
+export interface ToolsPolicy {
+    allowed: string[];
+}
+export interface OutputContract {
+    mode?: 'json_strict' | 'json_lenient' | 'text';
+    require_confidence?: boolean;
+    require_rationale?: boolean;
+    require_behavior_equivalence?: boolean;
+}
+export interface FailureContract {
+    schema?: object;
 }
 export interface ModuleResult {
     output: unknown;
     confidence: number;
     rationale: string;
+    behaviorEquivalence?: boolean;
     raw?: string;
 }
 export interface CommandContext {
@@ -51,3 +77,10 @@ export interface CommandResult {
     data?: unknown;
     error?: string;
 }
+export interface ModuleInput {
+    code?: string;
+    query?: string;
+    language?: string;
+    options?: Record<string, unknown>;
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -1,4 +1,5 @@
 /**
  * Cognitive Runtime - Core Types
+ * Version 2.0 - With tools policy, failure contract, and behavior equivalence
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-runtime",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Cognitive Runtime - Structured AI Task Execution",
   "type": "module",
   "main": "dist/index.js",

package/src/cli.ts

@@ -13,7 +13,7 @@ import { getProvider, listProviders } from './providers/index.js';
 import { run, list, pipe, init } from './commands/index.js';
 import type { CommandContext } from './types.js';
 
-const VERSION = '0.3.0';
+const VERSION = '0.4.0';
 
 async function main() {
   const args = process.argv.slice(2);

package/src/commands/pipe.ts

@@ -52,8 +52,6 @@ export async function pipe(
     const result = await runModule(module, ctx.provider, {
       args: inputData ? undefined : input,
       input: inputData,
-      validateInput: !options.noValidate,
-      validateOutput: !options.noValidate,
     });
 
     // Output JSON to stdout

package/src/commands/run.ts

@@ -47,8 +47,6 @@ export async function run(
     const result = await runModule(module, ctx.provider, {
       args: options.args,
       input: inputData,
-      validateInput: !options.noValidate,
-      validateOutput: !options.noValidate,
       verbose: options.verbose || ctx.verbose,
     });
 

package/src/index.ts

@@ -12,6 +12,11 @@ export type {
   Message,
   CognitiveModule,
   ModuleResult,
+  ModuleInput,
+  ModuleConstraints,
+  ToolsPolicy,
+  OutputContract,
+  FailureContract,
   CommandContext,
   CommandResult,
 } from './types.js';

package/src/modules/loader.ts

@@ -1,15 +1,86 @@
 /**
  * Module Loader - Load and parse Cognitive Modules
+ * Supports both v1 (MODULE.md) and v2 (module.yaml + prompt.md) formats
  */
 
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
-import type { CognitiveModule } from '../types.js';
+import type { CognitiveModule, ModuleConstraints, ToolsPolicy, OutputContract, FailureContract } from '../types.js';
 
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
 
-export async function loadModule(modulePath: string): Promise<CognitiveModule> {
+/**
+ * Detect module format version
+ */
+async function detectFormat(modulePath: string): Promise<'v1' | 'v2'> {
+  const v2Manifest = path.join(modulePath, 'module.yaml');
+  try {
+    await fs.access(v2Manifest);
+    return 'v2';
+  } catch {
+    return 'v1';
+  }
+}
+
+/**
+ * Load v2 format module (module.yaml + prompt.md)
+ */
+async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
+  const manifestFile = path.join(modulePath, 'module.yaml');
+  const promptFile = path.join(modulePath, 'prompt.md');
+  const schemaFile = path.join(modulePath, 'schema.json');
+
+  // Read module.yaml
+  const manifestContent = await fs.readFile(manifestFile, 'utf-8');
+  const manifest = yaml.load(manifestContent) as Record<string, unknown>;
+
+  // Read prompt.md
+  let prompt = '';
+  try {
+    prompt = await fs.readFile(promptFile, 'utf-8');
+  } catch {
+    // prompt.md is optional, manifest may include inline prompt
+  }
+
+  // Read schema.json
+  let inputSchema: object | undefined;
+  let outputSchema: 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;
+    errorSchema = schema.error;
+  } catch {
+    // Schema file is optional but recommended
+  }
+
+  return {
+    name: manifest.name as string || path.basename(modulePath),
+    version: manifest.version as string || '1.0.0',
+    responsibility: manifest.responsibility as string || '',
+    excludes: (manifest.excludes as string[]) || [],
+    constraints: manifest.constraints as ModuleConstraints | undefined,
+    tools: manifest.tools as ToolsPolicy | undefined,
+    output: manifest.output as OutputContract | undefined,
+    failure: manifest.failure as FailureContract | undefined,
+    context: manifest.context as 'fork' | 'main' | undefined,
+    prompt,
+    inputSchema,
+    outputSchema,
+    errorSchema,
+    location: modulePath,
+    format: 'v2',
+  };
+}
+
+/**
+ * Load v1 format module (MODULE.md with frontmatter)
+ */
+async function loadModuleV1(modulePath: string): Promise<CognitiveModule> {
   const moduleFile = path.join(modulePath, 'MODULE.md');
   const schemaFile = path.join(modulePath, 'schema.json');
 
@@ -38,29 +109,69 @@ export async function loadModule(modulePath: string): Promise<CognitiveModule> {
     // Schema file is optional
   }
 
+  // Extract constraints from v1 format
+  const constraints: ModuleConstraints = {};
+  const v1Constraints = frontmatter.constraints as Record<string, boolean> | undefined;
+  if (v1Constraints) {
+    constraints.no_network = v1Constraints.no_network;
+    constraints.no_side_effects = v1Constraints.no_side_effects;
+    constraints.no_inventing_data = v1Constraints.no_inventing_data;
+  }
+
   return {
     name: frontmatter.name as string || path.basename(modulePath),
     version: frontmatter.version as string || '1.0.0',
     responsibility: frontmatter.responsibility as string || '',
     excludes: (frontmatter.excludes as string[]) || [],
+    constraints: Object.keys(constraints).length > 0 ? constraints : undefined,
     context: frontmatter.context as 'fork' | 'main' | undefined,
     prompt,
     inputSchema,
     outputSchema,
     location: modulePath,
+    format: 'v1',
   };
 }
 
+/**
+ * Load a Cognitive Module (auto-detects format)
+ */
+export async function loadModule(modulePath: string): Promise<CognitiveModule> {
+  const format = await detectFormat(modulePath);
+  
+  if (format === 'v2') {
+    return loadModuleV2(modulePath);
+  } else {
+    return loadModuleV1(modulePath);
+  }
+}
+
+/**
+ * Check if a directory contains a valid module
+ */
+async function isValidModule(modulePath: string): Promise<boolean> {
+  const v2Manifest = path.join(modulePath, 'module.yaml');
+  const v1Module = path.join(modulePath, 'MODULE.md');
+  
+  try {
+    await fs.access(v2Manifest);
+    return true;
+  } catch {
+    try {
+      await fs.access(v1Module);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
 export async function findModule(name: string, searchPaths: string[]): Promise<CognitiveModule | null> {
   for (const basePath of searchPaths) {
     const modulePath = path.join(basePath, name);
-    const moduleFile = path.join(modulePath, 'MODULE.md');
     
-    try {
-      await fs.access(moduleFile);
+    if (await isValidModule(modulePath)) {
       return await loadModule(modulePath);
-    } catch {
-      // Module not found in this path, continue
     }
   }
   
@@ -77,14 +188,14 @@ export async function listModules(searchPaths: string[]): Promise<CognitiveModul
       for (const entry of entries) {
         if (entry.isDirectory()) {
           const modulePath = path.join(basePath, entry.name);
-          const moduleFile = path.join(modulePath, 'MODULE.md');
           
-          try {
-            await fs.access(moduleFile);
-            const module = await loadModule(modulePath);
-            modules.push(module);
-          } catch {
-            // Not a valid module, skip
+          if (await isValidModule(modulePath)) {
+            try {
+              const module = await loadModule(modulePath);
+              modules.push(module);
+            } catch {
+              // Skip invalid modules
+            }
           }
         }
       }

package/src/modules/runner.ts

@@ -1,14 +1,18 @@
 /**
  * Module Runner - Execute Cognitive Modules
+ * v2: Clean input mapping, no CLI pollution
  */
 
-import type { Provider, CognitiveModule, ModuleResult, Message } from '../types.js';
+import type { Provider, CognitiveModule, ModuleResult, Message, ModuleInput } from '../types.js';
 
 export interface RunOptions {
+  // Clean input (v2 style)
+  input?: ModuleInput;
+  
+  // Legacy CLI args (v1 compatibility) - mapped to input.code or input.query
   args?: string;
-  input?: Record<string, unknown>;
-  validateInput?: boolean;
-  validateOutput?: boolean;
+  
+  // Runtime options
   verbose?: boolean;
 }
 
@@ -19,44 +23,69 @@ export async function runModule(
 ): Promise<ModuleResult> {
   const { args, input, verbose = false } = options;
 
-  // Build input data
-  let inputData: Record<string, unknown> = input || {};
-  if (args) {
-    inputData = { $ARGUMENTS: args, query: args };
+  // Build clean input data (v2 style: no $ARGUMENTS pollution)
+  const inputData: ModuleInput = input || {};
+  
+  // Map legacy --args to clean input
+  if (args && !inputData.code && !inputData.query) {
+    // Determine if args looks like code or natural language
+    if (looksLikeCode(args)) {
+      inputData.code = args;
+    } else {
+      inputData.query = args;
+    }
   }
 
-  // Build prompt
+  // Build prompt with clean substitution
   const prompt = buildPrompt(module, inputData);
 
   if (verbose) {
+    console.error('--- Module ---');
+    console.error(`Name: ${module.name} (${module.format})`);
+    console.error(`Responsibility: ${module.responsibility}`);
+    console.error('--- Input ---');
+    console.error(JSON.stringify(inputData, null, 2));
     console.error('--- Prompt ---');
     console.error(prompt);
-    console.error('--- End Prompt ---');
+    console.error('--- End ---');
+  }
+
+  // Build system message based on module config
+  const systemParts: string[] = [
+    `You are executing the "${module.name}" Cognitive Module.`,
+    '',
+    `RESPONSIBILITY: ${module.responsibility}`,
+  ];
+
+  if (module.excludes.length > 0) {
+    systemParts.push('', 'YOU MUST NOT:');
+    module.excludes.forEach(e => systemParts.push(`- ${e}`));
+  }
+
+  if (module.constraints) {
+    systemParts.push('', 'CONSTRAINTS:');
+    if (module.constraints.no_network) systemParts.push('- No network access');
+    if (module.constraints.no_side_effects) systemParts.push('- No side effects');
+    if (module.constraints.no_file_write) systemParts.push('- No file writes');
+    if (module.constraints.no_inventing_data) systemParts.push('- Do not invent data');
+  }
+
+  if (module.output?.require_behavior_equivalence) {
+    systemParts.push('', 'BEHAVIOR EQUIVALENCE:');
+    systemParts.push('- You MUST set behavior_equivalence=true ONLY if the output is functionally identical');
+    systemParts.push('- If unsure, set behavior_equivalence=false and explain in rationale');
+  }
+
+  systemParts.push('', 'OUTPUT FORMAT:');
+  systemParts.push('- Respond with ONLY valid JSON');
+  systemParts.push('- Include "confidence" (0-1) and "rationale" fields');
+  if (module.output?.require_behavior_equivalence) {
+    systemParts.push('- Include "behavior_equivalence" (boolean) field');
   }
 
-  // Build messages
   const messages: Message[] = [
-    {
-      role: 'system',
-      content: `You are executing the "${module.name}" Cognitive Module.
-
-RESPONSIBILITY: ${module.responsibility}
-
-YOU MUST NOT:
-${module.excludes.map(e => `- ${e}`).join('\n')}
-
-REQUIRED OUTPUT FORMAT:
-You MUST respond with a valid JSON object. Include these fields:
-- All fields required by the output schema
-- "confidence": a number between 0 and 1
-- "rationale": a string explaining your reasoning
-
-Respond with ONLY valid JSON, no markdown code blocks.`,
-    },
-    {
-      role: 'user',
-      content: prompt,
-    },
+    { role: 'system', content: systemParts.join('\n') },
+    { role: 'user', content: prompt },
   ];
 
   // Invoke provider
@@ -75,7 +104,6 @@ Respond with ONLY valid JSON, no markdown code blocks.`,
   // Parse response
   let output: unknown;
   try {
-    // Try to extract JSON from markdown code blocks
     const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
     const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
     output = JSON.parse(jsonStr.trim());
@@ -83,39 +111,73 @@ Respond with ONLY valid JSON, no markdown code blocks.`,
     throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
   }
 
-  // Extract confidence and rationale
+  // Extract standard fields
   const outputObj = output as Record<string, unknown>;
   const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
   const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
+  const behaviorEquivalence = typeof outputObj.behavior_equivalence === 'boolean' 
+    ? outputObj.behavior_equivalence 
+    : undefined;
 
   return {
     output,
     confidence,
     rationale,
+    behaviorEquivalence,
     raw: result.content,
   };
 }
 
-function buildPrompt(module: CognitiveModule, inputData: Record<string, unknown>): string {
+/**
+ * Build prompt with clean variable substitution
+ */
+function buildPrompt(module: CognitiveModule, input: ModuleInput): string {
   let prompt = module.prompt;
 
-  // Substitute $ARGUMENTS
-  const argsValue = String(inputData.$ARGUMENTS || inputData.query || '');
+  // v2 style: substitute ${variable} placeholders
+  for (const [key, value] of Object.entries(input)) {
+    const strValue = typeof value === 'string' ? value : JSON.stringify(value);
+    prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), strValue);
+  }
+
+  // v1 compatibility: substitute $ARGUMENTS
+  const argsValue = input.code || input.query || '';
   prompt = prompt.replace(/\$ARGUMENTS/g, argsValue);
 
-  // Substitute $N placeholders
-  const argsList = argsValue.split(/\s+/);
-  argsList.forEach((arg, i) => {
-    prompt = prompt.replace(new RegExp(`\\$${i}`, 'g'), arg);
-    prompt = prompt.replace(new RegExp(`\\$ARGUMENTS\\[${i}\\]`, 'g'), arg);
-  });
+  // Substitute $N placeholders (v1 compatibility)
+  if (typeof argsValue === 'string') {
+    const argsList = argsValue.split(/\s+/);
+    argsList.forEach((arg, i) => {
+      prompt = prompt.replace(new RegExp(`\\$${i}\\b`, 'g'), arg);
+    });
+  }
 
-  // Substitute other input fields
-  for (const [key, value] of Object.entries(inputData)) {
-    if (key !== '$ARGUMENTS' && key !== 'query') {
-      prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), String(value));
+  // Append input summary if not already in prompt
+  if (!prompt.includes(argsValue) && argsValue) {
+    prompt += '\n\n## Input\n\n';
+    if (input.code) {
+      prompt += '```\n' + input.code + '\n```\n';
+    }
+    if (input.query) {
+      prompt += input.query + '\n';
+    }
+    if (input.language) {
+      prompt += `\nLanguage: ${input.language}\n`;
     }
   }
 
   return prompt;
 }
+
+/**
+ * Heuristic to detect if input looks like code
+ */
+function looksLikeCode(str: string): boolean {
+  const codeIndicators = [
+    /^(def|function|class|const|let|var|import|export|public|private)\s/,
+    /[{};()]/,
+    /=>/,
+    /\.(py|js|ts|go|rs|java|cpp|c|rb)$/,
+  ];
+  return codeIndicators.some(re => re.test(str));
+}

package/src/types.ts

@@ -1,5 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
+ * Version 2.0 - With tools policy, failure contract, and behavior equivalence
  */
 
 // Provider interface - all LLM providers implement this
@@ -30,23 +31,69 @@ export interface InvokeResult {
   };
 }
 
-// Module types
+// Module types (v2)
 export interface CognitiveModule {
+  // Core identity
   name: string;
   version: string;
   responsibility: string;
+  
+  // Constraints
   excludes: string[];
+  constraints?: ModuleConstraints;
+  
+  // Tools policy
+  tools?: ToolsPolicy;
+  
+  // Output contract
+  output?: OutputContract;
+  
+  // Failure contract
+  failure?: FailureContract;
+  
+  // Execution context
   context?: 'fork' | 'main';
+  
+  // Prompt (from prompt.md or MODULE.md body)
   prompt: string;
+  
+  // Schemas
   inputSchema?: object;
   outputSchema?: object;
+  errorSchema?: object;
+  
+  // Metadata
   location: string;
+  format: 'v1' | 'v2';  // v1 = MODULE.md, v2 = module.yaml + prompt.md
+}
+
+export interface ModuleConstraints {
+  no_network?: boolean;
+  no_side_effects?: boolean;
+  no_file_write?: boolean;
+  no_inventing_data?: boolean;
+}
+
+export interface ToolsPolicy {
+  allowed: string[];
+}
+
+export interface OutputContract {
+  mode?: 'json_strict' | 'json_lenient' | 'text';
+  require_confidence?: boolean;
+  require_rationale?: boolean;
+  require_behavior_equivalence?: boolean;
+}
+
+export interface FailureContract {
+  schema?: object;
 }
 
 export interface ModuleResult {
   output: unknown;
   confidence: number;
   rationale: string;
+  behaviorEquivalence?: boolean;
   raw?: string;
 }
 
@@ -62,3 +109,12 @@ export interface CommandResult {
   data?: unknown;
   error?: string;
 }
+
+// Module input (clean, no CLI pollution)
+export interface ModuleInput {
+  code?: string;
+  query?: string;
+  language?: string;
+  options?: Record<string, unknown>;
+  [key: string]: unknown;
+}