Hierarchical Protocols and Mutation Framework

AGENTS.md

@@ -9,25 +9,25 @@ This is a Python-based project with a sophisticated, self-correcting agent archi
 ## Build & Commands
 
 This repository uses a hierarchical, decentralized protocol system. Each of the following directories contains a self-contained set of protocols and is compiled by its own local build script.
+- [Aal Spec](protocols/aal_spec/AGENTS.md)
+- [Chc Protocols](protocols/chc_protocols/AGENTS.md)
 - [Compliance](protocols/compliance/AGENTS.md)
 - [Core](protocols/core/AGENTS.md)
 - [Critic](protocols/critic/AGENTS.md)
 - [Experimental](protocols/experimental/AGENTS.md)
+- [Mutation](protocols/mutation/AGENTS.md)
 - [Security](protocols/security/AGENTS.md)
-- [Self-improvement](protocols/self_improvement/AGENTS.md)
+- [Self-Improvement](protocols/self-improvement/AGENTS.md)
 - [Testing](protocols/testing/AGENTS.md)
-- [CHC Bootstrap](protocols/chc_protocols/bootstrap/README.md)
 
 ### Dependency Installation
-
 General protocols are defined in the [root protocol module](./protocols/AGENTS.md).
 To install all required Python packages, run:
 ```bash
 make install
 ```
 
 ### Running Tests
-
 To run the full suite of unit tests, use the following command:
 ```bash
 make test
@@ -51,44 +51,6 @@ To automatically format the code, run:
 make format
 ```
 
-## Executable Agent Instructions
-
-This `AGENTS.md` file can be executed to perform the tasks described above. To run the agent, use the following command:
-
-```bash
-python3 AGENTS.md
-```
-
-```python
-import subprocess
-import re
-
-def execute_commands_from_agents_md():
-    with open(__file__, 'r') as f:
-        content = f.read()
-
-    commands = re.findall(r'```bash\n(.*?)\n```', content, re.DOTALL)
-
-    for command in commands:
-        print(f"Executing command: {command}")
-        process = subprocess.Popen(command, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
-        stdout, stderr = process.communicate()
-
-        if process.returncode == 0:
-            print("Command executed successfully.")
-            if stdout:
-                print("Output:")
-                print(stdout.decode())
-        else:
-            print("Command failed.")
-            if stderr:
-                print("Error:")
-                print(stderr.decode())
-
-if __name__ == '__main__':
-    execute_commands_from_agents_md()
-```
-
 ## Jules API Integration
 
 This section provides instructions for interacting with the Jules API, which allows for programmatic access to Jules's capabilities.

knowledge_core/SYSTEM_DOCUMENTATION.md

@@ -2,6 +2,22 @@
 
 ---
 
+## `/app/protocols/` Directory
+
+### Mutation Protocol
+
+The Mutation Protocol (`MUTATION-001`) defines a structured workflow for experimenting with code changes. It is designed to allow the agent to autonomously explore the effects of modifications to the codebase in a safe and controlled manner.
+
+The protocol consists of four main stages:
+1.  **Candidate Generation:** A potential code mutation is generated by the `code_mutator` tool.
+2.  **Sandboxed Application:** The mutation is applied to a temporary, isolated copy of the repository.
+3.  **Evaluation:** The `mutation_evaluator` tool runs the full test suite within the sandbox to check for regressions.
+4.  **Reporting:** The results of the evaluation are reported for analysis.
+
+This protocol is a key component of the agent's long-term learning and self-improvement capabilities, as it provides a formal mechanism for trial-and-error experimentation.
+
+---
+
 ## `/app/tooling/` Directory
 
 ### `/app/tooling/__init__.py`
@@ -371,6 +387,39 @@ cornerstone of the agent's design philosophy.
   > 4. Running the full test suite to ensure no existing capabilities were lost.
 
 
+### `/app/tooling/code_mutator.py`
+
+A tool for generating simple, syntactic code mutations.
+
+This script provides a basic implementation of a code mutation tool, which is
+a key component of the `MUTATION-001` protocol. It is designed to introduce
+small, syntactically valid changes into a source file, allowing the agent to
+explore the effects of these changes in a controlled way.
+
+The current implementation performs a simple set of mutations, focusing on
+replacing common binary operators (e.g., `==` with `!=`, `<` with `>`). This
+serves as a proof-of-concept for the mutation testing workflow. Future
+iterations can expand this tool with more sophisticated mutation strategies,
+such as statement deletion, constant replacement, or AST-based manipulations,
+without altering the core protocol.
+
+The tool is invoked with a single command-line argument: the path to the file
+to be mutated. It modifies the file in-place.
+
+
+**Public Functions:**
+
+
+- #### `def main()`
+
+  > Main entry point for the code mutator tool.
+
+
+- #### `def mutate_code(filepath)`
+
+  > Performs a simple mutation on a file by replacing a common keyword.
+
+
 ### `/app/tooling/code_suggester.py`
 
 Handles the generation and application of autonomous code change suggestions.
@@ -1069,7 +1118,7 @@ Key classes:
 - `ParaconsistentTruth`: An enum for the four truth values.
 - `ParaconsistentState`: A wrapper for a value that holds a paraconsistent truth.
 - `LFIInstruction`: A UDC instruction that operates on paraconsistent states.
-- `LFIExecutor`: A virtual machine that executes a UDC plan using LFI semantics.
+- `LFIExecutor`: a virtual machine that executes a UDC plan using LFI semantics.
 - `ParaconsistentHaltingDecider`: The main entry point that orchestrates the
   analysis of a UDC plan.
 
@@ -1330,6 +1379,43 @@ subsystem.
   > Prints the first command-line argument to simulate a user message.
 
 
+### `/app/tooling/mutation_evaluator.py`
+
+A tool for evaluating the impact of a code mutation.
+
+This script is the second key component of the `MUTATION-001` protocol. It is
+designed to be run within a sandboxed environment where a code mutation has
+been applied. Its purpose is to provide a clear, automated assessment of the
+mutation's impact on the overall health of the codebase.
+
+The current implementation performs a single, critical check: it runs the
+repository's main test suite (via `make test`). This ensures that the mutation
+has not introduced any regressions.
+
+Future iterations of this tool could be expanded to include more sophisticated
+analyses, such as:
+- Performance benchmarking to detect performance regressions.
+- Static analysis to check for new code style violations.
+- Code coverage analysis to ensure the mutation is exercised by the test suite.
+
+The tool is invoked with a single command-line argument: the path to the
+sandbox directory to be evaluated. It reports the success or failure of the
+test suite to standard output.
+
+
+**Public Functions:**
+
+
+- #### `def evaluate_mutation(sandbox_path)`
+
+  > Evaluates a mutation by running the test suite in a sandboxed environment.
+
+
+- #### `def main()`
+
+  > Main entry point for the mutation evaluator tool.
+
+
 ### `/app/tooling/pda_parser.py`
 
 A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas.

protocols/AGENTS.md

@@ -1,8 +1,7 @@
 # ---
 # DO NOT EDIT THIS FILE DIRECTLY.
-# This file is programmatically generated by the `build.py` script in this directory.
-# All changes to agent protocols must be made in the source files
-# located in the `protocols/` directory.
+# This file is programmatically generated by the build script in this directory.
+# All changes to agent protocols must be made in the source files.
 #
 # This file contains the compiled protocols in a human-readable Markdown format,
 # with machine-readable JSON definitions embedded.

protocols/aal_spec/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS.md
+
+This file is a placeholder. Protocols for this module have not yet been defined.

protocols/build.py

@@ -2,6 +2,7 @@
 import sys
 import json
 import jsonschema
+from pathlib import Path
 
 # Add the root directory to the Python path
 sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
@@ -10,17 +11,15 @@
 
 # --- Configuration ---
 ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
-SOURCE_DIR = os.path.dirname(__file__)
-TARGET_FILE = os.path.join(SOURCE_DIR, "AGENTS.md")
-SCHEMA_FILE = os.path.join(ROOT_DIR, "protocols", "protocol.schema.json")
+PROTOCOLS_DIR = os.path.dirname(__file__)
+SCHEMA_FILE = os.path.join(PROTOCOLS_DIR, "protocol.schema.json")
 TOOL_MANIFEST_FILE = os.path.join(ROOT_DIR, "tooling", "tool_manifest.json")
 
 DISCLAIMER_TEMPLATE = """\
 # ---
 # DO NOT EDIT THIS FILE DIRECTLY.
-# This file is programmatically generated by the `build.py` script in this directory.
-# All changes to agent protocols must be made in the source files
-# located in the `{source_dir_name}/` directory.
+# This file is programmatically generated by the build script in this directory.
+# All changes to agent protocols must be made in the source files.
 #
 # This file contains the compiled protocols in a human-readable Markdown format,
 # with machine-readable JSON definitions embedded.
@@ -48,28 +47,29 @@ def validate_protocol_tools(protocol_data, tool_manifest):
                 print(f"Warning: Tool '{tool_name}' in protocol '{protocol_data.get('protocol_id', 'N/A')}' not found in tool manifest.", file=sys.stderr)
 
 # --- Core Compilation Logic ---
-def compile_module():
-    """Compiles the protocol files in this directory into a single AGENTS.md."""
-    print(f"--- Starting Protocol Compilation for Root Protocols Module ---")
-    print(f"Source directory: {SOURCE_DIR}")
-    print(f"Target file: {TARGET_FILE}")
+def compile_protocol_module(source_dir, target_file):
+    """Compiles all protocol files in a given directory into a single AGENTS.md."""
+    print(f"--- Compiling Protocol Module: {source_dir} ---")
 
     schema = load_schema(SCHEMA_FILE)
     if not schema:
+        print(f"Error: Could not load schema from {SCHEMA_FILE}", file=sys.stderr)
         return
 
     tool_manifest = load_tool_manifest()
 
-    # Find all protocol source files in the current directory (non-recursive)
-    all_md_files = sorted([os.path.join(SOURCE_DIR, f) for f in find_files(".protocol.md", base_dir=SOURCE_DIR, recursive=False)])
-    all_json_files = sorted([os.path.join(SOURCE_DIR, f) for f in find_files(".protocol.json", base_dir=SOURCE_DIR, recursive=False)])
+    all_md_files = sorted(find_files(".protocol.md", base_dir=source_dir, recursive=False))
+    all_json_files = sorted(find_files(".protocol.json", base_dir=source_dir, recursive=False))
 
-    disclaimer = DISCLAIMER_TEMPLATE.format(source_dir_name=os.path.basename(SOURCE_DIR))
-    final_content = [disclaimer]
+    if not all_md_files and not all_json_files:
+        print("No protocol files found. Skipping.")
+        return
+
+    final_content = [DISCLAIMER_TEMPLATE]
 
     # Process markdown files
     for file_path in all_md_files:
-        with open(file_path, "r") as f:
+        with open(os.path.join(source_dir, file_path), "r") as f:
             content = f.read()
             sanitized_content = sanitize_markdown(content)
             final_content.append(sanitized_content)
@@ -78,20 +78,10 @@ def compile_module():
     # Process JSON files
     for file_path in all_json_files:
         try:
-            with open(file_path, "r") as f:
+            with open(os.path.join(source_dir, file_path), "r") as f:
                 protocol_data = json.load(f)
             jsonschema.validate(instance=protocol_data, schema=schema)
             validate_protocol_tools(protocol_data, tool_manifest)
-
-            # --- Handle Executable Code ---
-            if "rules" in protocol_data:
-                for rule in protocol_data["rules"]:
-                    if "executable_code" in rule and rule["executable_code"]:
-                        execute_code(rule["executable_code"], protocol_data.get("protocol_id", "N/A"), rule.get("rule_id", "N/A"))
-                        # Embed the code in the markdown output
-                        code_md = f"#### Executable Code for Rule: `{rule.get('rule_id', 'N/A')}`\n\n```python\n{rule['executable_code']}\n```\n"
-                        final_content.append(code_md)
-
             json_string = json.dumps(protocol_data, indent=2)
             md_json_block = f"```json\n{json_string}\n```\n"
             final_content.append(md_json_block)
@@ -101,14 +91,56 @@ def compile_module():
         except jsonschema.ValidationError as e:
             print(f"Warning: Schema validation failed for {file_path}: {e.message}", file=sys.stderr)
 
-
     # Write the final output
-    final_output_string = "\n".join(final_content)
-    temp_target_file = TARGET_FILE + ".tmp"
-    with open(temp_target_file, "w") as f:
-        f.write(final_output_string)
-    os.rename(temp_target_file, TARGET_FILE)
-    print(f"Successfully compiled AGENTS.md for root protocols module at {TARGET_FILE}")
+    with open(target_file, "w") as f:
+        f.write("\n".join(final_content))
+    print(f"Successfully compiled AGENTS.md at {target_file}")
+
+
+def generate_root_agents_md(child_protocol_dirs):
+    """Generates the root AGENTS.md file, linking to the compiled sub-modules."""
+    print("--- Generating Root AGENTS.md ---")
+    content = [
+        "# AGENTS.md",
+        "\nThis file provides instructions for AI coding agents to interact with this project.",
+        "\n## Project Overview",
+        "\nThis is a Python-based project with a sophisticated, self-correcting agent architecture.",
+        "\n## Build & Commands",
+        "\nThis repository uses a hierarchical, decentralized protocol system. Each of the following directories contains a self-contained set of protocols and is compiled by its own local build script."
+    ]
+
+    for dir_path in sorted(child_protocol_dirs):
+        module_name = Path(dir_path).name.replace('_', ' ').title()
+        link = f"- [{module_name}]({Path(dir_path).relative_to(ROOT_DIR)}/AGENTS.md)"
+        content.append(link)
+
+    content.append("\n### Dependency Installation")
+    content.append("General protocols are defined in the [root protocol module](./protocols/AGENTS.md).")
+    content.append("To install all required Python packages, run:\n```bash\nmake install\n```")
+    content.append("\n### Running Tests")
+    content.append("To run the full suite of unit tests, use the following command:\n```bash\nmake test\n```")
+
+    target_file = os.path.join(ROOT_DIR, "AGENTS.md")
+    with open(target_file, "w") as f:
+        f.write("\n".join(content))
+    print(f"Successfully generated root AGENTS.md at {target_file}")
+
+
+def main():
+    """Main function to orchestrate the hierarchical compilation process."""
+    print("--- Starting Hierarchical Protocol Compilation ---")
+    protocol_dirs = [d for d in Path(PROTOCOLS_DIR).iterdir() if d.is_dir()]
+
+    for directory in protocol_dirs:
+        target_file = os.path.join(directory, "AGENTS.md")
+        compile_protocol_module(str(directory), target_file)
+
+    # Compile the root protocol files as well
+    compile_protocol_module(PROTOCOLS_DIR, os.path.join(PROTOCOLS_DIR, "AGENTS.md"))
+
+    # Generate the main AGENTS.md that links to all sub-protocols
+    generate_root_agents_md(protocol_dirs)
+
 
 if __name__ == "__main__":
-    compile_module()
+    main()

protocols/chc_protocols/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS.md
+
+This file is a placeholder. Protocols for this module have not yet been defined.