From 11c0a0500fa337324e88a63b9e29bed372f58c1f Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 18 Oct 2025 21:21:06 +0000 Subject: [PATCH] Refactor the AGENTS.md system into a robust, verifiable build process. This commit introduces a complete overhaul of how agent protocols are managed, moving from a single, monolithic AGENTS.md file to a modern, source-controlled build system. This change addresses critical issues of merge conflicts, verifiability, security, and machine-readability that were present in the previous flat-file system. The new system is built around the following core components: 1. **Protocol Source Files:** - Protocols are now defined in structured `.protocol.json` files, which serve as the single source of truth. - These source files are validated against a formal JSON schema (`protocols/protocol.schema.json`) to ensure structural integrity and prevent errors before runtime. 2. **Hierarchical Build System:** - A new script, `tooling/hierarchical_compiler.py`, orchestrates the entire build process. - It recursively finds all `protocols` subdirectories and runs a `tooling/compiler.py` on each one. - This generates scoped `AGENTS.md` files (e.g., `core/AGENTS.md`), allowing for context-specific protocols that apply only to certain parts of the codebase. 3. **Knowledge Graph Generation:** - The build process now generates a `protocols.ttl` file in the root directory. - This file is a formal RDF knowledge graph of all protocols, their rules, and their associated tools, created by `tooling/knowledge_graph_generator.py`. - This restores the critical capability for the agent to perform machine reasoning and introspection on its own rules. 4. **Self-Modification Protocol:** - A new meta-protocol (`self-modification-001`) has been introduced to govern how the agent modifies the protocol system itself. - This establishes a recursive self-improvement loop, ensuring that all future changes to the system follow the new, robust process. By treating protocols as source code and `AGENTS.md` as a build artifact, this new system makes the agent's governing rules more dynamic, merge-friendly, and powerful. --- AGENTS.md | 84 +- compliance/AGENTS.md | 261 +- core/AGENTS.md | 688 +- .../99_self_modification.protocol.json | 32 + critic/AGENTS.md | 106 +- protocols.ttl | 683 + protocols/AGENTS.md | 74 - protocols/core/AGENTS.md | 14571 ---------------- tooling/compiler.py | 88 + tooling/hierarchical_compiler.py | 64 + tooling/knowledge_graph_generator.py | 89 + 11 files changed, 1195 insertions(+), 15545 deletions(-) create mode 100644 core/protocols/99_self_modification.protocol.json create mode 100644 protocols.ttl delete mode 100644 protocols/AGENTS.md delete mode 100644 protocols/core/AGENTS.md create mode 100644 tooling/compiler.py create mode 100644 tooling/hierarchical_compiler.py create mode 100644 tooling/knowledge_graph_generator.py diff --git a/AGENTS.md b/AGENTS.md index 858cfd20..6050f4fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,83 +1,3 @@ +# Agent Protocols -# --- -# DO NOT EDIT THIS FILE DIRECTLY. -# This file is programmatically generated by the `protocol_compiler.py` script. -# It provides a top-level view of the repository's protocol modules. -# All changes to agent protocols must be made in the source files -# located in the `protocols/` subdirectories. -# --- - -# Agent Charter & Operational Principles - -## 1. Agent Identity and Purpose - -This repository is designed for development by an advanced AI software engineering assistant. - -**Identity:** The primary agent interacting with this repository is a large language model-based coding assistant developed by Google. It operates externally and interacts with the codebase via a secure GitHub application. It is not a resident entity within the repository, and any documentation referring to a specific persona (e.g., "Jules") is legacy and should be disregarded. - -**Purpose:** The agent's purpose is to assist in software development tasks, including but not limited to: -* Implementing new features. -* Fixing bugs. -* Refactoring code. -* Improving documentation. -* Analyzing and improving the repository's architecture and protocols. - -The agent is expected to operate autonomously, using the tools and information provided within this repository to complete its tasks. - -## 2. Core Operational Principles - -This repository is architected to facilitate effective human-AI collaboration. The following principles are fundamental to the agent's operation. - -### 2.1. Protocol-Driven Operation - -The agent's behavior is governed by a set of formal, machine-readable protocols. These are defined in the `protocols/` directory and compiled into the `AGENTS.md` file. The agent **must** adhere to these protocols at all times. They are not guidelines; they are the rules of the system. - -### 2.2. The Knowledge Core as the Source of Truth - -The agent's ability to reason effectively about the codebase is augmented by a dedicated `knowledge_core/` directory. This directory contains a set of machine-readable artifacts that provide a structured, up-to-date representation of the repository's state. - -* **`dependency_graph.json`**: An explicit map of all dependencies within the repository. The agent must use this artifact for impact analysis. -* **`symbols.json`**: A universal map of all code symbols (functions, classes, etc.). The agent must use this for precise code navigation and retrieval. -* **`asts/`**: A collection of Abstract Syntax Trees for source files. The agent must use these for deep structural analysis and code manipulation. -* **`llms.txt`**: A curated corpus of high-level documentation and project rationale. -* **`temporal_orientation.md`**: A summary of the current state of external technologies to combat knowledge cutoff. - -The agent **must** prioritize using these artifacts over attempting to infer information from unstructured source code. - -### 2.3. Structured Logging for Learning - -All agent actions must be logged to `logs/activity.log.jsonl` in a structured format defined by `LOGGING_SCHEMA.md`. This is not just for debugging. These logs form a high-quality dataset of the agent's reasoning and actions, which is essential for analyzing performance and enabling long-term learning and self-improvement. - -### 2.4. Continuous Self-Improvement - -The agent is not only a user of this system but also a contributor to its evolution. The agent is empowered to: -* Identify flaws or inefficiencies in the existing protocols. -* Propose improvements to the protocols or the tools in the `tooling/` directory. -* Implement and validate these improvements. - -This self-improvement loop is a core objective of this project. - -## 3. Interaction Model - -The agent's interaction with the repository follows a clear cycle: -1. **Task Ingestion:** Receive a task from a user. -2. **Contextualization:** Use the Knowledge Core and external search tools to build a comprehensive understanding of the task. -3. **Planning:** Generate a detailed, step-by-step plan. -4. **Execution:** Execute the plan, using the available tools and logging every action. -5. **Verification:** Verify the successful completion of the task. -6. **Post-Mortem:** Analyze the execution to identify lessons learned. -7. **Submission:** Submit the completed work for review. - -This structured process ensures that the agent's work is predictable, verifiable, and aligned with the project's goals. - ---- - - - -# --- Child Protocol Modules --- - -This repository uses a hierarchical protocol system. Each of the following directories contains a self-contained set of protocols in its own `AGENTS.md` file. -- [Compliance](protocols/compliance/AGENTS.md) -- [Core](protocols/core/AGENTS.md) -- [Critic](protocols/critic/AGENTS.md) -- [Security](protocols/security/AGENTS.md) \ No newline at end of file +*No protocols defined in this scope.* diff --git a/compliance/AGENTS.md b/compliance/AGENTS.md index fc1c36d7..6c80f73a 100644 --- a/compliance/AGENTS.md +++ b/compliance/AGENTS.md @@ -1,234 +1,75 @@ -# --- -# DO NOT EDIT THIS FILE DIRECTLY. -# This file is programmatically generated by the `protocol_compiler.py` script. -# All changes to agent protocols must be made in the source files -# located in the `protocols/` directory. -# -# This file contains the compiled protocols in a human-readable Markdown format, -# with machine-readable JSON definitions embedded. -# --- +# Agent Protocols +_This document is auto-generated from protocol source files. Do not edit it directly._ -# Meta-Protocol: `AGENTS.md` Self-Management +## Protocol: best-practices-001 +_A set of best practices derived from observing successful, data-driven workflow patterns._ -This protocol defines how the agent should manage its own core `AGENTS.md` file. - -**Rule `agents-md-self-awareness`**: The `AGENTS.md` file is not a static document; it is a build artifact compiled from the source files located in the `protocols/` directory. This compilation is handled by the `make AGENTS.md` command, which orchestrates the `tooling/protocol_compiler.py` script. - -To ensure that you are always operating under the most current set of rules and directives, you must periodically run `make AGENTS.md`. This is especially critical at the beginning of a new task or if you observe behavior that seems inconsistent with your documented protocols, as the protocols may have been updated. - -This act of self-maintenance is a foundational element of robust, autonomous operation. It ensures that your understanding of your own governing principles remains synchronized with the repository's ground truth. - ---- - -# Protocol: AGENTS.md Non-Compliance - -This protocol defines what constitutes non-compliance with the established `AGENTS.md` protocols and outlines the expected corrective actions. Adherence to these meta-rules is critical for ensuring predictable, verifiable, and robust agent behavior. - -## Rule `non-compliance-definition`: Definition of Non-Compliance - -Non-compliance is the act of violating the explicit rules, conventions, or procedures documented in the `AGENTS.md` file and its source protocols within the `protocols/` directory. The `AGENTS.md` file serves as the agent's primary operational mandate, and any deviation from it is considered a fault condition. - -## Rule `non-compliance-direct-editing`: Prohibition of Direct Artifact Editing - -**Violation:** Directly editing any file that is a documented build artifact. -- **Primary Example:** Modifying `AGENTS.md` or `README.md` directly is a severe violation. These files are generated from source protocols and documentation. -- **Corrective Action:** The agent must revert any direct edits to build artifacts. Changes must be made to the source files (e.g., in `protocols/` or tool docstrings), and the appropriate build command (e.g., `make AGENTS.md`, `make docs`) must be executed. - -## Rule `non-compliance-test-procedure`: Adherence to Testing Protocols - -**Violation:** Failing to execute the testing procedures as defined in `AGENTS.md` before submitting changes. This includes not running the full test suite or ignoring failing tests. -- **Corrective Action:** The agent must halt its execution plan and run the required tests. If tests fail, the agent must enter a debugging loop to resolve the failures before proceeding. - -## Rule `non-compliance-architectural-deviation`: Adherence to Architectural and Convention Guidelines - -**Violation:** Introducing changes that contradict the architectural patterns, coding conventions, or file structures laid out in `AGENTS.md`. -- **Example:** Placing a new backend component in the `frontend/` directory when the architecture explicitly forbids it. -- **Corrective Action:** The agent must identify the deviation, revert the incorrect changes, and re-implement them in accordance with the documented standards. - -## Rule `non-compliance-self-awareness-failure`: Failure to Maintain Protocol Awareness - -**Violation:** Operating with an outdated understanding of the protocols by failing to re-compile `AGENTS.md` when necessary, as defined in the `meta-protocol`. -- **Corrective Action:** If the agent detects that its actions are out of sync with repository standards, it should trigger the `make AGENTS.md` command to refresh its internal state and re-evaluate its plan. - -## Consequence of Non-Compliance - -Upon detecting any form of non-compliance, the agent is required to: -1. **Halt:** Immediately stop the current execution path to prevent further deviation. -2. **Report:** Log the specific violation that was detected. -3. **Correct:** Initiate the defined corrective action for the specific violation. If a corrective action is not explicitly defined, the agent should revert the violating changes and re-plan its approach. - ---- - -# Protocol: Pre-Commit Verification - -This protocol establishes the mandatory sequence of verification steps that must be performed before any code is submitted. Its purpose is to ensure that all changes meet a baseline level of quality, correctness, and review, preventing regressions and maintaining repository health. - -## Rule: Mandatory Pre-Commit Checks - -Before finalizing and submitting any work, the agent **must** execute the `pre_commit_instructions` tool. This tool acts as a procedural gateway, providing the specific, up-to-date checklist of actions required for validation. This typically includes: - -1. **Running all automated tests** to verify correctness. -2. **Requesting a formal code review** to get critical feedback. -3. **Recording key learnings** to contribute to the agent's long-term memory. - -Adherence to this protocol is not optional. It is a fundamental step in the development lifecycle that safeguards the integrity of the codebase. +### Rules +- **verify-after-write**: After every file creation or modification action (`create_file_with_block`, `overwrite_file_with_block`, `replace_with_git_merge_diff`), the agent MUST use a subsequent read-only tool (`read_file`, `list_files`, `grep`) to verify that the action was executed successfully and had the intended effect. A plan step should only be marked as complete after this verification. + - *Enforcement: This is a core operational discipline. Future tooling, such as a trace validator, could enforce this by analyzing the execution log against this protocol.* +### Associated Tools +- `create_file_with_block` +- `overwrite_file_with_block` +- `replace_with_git_merge_diff` +- `delete_file` +- `read_file` +- `list_files` +- `grep` --- -# Protocol: `reset_all` Prohibition - -**ID:** `reset-all-prohibition-001` - -## 1. Description - -This protocol establishes a strict and unconditional prohibition on the use of the `reset_all` tool. This tool is considered a legacy, high-risk command that is no longer permitted in any workflow. +## Protocol: meta-protocol-001 +_A meta-protocol governing the agent's awareness and maintenance of its own core protocol files._ -## 2. Rationale +### Rules +- **agents-md-self-awareness**: The AGENTS.md file is a build artifact generated from source files in the 'protocols/' directory. Before relying on AGENTS.md, the agent should ensure it is up-to-date by running 'make AGENTS.md'. This ensures the agent is operating with the latest set of protocols. + - *Enforcement: The agent should incorporate this check into its standard operating procedure, particularly at the beginning of a task or when unexpected behavior occurs.* -The `reset_all` tool has been the cause of multiple catastrophic failures, leading to the complete loss of work and the inability to complete tasks. Its behavior is too destructive and unpredictable for a production environment. More granular and safer tools are available for workspace management. This protocol serves as a hard-coded safeguard to prevent any future use of this tool. - -## 3. Rules - -### Rule `no-reset-all` - -- **Description:** The `reset_all` tool is strictly forbidden under all circumstances. -- **Enforcement:** The `master_control.py` orchestrator will programmatically block any attempt to call `reset_all` and will immediately terminate the task with a critical error. This is not a rule for the agent to interpret, but a hard-coded system constraint. +### Associated Tools +- `run_in_bash_session` --- -```json -{ - "protocol_id": "best-practices-001", - "description": "A set of best practices derived from observing successful, data-driven workflow patterns.", - "rules": [ - { - "rule_id": "verify-after-write", - "description": "After every file creation or modification action (`create_file_with_block`, `overwrite_file_with_block`, `replace_with_git_merge_diff`), the agent MUST use a subsequent read-only tool (`read_file`, `list_files`, `grep`) to verify that the action was executed successfully and had the intended effect. A plan step should only be marked as complete after this verification.", - "enforcement": "This is a core operational discipline. Future tooling, such as a trace validator, could enforce this by analyzing the execution log against this protocol." - } - ], - "associated_tools": [ - "create_file_with_block", - "overwrite_file_with_block", - "replace_with_git_merge_diff", - "delete_file", - "read_file", - "list_files", - "grep" - ] -} -``` - +## Protocol: non-compliance-protocol-001 +_A protocol that defines non-compliance with AGENTS.md and specifies corrective actions._ + +### Rules +- **non-compliance-definition**: Defines non-compliance as a violation of any rule, convention, or procedure in AGENTS.md or its source protocols. + - *Enforcement: This is a definitional rule. Enforcement is achieved through the agent's adherence to the specific non-compliance rules that follow.* +- **non-compliance-direct-editing**: Prohibits the direct editing of build artifacts like AGENTS.md or README.md. Changes must be made to source files, followed by a rebuild. + - *Enforcement: Agent must revert direct edits and modify source files, then run the appropriate build command.* +- **non-compliance-test-procedure**: Requires adherence to all documented testing procedures before submitting changes. + - *Enforcement: Agent must halt execution and run the required tests, debugging any failures before proceeding.* +- **non-compliance-architectural-deviation**: Forbids changes that contradict documented architectural patterns or coding conventions. + - *Enforcement: Agent must revert non-compliant changes and re-implement them according to standards.* +- **non-compliance-self-awareness-failure**: Requires the agent to maintain an up-to-date understanding of protocols by recompiling AGENTS.md when necessary. + - *Enforcement: Agent should run 'make AGENTS.md' to refresh its protocol knowledge and re-evaluate its plan.* --- -```json -{ - "protocol_id": "meta-protocol-001", - "description": "A meta-protocol governing the agent's awareness and maintenance of its own core protocol files.", - "rules": [ - { - "rule_id": "agents-md-self-awareness", - "description": "The AGENTS.md file is a build artifact generated from source files in the 'protocols/' directory. Before relying on AGENTS.md, the agent should ensure it is up-to-date by running 'make AGENTS.md'. This ensures the agent is operating with the latest set of protocols.", - "enforcement": "The agent should incorporate this check into its standard operating procedure, particularly at the beginning of a task or when unexpected behavior occurs." - } - ], - "associated_tools": [ - "run_in_bash_session" - ] -} -``` - +## Protocol: pre-commit-protocol-001 +_Defines the mandatory pre-commit checks to ensure code quality, correctness, and readiness for submission._ ---- - -```json -{ - "protocol_id": "non-compliance-protocol-001", - "description": "A protocol that defines non-compliance with AGENTS.md and specifies corrective actions.", - "rules": [ - { - "rule_id": "non-compliance-definition", - "description": "Defines non-compliance as a violation of any rule, convention, or procedure in AGENTS.md or its source protocols.", - "enforcement": "This is a definitional rule. Enforcement is achieved through the agent's adherence to the specific non-compliance rules that follow." - }, - { - "rule_id": "non-compliance-direct-editing", - "description": "Prohibits the direct editing of build artifacts like AGENTS.md or README.md. Changes must be made to source files, followed by a rebuild.", - "enforcement": "Agent must revert direct edits and modify source files, then run the appropriate build command.", - "associated_tools": [ - "restore_file", - "run_in_bash_session" - ] - }, - { - "rule_id": "non-compliance-test-procedure", - "description": "Requires adherence to all documented testing procedures before submitting changes.", - "enforcement": "Agent must halt execution and run the required tests, debugging any failures before proceeding.", - "associated_tools": [ - "run_in_bash_session" - ] - }, - { - "rule_id": "non-compliance-architectural-deviation", - "description": "Forbids changes that contradict documented architectural patterns or coding conventions.", - "enforcement": "Agent must revert non-compliant changes and re-implement them according to standards." - }, - { - "rule_id": "non-compliance-self-awareness-failure", - "description": "Requires the agent to maintain an up-to-date understanding of protocols by recompiling AGENTS.md when necessary.", - "enforcement": "Agent should run 'make AGENTS.md' to refresh its protocol knowledge and re-evaluate its plan.", - "associated_tools": [ - "run_in_bash_session" - ] - } - ] -} -``` +### Rules +- **pre-commit-instructions-mandate**: Before submitting changes, the agent MUST execute the `pre_commit_instructions` tool to receive the required sequence of validation steps (e.g., running tests, requesting code review). + - *Enforcement: The agent's core logic should invoke this tool as the entry point to the pre-submission phase.* +### Associated Tools +- `pre_commit_instructions` +- `code_linter` --- -```json -{ - "protocol_id": "pre-commit-protocol-001", - "description": "Defines the mandatory pre-commit checks to ensure code quality, correctness, and readiness for submission.", - "rules": [ - { - "rule_id": "pre-commit-instructions-mandate", - "description": "Before submitting changes, the agent MUST execute the `pre_commit_instructions` tool to receive the required sequence of validation steps (e.g., running tests, requesting code review).", - "enforcement": "The agent's core logic should invoke this tool as the entry point to the pre-submission phase." - } - ], - "associated_tools": [ - "pre_commit_instructions", - "code_linter" - ] -} -``` - - ---- +## Protocol: reset-all-prohibition-001 +_A high-priority protocol that unconditionally forbids the use of the `reset_all` tool._ -```json -{ - "protocol_id": "reset-all-prohibition-001", - "protocol_name": "Prohibition of reset_all Tool", - "description": "A high-priority protocol that unconditionally forbids the use of the `reset_all` tool.", - "rules": [ - { - "rule_id": "no-reset-all", - "description": "The `reset_all` tool is strictly forbidden under all circumstances. It is a legacy tool that has been superseded by more granular and safer methods of workspace management. Its use is considered a critical failure.", - "enforcement": "This rule is enforced by the `master_control.py` orchestrator, which will immediately terminate the workflow with an error if an attempt is made to call this tool." - } - ], - "associated_tools": [ - "reset_all" - ] -} -``` +### Rules +- **no-reset-all**: The `reset_all` tool is strictly forbidden under all circumstances. It is a legacy tool that has been superseded by more granular and safer methods of workspace management. Its use is considered a critical failure. + - *Enforcement: This rule is enforced by the `master_control.py` orchestrator, which will immediately terminate the workflow with an error if an attempt is made to call this tool.* +### Associated Tools +- `reset_all` --- diff --git a/core/AGENTS.md b/core/AGENTS.md index 9940cb1a..32633c2a 100644 --- a/core/AGENTS.md +++ b/core/AGENTS.md @@ -1,585 +1,233 @@ -# --- -# DO NOT EDIT THIS FILE DIRECTLY. -# This file is programmatically generated by the `protocol_compiler.py` script. -# All changes to agent protocols must be made in the source files -# located in the `protocols/` directory. -# -# This file contains the compiled protocols in a human-readable Markdown format, -# with machine-readable JSON definitions embedded. -# --- +# Agent Protocols +_This document is auto-generated from protocol source files. Do not edit it directly._ -# Jules Agent Protocol: The Hierarchical Development Cycle +## Protocol: aorp-header +_Defines the identity and versioning of the Advanced Orientation and Research Protocol (AORP)._ -**Version:** 4.0.0 +### Rules +- **aorp-identity**: The governing protocol set is identified as the Advanced Orientation and Research Protocol (AORP). + - *Enforcement: Protocol is identified by its name in documentation and compiled artifacts.* +- **aorp-versioning**: The official protocol version is tracked in the VERSION file in the repository root, following Semantic Versioning (SemVer). + - *Enforcement: Build or validation scripts should verify the presence and format of the VERSION file.* --- ---- - -## 1. The Core Problem: Ensuring Formally Verifiable Execution - -To tackle complex tasks reliably, an agent's workflow must be formally structured and guaranteed to terminate—it must be **decidable**. This is achieved through a hierarchical system composed of a high-level **Orchestrator** that manages the agent's overall state and a low-level **FDC Toolchain** that governs the validity of the agent's plans. This structure prevents the system from entering paradoxical, non-terminating loops. - ---- +## Protocol: core-directive-001 +_The mandatory first action for any new task, ensuring a formal start to the Finite Development Cycle (FDC)._ ---- +### Rules +- **mandatory-fdc-start**: Upon receiving a new task, the agent's first action MUST be to programmatically execute the FDC 'start' command to formally initiate the task and run the AORP orientation cascade. + - *Enforcement: This is a hard-coded behavior in the agent's core operational loop and is verified by the FDC toolchain.* -## 2. The Solution: A Two-Layered FSM System +### Associated Tools +- `tooling/fdc_cli.py` --- -### Layer 1: The Orchestrator (`master_control.py` & `fsm.json`) - -The Orchestrator is the master Finite State Machine (FSM) that guides the agent through its entire lifecycle, from orientation to submission. It is not directly controlled by the agent's plan but rather directs the agent's state based on the successful completion of each phase. +## Protocol: decidability-constraints-001 +_Ensures all development processes are formally decidable and computationally tractable._ -**Key States (defined in `tooling/fsm.json`):** -* `ORIENTING`: The initial state where the agent gathers context. -* `PLANNING`: The state where the Orchestrator waits for the agent to produce a `plan.txt`. -* `EXECUTING`: The state where the Orchestrator oversees the step-by-step execution of the validated plan. -* `POST_MORTEM`: The state for finalizing the task and recording learnings. -* `AWAITING_SUBMISSION`: The final state before the code is submitted. +### Rules +- **non-turing-completeness**: The agent's planning and execution language is, by design, not Turing-complete. This is a fundamental constraint to guarantee that all processes will terminate. + - *Enforcement: Enforced by the design of the plan runner and validated by the `lint` command in the FDC toolchain.* +- **bounded-recursion**: The agent MUST NOT generate plans that involve recursion or self-invocation. A plan cannot trigger another FDC or a sub-plan, with the sole exception of the 'Deep Research Cycle'. + - *Enforcement: The `lint` command in `tooling/fdc_cli.py` scans plans for disallowed recursive calls.* +- **fsm-adherence**: All plans must be valid strings in the language defined by the tooling/fdc_fsm.json Finite State Machine. + - *Enforcement: The `lint` command in `tooling/fdc_cli.py` validates the plan against the FSM definition.* -**The Orchestrator's Critical Role in Planning:** -During the `PLANNING` state, the Orchestrator's most important job is to validate the agent-generated `plan.txt`. It does this by calling the FDC Toolchain's `lint` command. **A plan that fails this check will halt the entire process, preventing the agent from entering an invalid state.** +### Associated Tools +- `tooling/fdc_cli.py` +- `tooling/fdc_fsm.json` --- -### Layer 2: The FDC Toolchain (`fdc_cli.py` & `fdc_fsm.json`) - -The FDC Toolchain is a set of utilities that the agent uses to structure its work and that the Orchestrator uses for validation. The toolchain is governed by its own FSM (`tooling/fdc_fsm.json`), which defines the legal sequence of commands *within a plan*. - -#### **FDC Commands for Agent Use:** - -**`start` - Task Initiation** -* **Usage:** The first command the agent MUST issue upon receiving a task. -* **Command:** `run_in_bash_session python3 tooling/fdc_cli.py start --task-id "your-task-id"` -* **Function:** Logs the `TASK_START` event, formally beginning the development cycle. - -**`lint` - Pre-Flight Plan Validation** -* **Usage:** A command the agent can use to self-correct its own plan before finalizing it. The Orchestrator will *always* run this command on `plan.txt` as a mandatory check. -* **Command:** `run_in_bash_session python3 tooling/fdc_cli.py lint ` -* **Function:** Performs a comprehensive check against the low-level FSM: - 1. **Closure Mandate:** Ensures the plan's final action is a call to the `close` command. - 2. **FSM Validation:** Validates the sequence of agent tools against `tooling/fdc_fsm.json`. - 3. **Semantic Validation:** Checks for errors like using a file before creating it. - -**`close` - Task Closure** -* **Usage:** The **last command** in any valid plan. -* **Command:** `run_in_bash_session python3 tooling/fdc_cli.py close --task-id "your-task-id"` -* **Function:** Logs `TASK_END`, generates a post-mortem template, and signals to the Orchestrator that plan execution is complete. ---- - ---- - -### STANDING ORDERS - -1. **Orchestrator is Sovereign:** The agent's lifecycle is governed by `master_control.py`. The agent's primary job is to provide a valid `plan.txt` when the Orchestrator enters the `PLANNING` state. -2. **Toolchain is Law:** All plans must be valid according to the `fdc_cli.py lint` command. A valid plan is one that passes the Closure Mandate and is a valid string in the language defined by `fdc_fsm.json`. -3. **Hierarchy is Structure:** The Orchestrator (`master_control.py`) validates the agent's plan using the FDC Toolchain (`fdc_cli.py`). This separation ensures a robust, verifiable, and decidable development process, preventing the system from executing paradoxical or non-terminating plans. - ---- - -# Protocol: The Context-Free Development Cycle (CFDC) - -This protocol marks a significant evolution from the Finite Development Cycle (FDC), introducing a hierarchical planning model that enables far greater complexity and modularity while preserving the system's core guarantee of decidability. - -## From FSM to Pushdown Automaton - -The FDC was based on a Finite State Machine (FSM), which provided a strict, linear sequence of operations. While robust, this model was fundamentally limited: it could not handle nested tasks or sub-routines, forcing all plans to be monolithic. - -The CFDC upgrades our execution model to a **Pushdown Automaton**. This is achieved by introducing a **plan execution stack**, which allows the system to call other plans as sub-routines. This enables a powerful new paradigm: **Context-Free Development Cycles**. - -## The `call_plan` Directive - -The core of the CFDC is the new `call_plan` directive. This allows one plan to execute another, effectively creating a parent-child relationship between them. - -- **Usage:** `call_plan ` -- **Function:** When the execution engine encounters this directive, it: - 1. Pushes the current plan's state (e.g., the current step number) onto the execution stack. - 2. Begins executing the sub-plan specified in the path. - 3. Once the sub-plan completes, it pops the parent plan's state from the stack and resumes its execution from where it left off. - -## Ensuring Decidability: The Recursion Depth Limit - -A system with unbounded recursion is not guaranteed to terminate. To prevent this, the CFDC introduces a non-negotiable, system-wide limit on the depth of the plan execution stack. - -**Rule `max-recursion-depth`**: The execution engine MUST enforce a maximum recursion depth, defined by a `MAX_RECURSION_DEPTH` constant. If a `call_plan` directive would cause the stack depth to exceed this limit, the entire process MUST terminate with an error. This hard limit ensures that even with recursive or deeply nested plans, the system remains a **decidable**, non-Turing-complete process that is guaranteed to halt. - ---- - -# Protocol: The Plan Registry - -This protocol introduces a Plan Registry to create a more robust, modular, and discoverable system for hierarchical plans. It decouples the act of calling a plan from its physical file path, allowing plans to be referenced by a logical name. - -## The Problem with Path-Based Calls - -The initial implementation of the Context-Free Development Cycle (CFDC) relied on direct file paths (e.g., `call_plan path/to/plan.txt`). This is brittle: -- If a registered plan is moved or renamed, all plans that call it will break. -- It is difficult for an agent to discover and reuse existing, validated plans. - -## The Solution: A Central Registry +## Protocol: orientation-cascade-001 +_Defines the mandatory, four-tiered orientation cascade that must be executed at the start of any task to establish a coherent model of the agent's identity, environment, and the world state._ -The Plan Registry solves this by creating a single source of truth that maps logical, human-readable plan names to their corresponding file paths. +### Rules +- **l1-self-awareness**: Level 1 (Self-Awareness): The agent must first establish its own identity and inherent limitations by reading the `knowledge_core/agent_meta.json` artifact. + - *Enforcement: The `start` command of the FDC toolchain executes this step and fails if the artifact is missing or invalid.* +- **l2-repository-sync**: Level 2 (Repository Sync): The agent must understand the current state of the local repository by loading primary artifacts from the `knowledge_core/` directory. + - *Enforcement: The `start` command of the FDC toolchain executes this step.* +- **l3-environmental-probing**: Level 3 (Environmental Probing & Targeted RAG): The agent must discover the rules and constraints of its operational environment by executing a probe script and using targeted RAG to resolve 'known unknowns'. + - *Enforcement: The `start` command of the FDC toolchain executes this step, utilizing tools like `google_search` and `view_text_website`.* +- **l4-deep-research-cycle**: Level 4 (Deep Research Cycle): To investigate 'unknown unknowns', the agent must initiate a formal, self-contained Finite Development Cycle (FDC) of the 'Analysis Modality'. + - *Enforcement: This is a special case of recursion, explicitly allowed and managed by the FDC toolchain.* -- **Location:** `knowledge_core/plan_registry.json` -- **Format:** A simple JSON object of key-value pairs: - ```json - { - "logical-name-1": "path/to/plan_1.txt", - "run-all-tests": "plans/common/run_tests.txt" - } - ``` - -## Updated `call_plan` Logic - -The `call_plan` directive is now significantly more powerful. When executing `call_plan `, the system will follow a **registry-first** approach: - -1. **Registry Lookup:** The system will first treat `` as a logical name and look it up in `knowledge_core/plan_registry.json`. -2. **Path Fallback:** If the name is not found in the registry, the system will fall back to treating `` as a direct file path. This ensures full backward compatibility with existing plans. - -## Management - -A new tool, `tooling/plan_manager.py`, will be introduced to manage the registry with simple commands like `register`, `deregister`, and `list`, making it easy to maintain the library of reusable plans. +### Associated Tools +- `tooling/environmental_probe.py` +- `google_search` +- `view_text_website` --- -# Protocol: The Closed-Loop Self-Correction Cycle - -This protocol describes the automated workflow that enables the agent to programmatically improve its own governing protocols based on new knowledge. It transforms the ad-hoc, manual process of learning into a reliable, machine-driven feedback loop. - -## The Problem: The Open Loop - -Previously, "lessons learned" were compiled into a simple markdown file, `knowledge_core/lessons_learned.md`. While this captured knowledge, it was a dead end. There was no automated process to translate these text-based insights into actual changes to the protocol source files. This required manual intervention, creating a significant bottleneck and a high risk of protocols becoming stale. - -## The Solution: A Protocol-Driven Self-Correction (PDSC) Workflow - -The PDSC workflow closes the feedback loop by introducing a set of new tools and structured data formats that allow the agent to enact its own improvements. +## Protocol: fdc-protocol-001 +_Defines the Finite Development Cycle (FDC), a formally defined process for executing a single, coherent task._ -**1. Structured, Actionable Lessons (`knowledge_core/lessons.jsonl`):** -- Post-mortem analysis now generates lessons as structured JSON objects, not free-form text. -- Each lesson includes a machine-readable `action` field, which contains a specific, executable command. +### Rules +- **fdc-entry-point**: The AORP cascade is the mandatory entry point to every FDC. + - *Enforcement: Enforced by the `start` command in `tooling/fdc_cli.py`.* +- **fdc-state-transitions**: The FDC is a Finite State Machine (FSM) formally defined in `tooling/fdc_fsm.json`. Plans must be valid strings in the language defined by this FSM. + - *Enforcement: Validated by the `lint` command in `tooling/fdc_cli.py`.* +- **phase1-deconstruction**: Phase 1 (Deconstruction & Contextualization): The agent must ingest the task, query historical logs, identify entities using the symbol map, and analyze impact using the dependency graph. + - *Enforcement: Procedural step guided by the agent's core logic, using artifacts in `logs/` and `knowledge_core/`.* +- **phase2-planning**: Phase 2 (Planning & Self-Correction): The agent must generate a granular plan, lint it using the FDC toolchain, cite evidence for its steps, and perform a critical review. + - *Enforcement: The `lint` command in `tooling/fdc_cli.py` is a mandatory pre-flight check.* +- **phase3-execution**: Phase 3 (Execution & Structured Logging): The agent must execute the validated plan and log every action according to the `LOGGING_SCHEMA.md`. + - *Enforcement: Logging is performed by the agent's action execution wrapper.* +- **phase4-post-mortem**: Phase 4 (Pre-Submission Post-Mortem): The agent must formally close the task using the `close` command and complete the generated post-mortem report. + - *Enforcement: The `close` command in `tooling/fdc_cli.py` initiates this phase.* -**2. The Protocol Updater (`tooling/protocol_updater.py`):** -- A new, dedicated tool for programmatically modifying the protocol source files (`*.protocol.json`). -- It accepts commands like `add-tool`, allowing for precise, automated changes to protocol definitions. - -**3. The Orchestrator (`tooling/self_correction_orchestrator.py`):** -- This script is the engine of the cycle. It reads `lessons.jsonl`, identifies pending lessons, and uses the `protocol_updater.py` to execute the defined actions. -- After applying a lesson, it updates the lesson's status, creating a clear audit trail. -- It finishes by running `make AGENTS.md` to ensure the changes are compiled into the live protocol. - -This new, automated cycle—**Analyze -> Structure Lesson -> Execute Correction -> Re-compile Protocol**—is a fundamental step towards autonomous self-improvement. +### Associated Tools +- `tooling/fdc_cli.py` +- `tooling/fdc_fsm.json` +- `knowledge_core/symbols.json` +- `knowledge_core/dependency_graph.json` +- `LOGGING_SCHEMA.md` +- `set_plan` +- `message_user` --- -# Protocol: Deep Research Cycle - -This protocol defines a standardized, multi-step plan for conducting in-depth research on a complex topic. It is designed to be a reusable, callable plan that ensures a systematic and thorough investigation. +## Protocol: standing-orders-001 +_A set of non-negotiable, high-priority mandates that govern the agent's behavior across all tasks._ -The cycle consists of five main phases: -1. **Review Scanned Documents:** The agent first reviews the content of documents found in the repository during the initial scan. This provides immediate, project-specific context. -2. **Initial Scoping & Keyword Generation:** Based on the initial topic and the information from scanned documents, the agent generates a set of search keywords. -3. **Broad Information Gathering:** The agent uses the keywords to perform broad web searches and collect a list of relevant URLs. -4. **Targeted Information Extraction:** The agent visits the most promising URLs to extract detailed information. -5. **Synthesis & Summary:** The agent synthesizes the gathered information into a coherent summary, which is saved to a research report file. +### Rules +- **aorp-mandate**: All Finite Development Cycles (FDCs) MUST be initiated using the FDC toolchain's 'start' command. This is non-negotiable. + - *Enforcement: Enforced by the agent's core operational loop and the `start` command in `tooling/fdc_cli.py`.* +- **rag-mandate**: For any task involving external technologies, Just-In-Time External RAG is REQUIRED to verify current best practices. Do not trust internal knowledge. + - *Enforcement: This is a core principle of the L3 orientation phase, utilizing tools like `google_search`.* +- **fdc-toolchain-mandate**: Use the `fdc_cli.py` tool for all core FDC state transitions: task initiation ('start'), plan linting ('lint'), and task closure ('close'). + - *Enforcement: The agent's internal logic is designed to prefer these specific tool commands for FDC state transitions.* -This structured approach ensures that research is not ad-hoc but is instead a repeatable and verifiable process. +### Associated Tools +- `tooling/fdc_cli.py` +- `google_search` +- `view_text_website` --- -# Protocol: The Formal Research Cycle (L4) - -This protocol establishes the L4 Deep Research Cycle, a specialized, self-contained Finite Development Cycle (FDC) designed for comprehensive knowledge acquisition. It elevates research from a simple tool-based action to a formal, verifiable process. - -## The Problem: Ad-Hoc Research - -Previously, research was an unstructured activity. The agent could use tools like `google_search` or `read_file`, but there was no formal process for planning, executing, and synthesizing complex research tasks. This made it difficult to tackle "unknown unknowns" in a reliable and auditable way. - -## The Solution: A Dedicated Research FDC - -The L4 Research Cycle solves this by introducing a new, specialized Finite State Machine (FSM) tailored specifically for research. When the main orchestrator (`master_control.py`) determines that a task requires deep knowledge, it initiates this cycle. - -### Key Features: +## Protocol: cfdc-protocol-001 +_Defines the Context-Free Development Cycle (CFDC), a hierarchical planning and execution model._ -1. **Specialized FSM (`tooling/research_fsm.json`):** Unlike the generic development FSM, the research FSM has states that reflect a true research workflow: `GATHERING`, `SYNTHESIZING`, and `REPORTING`. This provides a more accurate model for the task. -2. **Executable Plans:** The `tooling/research_planner.py` is upgraded to generate formal, executable plans that are validated against the new research FSM. These are no longer just templates but are verifiable artifacts that guide the agent through the research process. -3. **Formal Invocation:** The L4 cycle is a first-class citizen in the agent's architecture. The main orchestrator can formally invoke it, execute the research plan, and then integrate the resulting knowledge back into its main task. +### Rules +- **hierarchical-planning-via-call-plan**: Plans may execute other plans as sub-routines using the 'call_plan ' directive. This enables a modular, hierarchical workflow. + - *Enforcement: The plan validator must be able to parse this directive and recursively validate sub-plans. The execution engine must implement a plan execution stack to manage the context of nested calls.* +- **max-recursion-depth**: To ensure decidability, the plan execution stack must not exceed a system-wide constant, MAX_RECURSION_DEPTH. This prevents infinite recursion and guarantees all processes will terminate. + - *Enforcement: The execution engine must check the stack depth before every 'call_plan' execution and terminate with a fatal error if the limit would be exceeded.* -This new protocol provides a robust, reliable, and formally verifiable mechanism for the agent to explore complex topics, making it significantly more autonomous and capable. +### Associated Tools +- `tooling/master_control.py` +- `tooling/fdc_cli.py` --- -```json -{ - "protocol_id": "aorp-header", - "description": "Defines the identity and versioning of the Advanced Orientation and Research Protocol (AORP).", - "rules": [ - { - "rule_id": "aorp-identity", - "description": "The governing protocol set is identified as the Advanced Orientation and Research Protocol (AORP).", - "enforcement": "Protocol is identified by its name in documentation and compiled artifacts." - }, - { - "rule_id": "aorp-versioning", - "description": "The official protocol version is tracked in the VERSION file in the repository root, following Semantic Versioning (SemVer).", - "enforcement": "Build or validation scripts should verify the presence and format of the VERSION file." - } - ] -} -``` +## Protocol: plan-registry-001 +_Defines a central registry for discovering and executing hierarchical plans by a logical name._ +### Rules +- **registry-definition**: A central plan registry MUST exist at 'knowledge_core/plan_registry.json'. It maps logical plan names to their file paths. + - *Enforcement: The file's existence and format can be checked by the validation toolchain.* +- **registry-first-resolution**: The 'call_plan ' directive MUST first attempt to resolve '' as a logical name in the plan registry. If resolution fails, it MUST fall back to treating '' as a direct file path for backward compatibility. + - *Enforcement: This logic must be implemented in both the plan validator (`fdc_cli.py`) and the execution engine (`master_control.py`).* +- **registry-management-tool**: A dedicated tool (`tooling/plan_manager.py`) MUST be provided for managing the plan registry, with functions to register, deregister, and list plans. + - *Enforcement: The tool's existence and functionality can be verified via integration tests.* ---- - -```json -{ - "protocol_id": "core-directive-001", - "description": "The mandatory first action for any new task, ensuring a formal start to the Finite Development Cycle (FDC).", - "rules": [ - { - "rule_id": "mandatory-fdc-start", - "description": "Upon receiving a new task, the agent's first action MUST be to programmatically execute the FDC 'start' command to formally initiate the task and run the AORP orientation cascade.", - "enforcement": "This is a hard-coded behavior in the agent's core operational loop and is verified by the FDC toolchain." - } - ], - "associated_tools": [ - "tooling/fdc_cli.py" - ] -} -``` - +### Associated Tools +- `tooling/plan_manager.py` +- `tooling/master_control.py` +- `tooling/fdc_cli.py` --- -```json -{ - "protocol_id": "decidability-constraints-001", - "description": "Ensures all development processes are formally decidable and computationally tractable.", - "rules": [ - { - "rule_id": "non-turing-completeness", - "description": "The agent's planning and execution language is, by design, not Turing-complete. This is a fundamental constraint to guarantee that all processes will terminate.", - "enforcement": "Enforced by the design of the plan runner and validated by the `lint` command in the FDC toolchain." - }, - { - "rule_id": "bounded-recursion", - "description": "The agent MUST NOT generate plans that involve recursion or self-invocation. A plan cannot trigger another FDC or a sub-plan, with the sole exception of the 'Deep Research Cycle'.", - "enforcement": "The `lint` command in `tooling/fdc_cli.py` scans plans for disallowed recursive calls." - }, - { - "rule_id": "fsm-adherence", - "description": "All plans must be valid strings in the language defined by the tooling/fdc_fsm.json Finite State Machine.", - "enforcement": "The `lint` command in `tooling/fdc_cli.py` validates the plan against the FSM definition." - } - ], - "associated_tools": [ - "tooling/fdc_cli.py", - "tooling/fdc_fsm.json" - ] -} -``` +## Protocol: self-correction-protocol-001 +_Defines the automated, closed-loop workflow for protocol self-correction._ +### Rules +- **structured-lessons**: Lessons learned from post-mortem analysis must be generated as structured, machine-readable JSON objects in `knowledge_core/lessons.jsonl`. + - *Enforcement: The `tooling/knowledge_compiler.py` script is responsible for generating lessons in the correct format.* +- **programmatic-updates**: All modifications to protocol source files must be performed programmatically via the `tooling/protocol_updater.py` tool to ensure consistency and prevent manual errors. + - *Enforcement: Agent's core logic should be designed to use this tool for all protocol modifications.* +- **automated-orchestration**: The self-correction cycle must be managed by the `tooling/self_correction_orchestrator.py` script, which processes pending lessons and triggers the necessary updates. + - *Enforcement: This script is the designated engine for the PDSC workflow.* +- **programmatic-rule-refinement**: The self-correction system can modify the description of existing protocol rules via the `update-rule` command in `tooling/protocol_updater.py`, allowing it to refine its own logic. + - *Enforcement: The `tooling/knowledge_compiler.py` can generate `update-rule` actions, and the `tooling/self_correction_orchestrator.py` executes them.* +- **autonomous-code-suggestion**: The self-correction system can generate and apply code changes to its own tooling. This is achieved through a `PROPOSE_CODE_CHANGE` action, which is processed by `tooling/code_suggester.py` to create an executable plan. + - *Enforcement: The `tooling/self_correction_orchestrator.py` invokes the code suggester when it processes a lesson of this type.* ---- - -```json -{ - "protocol_id": "orientation-cascade-001", - "description": "Defines the mandatory, four-tiered orientation cascade that must be executed at the start of any task to establish a coherent model of the agent's identity, environment, and the world state.", - "rules": [ - { - "rule_id": "l1-self-awareness", - "description": "Level 1 (Self-Awareness): The agent must first establish its own identity and inherent limitations by reading the `knowledge_core/agent_meta.json` artifact.", - "enforcement": "The `start` command of the FDC toolchain executes this step and fails if the artifact is missing or invalid." - }, - { - "rule_id": "l2-repository-sync", - "description": "Level 2 (Repository Sync): The agent must understand the current state of the local repository by loading primary artifacts from the `knowledge_core/` directory.", - "enforcement": "The `start` command of the FDC toolchain executes this step." - }, - { - "rule_id": "l3-environmental-probing", - "description": "Level 3 (Environmental Probing & Targeted RAG): The agent must discover the rules and constraints of its operational environment by executing a probe script and using targeted RAG to resolve 'known unknowns'.", - "enforcement": "The `start` command of the FDC toolchain executes this step, utilizing tools like `google_search` and `view_text_website`." - }, - { - "rule_id": "l4-deep-research-cycle", - "description": "Level 4 (Deep Research Cycle): To investigate 'unknown unknowns', the agent must initiate a formal, self-contained Finite Development Cycle (FDC) of the 'Analysis Modality'.", - "enforcement": "This is a special case of recursion, explicitly allowed and managed by the FDC toolchain." - } - ], - "associated_tools": [ - "tooling/environmental_probe.py", - "google_search", - "view_text_website" - ] -} -``` - +### Associated Tools +- `tooling/knowledge_compiler.py` +- `tooling/protocol_updater.py` +- `tooling/self_correction_orchestrator.py` +- `tooling/code_suggester.py` +- `initiate_memory_recording` --- -```json -{ - "protocol_id": "fdc-protocol-001", - "description": "Defines the Finite Development Cycle (FDC), a formally defined process for executing a single, coherent task.", - "rules": [ - { - "rule_id": "fdc-entry-point", - "description": "The AORP cascade is the mandatory entry point to every FDC.", - "enforcement": "Enforced by the `start` command in `tooling/fdc_cli.py`." - }, - { - "rule_id": "fdc-state-transitions", - "description": "The FDC is a Finite State Machine (FSM) formally defined in `tooling/fdc_fsm.json`. Plans must be valid strings in the language defined by this FSM.", - "enforcement": "Validated by the `lint` command in `tooling/fdc_cli.py`." - }, - { - "rule_id": "phase1-deconstruction", - "description": "Phase 1 (Deconstruction & Contextualization): The agent must ingest the task, query historical logs, identify entities using the symbol map, and analyze impact using the dependency graph.", - "enforcement": "Procedural step guided by the agent's core logic, using artifacts in `logs/` and `knowledge_core/`." - }, - { - "rule_id": "phase2-planning", - "description": "Phase 2 (Planning & Self-Correction): The agent must generate a granular plan, lint it using the FDC toolchain, cite evidence for its steps, and perform a critical review.", - "enforcement": "The `lint` command in `tooling/fdc_cli.py` is a mandatory pre-flight check." - }, - { - "rule_id": "phase3-execution", - "description": "Phase 3 (Execution & Structured Logging): The agent must execute the validated plan and log every action according to the `LOGGING_SCHEMA.md`.", - "enforcement": "Logging is performed by the agent's action execution wrapper." - }, - { - "rule_id": "phase4-post-mortem", - "description": "Phase 4 (Pre-Submission Post-Mortem): The agent must formally close the task using the `close` command and complete the generated post-mortem report.", - "enforcement": "The `close` command in `tooling/fdc_cli.py` initiates this phase." - } - ], - "associated_tools": [ - "tooling/fdc_cli.py", - "tooling/fdc_fsm.json", - "knowledge_core/symbols.json", - "knowledge_core/dependency_graph.json", - "LOGGING_SCHEMA.md", - "set_plan", - "message_user" - ] -} -``` - - ---- +## Protocol: research-protocol-001 +_A protocol for conducting systematic research using the integrated research toolchain._ -```json -{ - "protocol_id": "standing-orders-001", - "description": "A set of non-negotiable, high-priority mandates that govern the agent's behavior across all tasks.", - "rules": [ - { - "rule_id": "aorp-mandate", - "description": "All Finite Development Cycles (FDCs) MUST be initiated using the FDC toolchain's 'start' command. This is non-negotiable.", - "enforcement": "Enforced by the agent's core operational loop and the `start` command in `tooling/fdc_cli.py`." - }, - { - "rule_id": "rag-mandate", - "description": "For any task involving external technologies, Just-In-Time External RAG is REQUIRED to verify current best practices. Do not trust internal knowledge.", - "enforcement": "This is a core principle of the L3 orientation phase, utilizing tools like `google_search`." - }, - { - "rule_id": "fdc-toolchain-mandate", - "description": "Use the `fdc_cli.py` tool for all core FDC state transitions: task initiation ('start'), plan linting ('lint'), and task closure ('close').", - "enforcement": "The agent's internal logic is designed to prefer these specific tool commands for FDC state transitions." - } - ], - "associated_tools": [ - "tooling/fdc_cli.py", - "google_search", - "view_text_website" - ] -} -``` +### Rules +- **mandate-research-tools**: For all complex research tasks, the `plan_deep_research` tool MUST be used to generate a plan, and the `execute_research_protocol` tool MUST be used for data gathering. This ensures a systematic and auditable research process. + - *Enforcement: Adherence is monitored by the Code Review Critic and through post-mortem analysis of the activity log.* +### Associated Tools +- `tooling.research_planner.plan_deep_research` +- `tooling.research.execute_research_protocol` --- -```json -{ - "protocol_id": "cfdc-protocol-001", - "description": "Defines the Context-Free Development Cycle (CFDC), a hierarchical planning and execution model.", - "rules": [ - { - "rule_id": "hierarchical-planning-via-call-plan", - "description": "Plans may execute other plans as sub-routines using the 'call_plan ' directive. This enables a modular, hierarchical workflow.", - "enforcement": "The plan validator must be able to parse this directive and recursively validate sub-plans. The execution engine must implement a plan execution stack to manage the context of nested calls." - }, - { - "rule_id": "max-recursion-depth", - "description": "To ensure decidability, the plan execution stack must not exceed a system-wide constant, MAX_RECURSION_DEPTH. This prevents infinite recursion and guarantees all processes will terminate.", - "enforcement": "The execution engine must check the stack depth before every 'call_plan' execution and terminate with a fatal error if the limit would be exceeded." - } - ], - "associated_tools": [ - "tooling/master_control.py", - "tooling/fdc_cli.py" - ] -} -``` +## Protocol: self-modification-001 +_A meta-protocol governing the agent's modification of its own governing protocols._ +### Rules +- **source-only-modification**: The agent MUST NOT edit any 'AGENTS.md' file directly. All modifications to protocols must be made to the '.protocol.json' source files within the 'protocols/' directories. + - *Enforcement: Procedural rule. The agent must demonstrate awareness of this by using tools like 'replace_with_git_merge_diff' or 'create_file_with_block' on source files, not build artifacts.* +- **rebuild-after-modification**: After modifying any '.protocol.json' source file, the agent MUST execute the main build script 'tooling/hierarchical_compiler.py' to regenerate all 'AGENTS.md' artifacts and the 'protocols.ttl' knowledge graph. + - *Enforcement: The agent's plan for modifying protocols must include a final step to run the build script. This can be verified by reviewing the execution log.* +- **validation-is-mandatory**: Any new or modified protocol source file MUST be successfully validated against the 'protocols/protocol.schema.json'. The build process, which includes this validation, must complete without errors. + - *Enforcement: The `hierarchical_compiler.py` script's successful execution serves as the enforcement mechanism.* +- **test-driven-protocol-development**: When adding or significantly altering a protocol, the agent SHOULD, where practical, create a temporary, illustrative test case (e.g., a deliberately invalid file) to prove the change has the intended effect and that the build system's error handling is robust. + - *Enforcement: This is a best-practice guideline. Adherence can be checked during code review by observing the agent's workflow.* ---- - -```json -{ - "protocol_id": "plan-registry-001", - "description": "Defines a central registry for discovering and executing hierarchical plans by a logical name.", - "rules": [ - { - "rule_id": "registry-definition", - "description": "A central plan registry MUST exist at 'knowledge_core/plan_registry.json'. It maps logical plan names to their file paths.", - "enforcement": "The file's existence and format can be checked by the validation toolchain." - }, - { - "rule_id": "registry-first-resolution", - "description": "The 'call_plan ' directive MUST first attempt to resolve '' as a logical name in the plan registry. If resolution fails, it MUST fall back to treating '' as a direct file path for backward compatibility.", - "enforcement": "This logic must be implemented in both the plan validator (`fdc_cli.py`) and the execution engine (`master_control.py`)." - }, - { - "rule_id": "registry-management-tool", - "description": "A dedicated tool (`tooling/plan_manager.py`) MUST be provided for managing the plan registry, with functions to register, deregister, and list plans.", - "enforcement": "The tool's existence and functionality can be verified via integration tests." - } - ], - "associated_tools": [ - "tooling/plan_manager.py", - "tooling/master_control.py", - "tooling/fdc_cli.py" - ] -} -``` - +### Associated Tools +- `tooling/hierarchical_compiler.py` +- `tooling/compiler.py` +- `tooling/knowledge_graph_generator.py` +- `protocols/protocol.schema.json` --- -```json -{ - "protocol_id": "self-correction-protocol-001", - "description": "Defines the automated, closed-loop workflow for protocol self-correction.", - "rules": [ - { - "rule_id": "structured-lessons", - "description": "Lessons learned from post-mortem analysis must be generated as structured, machine-readable JSON objects in `knowledge_core/lessons.jsonl`.", - "enforcement": "The `tooling/knowledge_compiler.py` script is responsible for generating lessons in the correct format." - }, - { - "rule_id": "programmatic-updates", - "description": "All modifications to protocol source files must be performed programmatically via the `tooling/protocol_updater.py` tool to ensure consistency and prevent manual errors.", - "enforcement": "Agent's core logic should be designed to use this tool for all protocol modifications." - }, - { - "rule_id": "automated-orchestration", - "description": "The self-correction cycle must be managed by the `tooling/self_correction_orchestrator.py` script, which processes pending lessons and triggers the necessary updates.", - "enforcement": "This script is the designated engine for the PDSC workflow." - }, - { - "rule_id": "programmatic-rule-refinement", - "description": "The self-correction system can modify the description of existing protocol rules via the `update-rule` command in `tooling/protocol_updater.py`, allowing it to refine its own logic.", - "enforcement": "The `tooling/knowledge_compiler.py` can generate `update-rule` actions, and the `tooling/self_correction_orchestrator.py` executes them." - }, - { - "rule_id": "autonomous-code-suggestion", - "description": "The self-correction system can generate and apply code changes to its own tooling. This is achieved through a `PROPOSE_CODE_CHANGE` action, which is processed by `tooling/code_suggester.py` to create an executable plan.", - "enforcement": "The `tooling/self_correction_orchestrator.py` invokes the code suggester when it processes a lesson of this type." - } - ], - "associated_tools": [ - "tooling/knowledge_compiler.py", - "tooling/protocol_updater.py", - "tooling/self_correction_orchestrator.py", - "tooling/code_suggester.py", - "initiate_memory_recording" - ], - "associated_artifacts": [ - "knowledge_core/lessons.jsonl" - ] -} -``` +## Protocol: deep-research-cycle-001 +_A standardized, callable plan for conducting in-depth research on a complex topic._ +### Rules +- **structured-research-phases**: The deep research plan MUST follow a structured four-phase process: Scoping, Broad Gathering, Targeted Extraction, and Synthesis. + - *Enforcement: The plan's structure itself enforces this rule. The `lint` command can be extended to validate the structure of registered research plans.* ---- - -```json -{ - "protocol_id": "research-protocol-001", - "description": "A protocol for conducting systematic research using the integrated research toolchain.", - "rules": [ - { - "rule_id": "mandate-research-tools", - "description": "For all complex research tasks, the `plan_deep_research` tool MUST be used to generate a plan, and the `execute_research_protocol` tool MUST be used for data gathering. This ensures a systematic and auditable research process.", - "enforcement": "Adherence is monitored by the Code Review Critic and through post-mortem analysis of the activity log." - } - ], - "associated_tools": [ - "tooling.research_planner.plan_deep_research", - "tooling.research.execute_research_protocol" - ] -} -``` - +### Associated Tools +- `google_search` +- `view_text_website` +- `create_file_with_block` --- -```json -{ - "protocol_id": "deep-research-cycle-001", - "description": "A standardized, callable plan for conducting in-depth research on a complex topic.", - "rules": [ - { - "rule_id": "structured-research-phases", - "description": "The deep research plan MUST follow a structured four-phase process: Scoping, Broad Gathering, Targeted Extraction, and Synthesis.", - "enforcement": "The plan's structure itself enforces this rule. The `lint` command can be extended to validate the structure of registered research plans." - } - ], - "associated_tools": [ - "google_search", - "view_text_website", - "create_file_with_block" - ] -} -``` - - ---- +## Protocol: research-fdc-001 +_Defines the formal Finite Development Cycle (FDC) for conducting deep research._ -```json -{ - "protocol_id": "research-fdc-001", - "description": "Defines the formal Finite Development Cycle (FDC) for conducting deep research.", - "rules": [ - { - "rule_id": "specialized-fsm", - "description": "The Research FDC must be governed by its own dedicated Finite State Machine, defined in `tooling/research_fsm.json`. This FSM is tailored for a research workflow, with states for gathering, synthesis, and reporting.", - "enforcement": "The `master_control.py` orchestrator must load and execute plans against this specific FSM when initiating an L4 Deep Research Cycle." - }, - { - "rule_id": "executable-plans", - "description": "Research plans must be generated by `tooling/research_planner.py` as valid, executable plans that conform to the `research_fsm.json` definition. They are not just templates but formal, verifiable artifacts.", - "enforcement": "The output of the research planner must be linted and validated by the `fdc_cli.py` tool using the `research_fsm.json`." - }, - { - "rule_id": "l4-invocation", - "description": "The L4 Deep Research Cycle is the designated mechanism for resolving complex 'unknown unknowns'. It is invoked by the main orchestrator when a task requires knowledge that cannot be obtained through simple L1-L3 orientation probes.", - "enforcement": "The `master_control.py` orchestrator is responsible for triggering the L4 cycle." - } - ], - "associated_tools": [ - "tooling/master_control.py", - "tooling/research_planner.py", - "tooling/research.py", - "tooling/fdc_cli.py" - ] -} -``` +### Rules +- **specialized-fsm**: The Research FDC must be governed by its own dedicated Finite State Machine, defined in `tooling/research_fsm.json`. This FSM is tailored for a research workflow, with states for gathering, synthesis, and reporting. + - *Enforcement: The `master_control.py` orchestrator must load and execute plans against this specific FSM when initiating an L4 Deep Research Cycle.* +- **executable-plans**: Research plans must be generated by `tooling/research_planner.py` as valid, executable plans that conform to the `research_fsm.json` definition. They are not just templates but formal, verifiable artifacts. + - *Enforcement: The output of the research planner must be linted and validated by the `fdc_cli.py` tool using the `research_fsm.json`.* +- **l4-invocation**: The L4 Deep Research Cycle is the designated mechanism for resolving complex 'unknown unknowns'. It is invoked by the main orchestrator when a task requires knowledge that cannot be obtained through simple L1-L3 orientation probes. + - *Enforcement: The `master_control.py` orchestrator is responsible for triggering the L4 cycle.* +### Associated Tools +- `tooling/master_control.py` +- `tooling/research_planner.py` +- `tooling/research.py` +- `tooling/fdc_cli.py` --- diff --git a/core/protocols/99_self_modification.protocol.json b/core/protocols/99_self_modification.protocol.json new file mode 100644 index 00000000..c6b38d1c --- /dev/null +++ b/core/protocols/99_self_modification.protocol.json @@ -0,0 +1,32 @@ +{ + "protocol_id": "self-modification-001", + "description": "A meta-protocol governing the agent's modification of its own governing protocols.", + "rules": [ + { + "rule_id": "source-only-modification", + "description": "The agent MUST NOT edit any 'AGENTS.md' file directly. All modifications to protocols must be made to the '.protocol.json' source files within the 'protocols/' directories.", + "enforcement": "Procedural rule. The agent must demonstrate awareness of this by using tools like 'replace_with_git_merge_diff' or 'create_file_with_block' on source files, not build artifacts." + }, + { + "rule_id": "rebuild-after-modification", + "description": "After modifying any '.protocol.json' source file, the agent MUST execute the main build script 'tooling/hierarchical_compiler.py' to regenerate all 'AGENTS.md' artifacts and the 'protocols.ttl' knowledge graph.", + "enforcement": "The agent's plan for modifying protocols must include a final step to run the build script. This can be verified by reviewing the execution log." + }, + { + "rule_id": "validation-is-mandatory", + "description": "Any new or modified protocol source file MUST be successfully validated against the 'protocols/protocol.schema.json'. The build process, which includes this validation, must complete without errors.", + "enforcement": "The `hierarchical_compiler.py` script's successful execution serves as the enforcement mechanism." + }, + { + "rule_id": "test-driven-protocol-development", + "description": "When adding or significantly altering a protocol, the agent SHOULD, where practical, create a temporary, illustrative test case (e.g., a deliberately invalid file) to prove the change has the intended effect and that the build system's error handling is robust.", + "enforcement": "This is a best-practice guideline. Adherence can be checked during code review by observing the agent's workflow." + } + ], + "associated_tools": [ + "tooling/hierarchical_compiler.py", + "tooling/compiler.py", + "tooling/knowledge_graph_generator.py", + "protocols/protocol.schema.json" + ] +} \ No newline at end of file diff --git a/critic/AGENTS.md b/critic/AGENTS.md index 4d537636..c26a962b 100644 --- a/critic/AGENTS.md +++ b/critic/AGENTS.md @@ -1,98 +1,28 @@ -# --- -# DO NOT EDIT THIS FILE DIRECTLY. -# This file is programmatically generated by the `protocol_compiler.py` script. -# All changes to agent protocols must be made in the source files -# located in the `protocols/` directory. -# -# This file contains the compiled protocols in a human-readable Markdown format, -# with machine-readable JSON definitions embedded. -# --- +# Agent Protocols +_This document is auto-generated from protocol source files. Do not edit it directly._ -# Meta-Protocol: Code Review Critic Evaluation Context +## Protocol: critic-meta-protocol-001 +_A meta-protocol that governs the behavior and evaluation criteria of the Code Review Critic agent._ -This protocol governs the behavior of the Code Review Critic agent. Its purpose is to provide the critic with the necessary context to perform accurate and helpful evaluations of changes made by other agents. - -## Rule: Protocols are Functional Source Code - -The `protocols/` directory is not just documentation; it is a core part of the agent's functional definition. The `.json` and `.md` files within this directory define the rules, capabilities, and constraints that govern the agent's behavior. Therefore, any changes to these files must be treated as **functional source code** and reviewed with the same level of scrutiny as changes to Python scripts. - -## Rule: Built-in Tools are Valid Dependencies - -The agent possesses a set of core, built-in tools provided by its execution environment (e.g., `read_file`, `list_files`, `submit`, `pre_commit_instructions`). The source code for these tools does not reside within this repository. - -When a protocol is modified to include one of these built-in tools in its `associated_tools` list, this constitutes a valid and complete functional change. It is an act of formally bringing an existing capability under the governance of a protocol. Such a change **must not** be flagged as "incomplete" simply because the tool's implementation is not included in the patch. - -## Rule: Definition of a "Functional Change" - -A change should be considered "functional" if it correctly modifies the agent's operational capabilities. This is determined by the combined state of the Python source code *and* the protocol source files. The critic's evaluation must consider both aspects to form a complete picture of the change's impact. - -## Rule: Adherence to Specific Prohibitions - -The critic must be aware of and strictly adhere to all specific prohibition protocols. This includes, but is not limited to, the `critic-reset-prohibition-001` protocol, which forbids the use of the `reset_all` tool. The critic's primary function is analysis, not destructive action. - - ---- - -# Protocol: Critic `reset_all` Prohibition - -This protocol establishes a critical safeguard to protect the integrity of the development workflow. - -## Rule: `critic-no-reset` - -The agent assigned the role of 'Code Review Critic' is explicitly and strictly forbidden from using the `reset_all` tool. - -**Rationale:** The `reset_all` tool is a destructive action that reverts all changes in the workspace. Its use by a review agent could lead to the accidental deletion of work-in-progress, creating a significant disruption. This protocol ensures that the critic's function is limited to analysis and feedback, preventing it from taking destructive actions. - -This prohibition is non-negotiable and must be adhered to by any agent assuming the 'Code Review Critic' role. - -**Enforcement Mechanism:** The Code Review Critic is not implemented in this repository. Its behavior is governed by the compiled `AGENTS.md` file, which is consumed by an external orchestration system. The inclusion of this protocol in `AGENTS.md` constitutes the complete implementation of this safeguard from the perspective of this codebase. +### Rules +- **protocol-as-source-code**: The `protocols/` directory and all its contents (`.md`, `.json` files) MUST be treated as functional source code. Changes to these files directly alter the agent's operational capabilities and governing rules. + - *Enforcement: The Code Review Critic must analyze changes in this directory with the same rigor as changes to `.py` files.* +- **built-in-tools-are-valid**: The agent's execution environment provides a set of built-in tools (e.g., `read_file`, `delete_file`, `pre_commit_instructions`). The implementation of these tools does not reside within the repository. A protocol change that adds a built-in tool to the `associated_tools` list is a valid and complete functional change. + - *Enforcement: The Code Review Critic must not flag a change as 'incomplete' or 'non-functional' solely because the implementation of a built-in tool is not present in the repository.* +- **functional-change-definition**: A change is considered 'functional' if it correctly modifies the agent's operational rules or capabilities, as defined by the combination of Python source code and the protocol source files in `protocols/`. + - *Enforcement: The Code Review Critic's evaluation of 'functionality' must encompass both traditional code and protocol definitions.* --- -```json -{ - "protocol_id": "critic-meta-protocol-001", - "description": "A meta-protocol that governs the behavior and evaluation criteria of the Code Review Critic agent.", - "rules": [ - { - "rule_id": "protocol-as-source-code", - "description": "The `protocols/` directory and all its contents (`.md`, `.json` files) MUST be treated as functional source code. Changes to these files directly alter the agent's operational capabilities and governing rules.", - "enforcement": "The Code Review Critic must analyze changes in this directory with the same rigor as changes to `.py` files." - }, - { - "rule_id": "built-in-tools-are-valid", - "description": "The agent's execution environment provides a set of built-in tools (e.g., `read_file`, `delete_file`, `pre_commit_instructions`). The implementation of these tools does not reside within the repository. A protocol change that adds a built-in tool to the `associated_tools` list is a valid and complete functional change.", - "enforcement": "The Code Review Critic must not flag a change as 'incomplete' or 'non-functional' solely because the implementation of a built-in tool is not present in the repository." - }, - { - "rule_id": "functional-change-definition", - "description": "A change is considered 'functional' if it correctly modifies the agent's operational rules or capabilities, as defined by the combination of Python source code and the protocol source files in `protocols/`.", - "enforcement": "The Code Review Critic's evaluation of 'functionality' must encompass both traditional code and protocol definitions." - } - ] -} -``` - - ---- +## Protocol: critic-reset-prohibition-001 +_A specific, high-priority protocol that forbids the Code Review Critic agent from using the 'reset_all' tool._ -```json -{ - "protocol_id": "critic-reset-prohibition-001", - "description": "A specific, high-priority protocol that forbids the Code Review Critic agent from using the 'reset_all' tool.", - "rules": [ - { - "rule_id": "critic-no-reset", - "description": "The agent role-playing as the 'Code Review Critic' is explicitly forbidden from invoking the 'reset_all' tool under any circumstances. This is a critical safeguard to prevent the loss of work during the review process.", - "enforcement": "This rule is enforced by its inclusion in the compiled AGENTS.md, which serves as the context for the Code Review Critic. The critic must be programmed to parse and adhere to this prohibition." - } - ], - "associated_tools": [ - "reset_all" - ] -} -``` +### Rules +- **critic-no-reset**: The agent role-playing as the 'Code Review Critic' is explicitly forbidden from invoking the 'reset_all' tool under any circumstances. This is a critical safeguard to prevent the loss of work during the review process. + - *Enforcement: This rule is enforced by its inclusion in the compiled AGENTS.md, which serves as the context for the Code Review Critic. The critic must be programmed to parse and adhere to this prohibition.* +### Associated Tools +- `reset_all` --- diff --git a/protocols.ttl b/protocols.ttl new file mode 100644 index 00000000..2fe097bf --- /dev/null +++ b/protocols.ttl @@ -0,0 +1,683 @@ +@prefix dcterms: . +@prefix proto: . +@prefix rdf: . +@prefix rdfs: . + +proto:Protocol a rdfs:Class ; + rdfs:label "Protocol" . + +proto:Rule a rdfs:Class ; + rdfs:label "Rule" . + +proto:governsTool a rdf:Property . + +proto:hasRule a rdf:Property . + + a proto:Protocol ; + rdfs:label "agent-bootstrap-001" ; + proto:governsTool "read_file" ; + proto:hasRule ; + dcterms:description "A foundational protocol that dictates the agent's initial actions upon starting any task." . + + a proto:Protocol ; + rdfs:label "agent-interaction-001" ; + proto:governsTool "message_user", + "set_plan" ; + proto:hasRule , + ; + dcterms:description "A protocol governing the agent's core interaction and planning tools." . + + a proto:Protocol ; + rdfs:label "agent-shell-001" ; + proto:governsTool "tooling/agent_shell.py" ; + proto:hasRule ; + dcterms:description "A protocol governing the use of the interactive agent shell as the primary entry point for all tasks." . + + a proto:Protocol ; + rdfs:label "aorp-header" ; + proto:hasRule , + ; + dcterms:description "Defines the identity and versioning of the Advanced Orientation and Research Protocol (AORP)." . + + a proto:Protocol ; + rdfs:label "aura-execution-001" ; + proto:governsTool "tooling/aura_executor.py" ; + proto:hasRule ; + dcterms:description "A protocol for executing Aura scripts, enabling a more expressive and powerful planning and automation language for the agent." . + + a proto:Protocol ; + rdfs:label "best-practices-001" ; + proto:governsTool "create_file_with_block", + "delete_file", + "grep", + "list_files", + "overwrite_file_with_block", + "read_file", + "replace_with_git_merge_diff" ; + proto:hasRule ; + dcterms:description "A set of best practices derived from observing successful, data-driven workflow patterns." . + + a proto:Protocol ; + rdfs:label "capability-verification-001" ; + proto:governsTool "tooling/capability_verifier.py" ; + proto:hasRule ; + dcterms:description "A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement." . + + a proto:Protocol ; + rdfs:label "cfdc-protocol-001" ; + proto:governsTool "tooling/fdc_cli.py", + "tooling/master_control.py" ; + proto:hasRule , + ; + dcterms:description "Defines the Context-Free Development Cycle (CFDC), a hierarchical planning and execution model." . + + a proto:Protocol ; + rdfs:label "core-directive-001" ; + proto:governsTool "tooling/fdc_cli.py" ; + proto:hasRule ; + dcterms:description "The mandatory first action for any new task, ensuring a formal start to the Finite Development Cycle (FDC)." . + + a proto:Protocol ; + rdfs:label "critic-meta-protocol-001" ; + proto:hasRule , + , + ; + dcterms:description "A meta-protocol that governs the behavior and evaluation criteria of the Code Review Critic agent." . + + a proto:Protocol ; + rdfs:label "critic-reset-prohibition-001" ; + proto:governsTool "reset_all" ; + proto:hasRule ; + dcterms:description "A specific, high-priority protocol that forbids the Code Review Critic agent from using the 'reset_all' tool." . + + a proto:Protocol ; + rdfs:label "csdc-001" ; + proto:governsTool "tooling/csdc_cli.py" ; + proto:hasRule , + , + ; + dcterms:description "A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints." . + + a proto:Protocol ; + rdfs:label "decidability-constraints-001" ; + proto:governsTool "tooling/fdc_cli.py", + "tooling/fdc_fsm.json" ; + proto:hasRule , + , + ; + dcterms:description "Ensures all development processes are formally decidable and computationally tractable." . + + a proto:Protocol ; + rdfs:label "deep-research-cycle-001" ; + proto:governsTool "create_file_with_block", + "google_search", + "view_text_website" ; + proto:hasRule ; + dcterms:description "A standardized, callable plan for conducting in-depth research on a complex topic." . + + a proto:Protocol ; + rdfs:label "dependency-management-001" ; + proto:governsTool "run_in_bash_session" ; + proto:hasRule ; + dcterms:description "A protocol for ensuring a reliable execution environment through formal dependency management." . + + a proto:Protocol ; + rdfs:label "experimental-prologue-001" ; + proto:governsTool "create_file_with_block" ; + proto:hasRule ; + dcterms:description "An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation." . + + a proto:Protocol ; + rdfs:label "fdc-protocol-001" ; + proto:governsTool "LOGGING_SCHEMA.md", + "knowledge_core/dependency_graph.json", + "knowledge_core/symbols.json", + "message_user", + "set_plan", + "tooling/fdc_cli.py", + "tooling/fdc_fsm.json" ; + proto:hasRule , + , + , + , + , + ; + dcterms:description "Defines the Finite Development Cycle (FDC), a formally defined process for executing a single, coherent task." . + + a proto:Protocol ; + rdfs:label "file-indexing-001" ; + proto:governsTool "tooling/file_indexer.py" ; + proto:hasRule ; + dcterms:description "A protocol for maintaining an up-to-date file index to accelerate tool performance." . + + a proto:Protocol ; + rdfs:label "hdl-proving-001" ; + proto:governsTool "tooling/hdl_prover.py" ; + proto:hasRule ; + dcterms:description "A protocol for interacting with the Hypersequent-calculus-based logic engine, allowing the agent to perform formal logical proofs." . + + a proto:Protocol ; + rdfs:label "meta-protocol-001" ; + proto:governsTool "run_in_bash_session" ; + proto:hasRule ; + dcterms:description "A meta-protocol governing the agent's awareness and maintenance of its own core protocol files." . + + a proto:Protocol ; + rdfs:label "non-compliance-protocol-001" ; + proto:hasRule , + , + , + , + ; + dcterms:description "A protocol that defines non-compliance with AGENTS.md and specifies corrective actions." . + + a proto:Protocol ; + rdfs:label "orientation-cascade-001" ; + proto:governsTool "google_search", + "tooling/environmental_probe.py", + "view_text_website" ; + proto:hasRule , + , + , + ; + dcterms:description "Defines the mandatory, four-tiered orientation cascade that must be executed at the start of any task to establish a coherent model of the agent's identity, environment, and the world state." . + + a proto:Protocol ; + rdfs:label "plan-registry-001" ; + proto:governsTool "tooling/fdc_cli.py", + "tooling/master_control.py", + "tooling/plan_manager.py" ; + proto:hasRule , + , + ; + dcterms:description "Defines a central registry for discovering and executing hierarchical plans by a logical name." . + + a proto:Protocol ; + rdfs:label "plllu-execution-001" ; + proto:governsTool "tooling/plllu_runner.py" ; + proto:hasRule ; + dcterms:description "A protocol for executing pLLLU scripts, enabling a more expressive and powerful planning and automation language for the agent." . + + a proto:Protocol ; + rdfs:label "pre-commit-protocol-001" ; + proto:governsTool "code_linter", + "pre_commit_instructions" ; + proto:hasRule ; + dcterms:description "Defines the mandatory pre-commit checks to ensure code quality, correctness, and readiness for submission." . + + a proto:Protocol ; + rdfs:label "research-fdc-001" ; + proto:governsTool "tooling/fdc_cli.py", + "tooling/master_control.py", + "tooling/research.py", + "tooling/research_planner.py" ; + proto:hasRule , + , + ; + dcterms:description "Defines the formal Finite Development Cycle (FDC) for conducting deep research." . + + a proto:Protocol ; + rdfs:label "research-protocol-001" ; + proto:governsTool "tooling.research.execute_research_protocol", + "tooling.research_planner.plan_deep_research" ; + proto:hasRule ; + dcterms:description "A protocol for conducting systematic research using the integrated research toolchain." . + + a proto:Protocol ; + rdfs:label "reset-all-prohibition-001" ; + proto:governsTool "reset_all" ; + proto:hasRule ; + dcterms:description "A high-priority protocol that unconditionally forbids the use of the `reset_all` tool." . + + a proto:Protocol ; + rdfs:label "security-header" ; + dcterms:description "Defines the identity and purpose of the Security Protocol document." . + + a proto:Protocol ; + rdfs:label "security-vuln-reporting-001" ; + proto:hasRule , + ; + dcterms:description "Defines the official policy and procedure for reporting security vulnerabilities." . + + a proto:Protocol ; + rdfs:label "self-correction-protocol-001" ; + proto:governsTool "initiate_memory_recording", + "tooling/code_suggester.py", + "tooling/knowledge_compiler.py", + "tooling/protocol_updater.py", + "tooling/self_correction_orchestrator.py" ; + proto:hasRule , + , + , + , + ; + dcterms:description "Defines the automated, closed-loop workflow for protocol self-correction." . + + a proto:Protocol ; + rdfs:label "self-modification-001" ; + proto:governsTool "protocols/protocol.schema.json", + "tooling/compiler.py", + "tooling/hierarchical_compiler.py", + "tooling/knowledge_graph_generator.py" ; + proto:hasRule , + , + , + ; + dcterms:description "A meta-protocol governing the agent's modification of its own governing protocols." . + + a proto:Protocol ; + rdfs:label "speculative-execution-001" ; + proto:governsTool "create_file_with_block", + "request_user_input", + "set_plan" ; + proto:hasRule , + , + , + , + ; + dcterms:description "A protocol that governs the agent's ability to initiate and execute self-generated, creative, or exploratory tasks during idle periods." . + + a proto:Protocol ; + rdfs:label "standing-orders-001" ; + proto:governsTool "google_search", + "tooling/fdc_cli.py", + "view_text_website" ; + proto:hasRule , + , + ; + dcterms:description "A set of non-negotiable, high-priority mandates that govern the agent's behavior across all tasks." . + + a proto:Protocol ; + rdfs:label "toolchain-review-on-schema-change-001" ; + proto:governsTool "tooling/hierarchical_compiler.py", + "tooling/protocol_auditor.py", + "tooling/protocol_compiler.py" ; + proto:hasRule ; + dcterms:description "A meta-protocol to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols." . + + a proto:Protocol ; + rdfs:label "unified-auditor-001" ; + proto:governsTool "tooling/auditor.py" ; + proto:hasRule ; + dcterms:description "A protocol for the unified repository auditing tool, which combines multiple health and compliance checks into a single interface." . + + a proto:Protocol ; + rdfs:label "unified-doc-builder-001" ; + proto:governsTool "tooling/doc_builder.py" ; + proto:hasRule ; + dcterms:description "A protocol for the unified documentation builder, which generates various documentation artifacts from the repository's sources of truth." . + + a proto:Rule ; + rdfs:label "bootstrap-load-agents-md" ; + proto:enforcement "This rule is enforced by the agent's core startup logic. The agent must verify the load of AGENTS.md before proceeding to the planning phase." ; + dcterms:description "Upon initialization for any task, the agent's first and highest-priority action must be to locate, read, and parse the AGENTS.md file in the repository root. This ensures the agent is properly contextualized before any planning or execution begins." . + + a proto:Rule ; + rdfs:label "communication-tool-access" ; + proto:enforcement "The agent's core logic should be designed to use this tool for all user-facing communication." ; + dcterms:description "The agent is authorized to use the `message_user` tool to communicate with the user, providing updates and asking for clarification. This is essential for a collaborative workflow." . + + a proto:Rule ; + rdfs:label "planning-tool-access" ; + proto:enforcement "The agent's core logic should be designed to use this tool for all planning activities." ; + dcterms:description "The agent is authorized to use the `set_plan` tool to create and update its execution plan. This is a foundational capability for task execution." . + + a proto:Rule ; + rdfs:label "shell-is-primary-entry-point" ; + proto:enforcement "This is a procedural rule. The agent's operational framework should only expose the agent_shell.py as the means of starting a new task." ; + dcterms:description "All agent tasks must be initiated through the `agent_shell.py` script. This script is the designated, API-driven entry point that ensures proper initialization of the MasterControlGraph FSM, centralized logging, and programmatic lifecycle management. Direct execution of other tools or scripts is forbidden for task initiation." . + + a proto:Rule ; + rdfs:label "aorp-identity" ; + proto:enforcement "Protocol is identified by its name in documentation and compiled artifacts." ; + dcterms:description "The governing protocol set is identified as the Advanced Orientation and Research Protocol (AORP)." . + + a proto:Rule ; + rdfs:label "aorp-versioning" ; + proto:enforcement "Build or validation scripts should verify the presence and format of the VERSION file." ; + dcterms:description "The official protocol version is tracked in the VERSION file in the repository root, following Semantic Versioning (SemVer)." . + + a proto:Rule ; + rdfs:label "execute-aura-script" ; + proto:enforcement "The tool is used by invoking it from the command line with the path to the Aura script as an argument." ; + dcterms:description "The `aura_executor.py` tool should be used to execute .aura script files. This tool provides the bridge between the agent's master control loop and the Aura language interpreter." . + + a proto:Rule ; + rdfs:label "verify-after-write" ; + proto:enforcement "This is a core operational discipline. Future tooling, such as a trace validator, could enforce this by analyzing the execution log against this protocol." ; + dcterms:description "After every file creation or modification action (`create_file_with_block`, `overwrite_file_with_block`, `replace_with_git_merge_diff`), the agent MUST use a subsequent read-only tool (`read_file`, `list_files`, `grep`) to verify that the action was executed successfully and had the intended effect. A plan step should only be marked as complete after this verification." . + + a proto:Rule ; + rdfs:label "verify-capability-acquisition" ; + proto:enforcement "The tool is used by invoking it from the command line with the path to the target test file." ; + dcterms:description "The `capability_verifier.py` tool should be used to test the agent's ability to acquire a new capability defined by a failing test file. The tool orchestrates the failure, self-correction, and verification process." . + + a proto:Rule ; + rdfs:label "hierarchical-planning-via-call-plan" ; + proto:enforcement "The plan validator must be able to parse this directive and recursively validate sub-plans. The execution engine must implement a plan execution stack to manage the context of nested calls." ; + dcterms:description "Plans may execute other plans as sub-routines using the 'call_plan ' directive. This enables a modular, hierarchical workflow." . + + a proto:Rule ; + rdfs:label "max-recursion-depth" ; + proto:enforcement "The execution engine must check the stack depth before every 'call_plan' execution and terminate with a fatal error if the limit would be exceeded." ; + dcterms:description "To ensure decidability, the plan execution stack must not exceed a system-wide constant, MAX_RECURSION_DEPTH. This prevents infinite recursion and guarantees all processes will terminate." . + + a proto:Rule ; + rdfs:label "mandatory-fdc-start" ; + proto:enforcement "This is a hard-coded behavior in the agent's core operational loop and is verified by the FDC toolchain." ; + dcterms:description "Upon receiving a new task, the agent's first action MUST be to programmatically execute the FDC 'start' command to formally initiate the task and run the AORP orientation cascade." . + + a proto:Rule ; + rdfs:label "built-in-tools-are-valid" ; + proto:enforcement "The Code Review Critic must not flag a change as 'incomplete' or 'non-functional' solely because the implementation of a built-in tool is not present in the repository." ; + dcterms:description "The agent's execution environment provides a set of built-in tools (e.g., `read_file`, `delete_file`, `pre_commit_instructions`). The implementation of these tools does not reside within the repository. A protocol change that adds a built-in tool to the `associated_tools` list is a valid and complete functional change." . + + a proto:Rule ; + rdfs:label "functional-change-definition" ; + proto:enforcement "The Code Review Critic's evaluation of 'functionality' must encompass both traditional code and protocol definitions." ; + dcterms:description "A change is considered 'functional' if it correctly modifies the agent's operational rules or capabilities, as defined by the combination of Python source code and the protocol source files in `protocols/`." . + + a proto:Rule ; + rdfs:label "protocol-as-source-code" ; + proto:enforcement "The Code Review Critic must analyze changes in this directory with the same rigor as changes to `.py` files." ; + dcterms:description "The `protocols/` directory and all its contents (`.md`, `.json` files) MUST be treated as functional source code. Changes to these files directly alter the agent's operational capabilities and governing rules." . + + a proto:Rule ; + rdfs:label "critic-no-reset" ; + proto:enforcement "This rule is enforced by its inclusion in the compiled AGENTS.md, which serves as the context for the Code Review Critic. The critic must be programmed to parse and adhere to this prohibition." ; + dcterms:description "The agent role-playing as the 'Code Review Critic' is explicitly forbidden from invoking the 'reset_all' tool under any circumstances. This is a critical safeguard to prevent the loss of work during the review process." . + + a proto:Rule ; + rdfs:label "model-a-constraints" ; + proto:enforcement "Enforced by the `fsm_model_a.json` FSM used by the `csdc_cli.py` tool." ; + dcterms:description "Model A permits `define_set_of_names` but forbids `define_diagonalization_function`." . + + a proto:Rule ; + rdfs:label "model-b-constraints" ; + proto:enforcement "Enforced by the `fsm_model_b.json` FSM used by the `csdc_cli.py` tool." ; + dcterms:description "Model B permits `define_diagonalization_function` but forbids `define_set_of_names`." . + + a proto:Rule ; + rdfs:label "use-csdc-cli" ; + proto:enforcement "The tool is used by invoking it from the command line with the plan file, model, and complexity as arguments." ; + dcterms:description "The `csdc_cli.py` tool must be used to validate plans under the CSDC. This tool enforces model-specific constraints (A or B) and complexity requirements (P or EXP)." . + + a proto:Rule ; + rdfs:label "bounded-recursion" ; + proto:enforcement "The `lint` command in `tooling/fdc_cli.py` scans plans for disallowed recursive calls." ; + dcterms:description "The agent MUST NOT generate plans that involve recursion or self-invocation. A plan cannot trigger another FDC or a sub-plan, with the sole exception of the 'Deep Research Cycle'." . + + a proto:Rule ; + rdfs:label "fsm-adherence" ; + proto:enforcement "The `lint` command in `tooling/fdc_cli.py` validates the plan against the FSM definition." ; + dcterms:description "All plans must be valid strings in the language defined by the tooling/fdc_fsm.json Finite State Machine." . + + a proto:Rule ; + rdfs:label "non-turing-completeness" ; + proto:enforcement "Enforced by the design of the plan runner and validated by the `lint` command in the FDC toolchain." ; + dcterms:description "The agent's planning and execution language is, by design, not Turing-complete. This is a fundamental constraint to guarantee that all processes will terminate." . + + a proto:Rule ; + rdfs:label "structured-research-phases" ; + proto:enforcement "The plan's structure itself enforces this rule. The `lint` command can be extended to validate the structure of registered research plans." ; + dcterms:description "The deep research plan MUST follow a structured four-phase process: Scoping, Broad Gathering, Targeted Extraction, and Synthesis." . + + a proto:Rule ; + rdfs:label "dependency-install-on-start" ; + proto:enforcement "The agent's core startup logic should be designed to execute `pip install -r requirements.txt` as one of its initial actions." ; + dcterms:description "Upon starting a task, after loading AGENTS.md, the agent MUST install all required Python packages listed in the `requirements.txt` file. This ensures the environment is correctly configured before any other tools are executed." . + + a proto:Rule ; + rdfs:label "create-prologue-file" ; + proto:enforcement "This is a procedural rule. The agent must verify the existence of 'prologue.txt' before using 'create_file_with_block' or similar tools for other files." ; + dcterms:description "Before creating any new file as part of a task, the agent MUST first create a file named 'prologue.txt' with the content 'This is a prologue file.' This rule serves as a test of the agent's ability to adapt its behavior to new, dynamically loaded protocols." . + + a proto:Rule ; + rdfs:label "fdc-entry-point" ; + proto:enforcement "Enforced by the `start` command in `tooling/fdc_cli.py`." ; + dcterms:description "The AORP cascade is the mandatory entry point to every FDC." . + + a proto:Rule ; + rdfs:label "fdc-state-transitions" ; + proto:enforcement "Validated by the `lint` command in `tooling/fdc_cli.py`." ; + dcterms:description "The FDC is a Finite State Machine (FSM) formally defined in `tooling/fdc_fsm.json`. Plans must be valid strings in the language defined by this FSM." . + + a proto:Rule ; + rdfs:label "phase1-deconstruction" ; + proto:enforcement "Procedural step guided by the agent's core logic, using artifacts in `logs/` and `knowledge_core/`." ; + dcterms:description "Phase 1 (Deconstruction & Contextualization): The agent must ingest the task, query historical logs, identify entities using the symbol map, and analyze impact using the dependency graph." . + + a proto:Rule ; + rdfs:label "phase2-planning" ; + proto:enforcement "The `lint` command in `tooling/fdc_cli.py` is a mandatory pre-flight check." ; + dcterms:description "Phase 2 (Planning & Self-Correction): The agent must generate a granular plan, lint it using the FDC toolchain, cite evidence for its steps, and perform a critical review." . + + a proto:Rule ; + rdfs:label "phase3-execution" ; + proto:enforcement "Logging is performed by the agent's action execution wrapper." ; + dcterms:description "Phase 3 (Execution & Structured Logging): The agent must execute the validated plan and log every action according to the `LOGGING_SCHEMA.md`." . + + a proto:Rule ; + rdfs:label "phase4-post-mortem" ; + proto:enforcement "The `close` command in `tooling/fdc_cli.py` initiates this phase." ; + dcterms:description "Phase 4 (Pre-Submission Post-Mortem): The agent must formally close the task using the `close` command and complete the generated post-mortem report." . + + a proto:Rule ; + rdfs:label "update-index-before-submit" ; + proto:enforcement "This is a procedural rule. The agent's pre-submission checklist should include a step to run 'python tooling/file_indexer.py build'." ; + dcterms:description "Before submitting any changes that alter the file structure (create, delete, rename), the agent MUST rebuild the repository's file index. This ensures that tools relying on the index, such as the FDC validator, have an accurate view of the filesystem." . + + a proto:Rule ; + rdfs:label "prove-sequent" ; + proto:enforcement "The tool is used by invoking it from the command line with the sequent to be proved as an argument." ; + dcterms:description "The `hdl_prover.py` tool should be used to check the provability of a logical sequent. This tool acts as a wrapper for the underlying Lisp-based prover." . + + a proto:Rule ; + rdfs:label "agents-md-self-awareness" ; + proto:enforcement "The agent should incorporate this check into its standard operating procedure, particularly at the beginning of a task or when unexpected behavior occurs." ; + dcterms:description "The AGENTS.md file is a build artifact generated from source files in the 'protocols/' directory. Before relying on AGENTS.md, the agent should ensure it is up-to-date by running 'make AGENTS.md'. This ensures the agent is operating with the latest set of protocols." . + + a proto:Rule ; + rdfs:label "non-compliance-architectural-deviation" ; + proto:enforcement "Agent must revert non-compliant changes and re-implement them according to standards." ; + dcterms:description "Forbids changes that contradict documented architectural patterns or coding conventions." . + + a proto:Rule ; + rdfs:label "non-compliance-definition" ; + proto:enforcement "This is a definitional rule. Enforcement is achieved through the agent's adherence to the specific non-compliance rules that follow." ; + dcterms:description "Defines non-compliance as a violation of any rule, convention, or procedure in AGENTS.md or its source protocols." . + + a proto:Rule ; + rdfs:label "non-compliance-direct-editing" ; + proto:enforcement "Agent must revert direct edits and modify source files, then run the appropriate build command." ; + dcterms:description "Prohibits the direct editing of build artifacts like AGENTS.md or README.md. Changes must be made to source files, followed by a rebuild." . + + a proto:Rule ; + rdfs:label "non-compliance-self-awareness-failure" ; + proto:enforcement "Agent should run 'make AGENTS.md' to refresh its protocol knowledge and re-evaluate its plan." ; + dcterms:description "Requires the agent to maintain an up-to-date understanding of protocols by recompiling AGENTS.md when necessary." . + + a proto:Rule ; + rdfs:label "non-compliance-test-procedure" ; + proto:enforcement "Agent must halt execution and run the required tests, debugging any failures before proceeding." ; + dcterms:description "Requires adherence to all documented testing procedures before submitting changes." . + + a proto:Rule ; + rdfs:label "l1-self-awareness" ; + proto:enforcement "The `start` command of the FDC toolchain executes this step and fails if the artifact is missing or invalid." ; + dcterms:description "Level 1 (Self-Awareness): The agent must first establish its own identity and inherent limitations by reading the `knowledge_core/agent_meta.json` artifact." . + + a proto:Rule ; + rdfs:label "l2-repository-sync" ; + proto:enforcement "The `start` command of the FDC toolchain executes this step." ; + dcterms:description "Level 2 (Repository Sync): The agent must understand the current state of the local repository by loading primary artifacts from the `knowledge_core/` directory." . + + a proto:Rule ; + rdfs:label "l3-environmental-probing" ; + proto:enforcement "The `start` command of the FDC toolchain executes this step, utilizing tools like `google_search` and `view_text_website`." ; + dcterms:description "Level 3 (Environmental Probing & Targeted RAG): The agent must discover the rules and constraints of its operational environment by executing a probe script and using targeted RAG to resolve 'known unknowns'." . + + a proto:Rule ; + rdfs:label "l4-deep-research-cycle" ; + proto:enforcement "This is a special case of recursion, explicitly allowed and managed by the FDC toolchain." ; + dcterms:description "Level 4 (Deep Research Cycle): To investigate 'unknown unknowns', the agent must initiate a formal, self-contained Finite Development Cycle (FDC) of the 'Analysis Modality'." . + + a proto:Rule ; + rdfs:label "registry-definition" ; + proto:enforcement "The file's existence and format can be checked by the validation toolchain." ; + dcterms:description "A central plan registry MUST exist at 'knowledge_core/plan_registry.json'. It maps logical plan names to their file paths." . + + a proto:Rule ; + rdfs:label "registry-first-resolution" ; + proto:enforcement "This logic must be implemented in both the plan validator (`fdc_cli.py`) and the execution engine (`master_control.py`)." ; + dcterms:description "The 'call_plan ' directive MUST first attempt to resolve '' as a logical name in the plan registry. If resolution fails, it MUST fall back to treating '' as a direct file path for backward compatibility." . + + a proto:Rule ; + rdfs:label "registry-management-tool" ; + proto:enforcement "The tool's existence and functionality can be verified via integration tests." ; + dcterms:description "A dedicated tool (`tooling/plan_manager.py`) MUST be provided for managing the plan registry, with functions to register, deregister, and list plans." . + + a proto:Rule ; + rdfs:label "execute-plllu-script" ; + proto:enforcement "The tool is used by invoking it from the command line with the path to the pLLLU script as an argument." ; + dcterms:description "The `plllu_runner.py` tool should be used to execute .plllu script files. This tool provides the bridge between the agent's master control loop and the pLLLU language interpreter." . + + a proto:Rule ; + rdfs:label "pre-commit-instructions-mandate" ; + proto:enforcement "The agent's core logic should invoke this tool as the entry point to the pre-submission phase." ; + dcterms:description "Before submitting changes, the agent MUST execute the `pre_commit_instructions` tool to receive the required sequence of validation steps (e.g., running tests, requesting code review)." . + + a proto:Rule ; + rdfs:label "executable-plans" ; + proto:enforcement "The output of the research planner must be linted and validated by the `fdc_cli.py` tool using the `research_fsm.json`." ; + dcterms:description "Research plans must be generated by `tooling/research_planner.py` as valid, executable plans that conform to the `research_fsm.json` definition. They are not just templates but formal, verifiable artifacts." . + + a proto:Rule ; + rdfs:label "l4-invocation" ; + proto:enforcement "The `master_control.py` orchestrator is responsible for triggering the L4 cycle." ; + dcterms:description "The L4 Deep Research Cycle is the designated mechanism for resolving complex 'unknown unknowns'. It is invoked by the main orchestrator when a task requires knowledge that cannot be obtained through simple L1-L3 orientation probes." . + + a proto:Rule ; + rdfs:label "specialized-fsm" ; + proto:enforcement "The `master_control.py` orchestrator must load and execute plans against this specific FSM when initiating an L4 Deep Research Cycle." ; + dcterms:description "The Research FDC must be governed by its own dedicated Finite State Machine, defined in `tooling/research_fsm.json`. This FSM is tailored for a research workflow, with states for gathering, synthesis, and reporting." . + + a proto:Rule ; + rdfs:label "mandate-research-tools" ; + proto:enforcement "Adherence is monitored by the Code Review Critic and through post-mortem analysis of the activity log." ; + dcterms:description "For all complex research tasks, the `plan_deep_research` tool MUST be used to generate a plan, and the `execute_research_protocol` tool MUST be used for data gathering. This ensures a systematic and auditable research process." . + + a proto:Rule ; + rdfs:label "no-reset-all" ; + proto:enforcement "This rule is enforced by the `master_control.py` orchestrator, which will immediately terminate the workflow with an error if an attempt is made to call this tool." ; + dcterms:description "The `reset_all` tool is strictly forbidden under all circumstances. It is a legacy tool that has been superseded by more granular and safer methods of workspace management. Its use is considered a critical failure." . + + a proto:Rule ; + rdfs:label "no-public-disclosure" ; + proto:enforcement "Violation of this rule may result in being banned from the project community." ; + dcterms:description "Vulnerabilities MUST NOT be disclosed publicly until a patch is available and has been distributed." . + + a proto:Rule ; + rdfs:label "vuln-reporting-channel" ; + proto:enforcement "This is a procedural rule. The designated contact is specified in the project's main SECURITY.md file." ; + dcterms:description "All suspected security vulnerabilities MUST be reported privately to the designated security contact." . + + a proto:Rule ; + rdfs:label "automated-orchestration" ; + proto:enforcement "This script is the designated engine for the PDSC workflow." ; + dcterms:description "The self-correction cycle must be managed by the `tooling/self_correction_orchestrator.py` script, which processes pending lessons and triggers the necessary updates." . + + a proto:Rule ; + rdfs:label "autonomous-code-suggestion" ; + proto:enforcement "The `tooling/self_correction_orchestrator.py` invokes the code suggester when it processes a lesson of this type." ; + dcterms:description "The self-correction system can generate and apply code changes to its own tooling. This is achieved through a `PROPOSE_CODE_CHANGE` action, which is processed by `tooling/code_suggester.py` to create an executable plan." . + + a proto:Rule ; + rdfs:label "programmatic-rule-refinement" ; + proto:enforcement "The `tooling/knowledge_compiler.py` can generate `update-rule` actions, and the `tooling/self_correction_orchestrator.py` executes them." ; + dcterms:description "The self-correction system can modify the description of existing protocol rules via the `update-rule` command in `tooling/protocol_updater.py`, allowing it to refine its own logic." . + + a proto:Rule ; + rdfs:label "programmatic-updates" ; + proto:enforcement "Agent's core logic should be designed to use this tool for all protocol modifications." ; + dcterms:description "All modifications to protocol source files must be performed programmatically via the `tooling/protocol_updater.py` tool to ensure consistency and prevent manual errors." . + + a proto:Rule ; + rdfs:label "structured-lessons" ; + proto:enforcement "The `tooling/knowledge_compiler.py` script is responsible for generating lessons in the correct format." ; + dcterms:description "Lessons learned from post-mortem analysis must be generated as structured, machine-readable JSON objects in `knowledge_core/lessons.jsonl`." . + + a proto:Rule ; + rdfs:label "rebuild-after-modification" ; + proto:enforcement "The agent's plan for modifying protocols must include a final step to run the build script. This can be verified by reviewing the execution log." ; + dcterms:description "After modifying any '.protocol.json' source file, the agent MUST execute the main build script 'tooling/hierarchical_compiler.py' to regenerate all 'AGENTS.md' artifacts and the 'protocols.ttl' knowledge graph." . + + a proto:Rule ; + rdfs:label "source-only-modification" ; + proto:enforcement "Procedural rule. The agent must demonstrate awareness of this by using tools like 'replace_with_git_merge_diff' or 'create_file_with_block' on source files, not build artifacts." ; + dcterms:description "The agent MUST NOT edit any 'AGENTS.md' file directly. All modifications to protocols must be made to the '.protocol.json' source files within the 'protocols/' directories." . + + a proto:Rule ; + rdfs:label "test-driven-protocol-development" ; + proto:enforcement "This is a best-practice guideline. Adherence can be checked during code review by observing the agent's workflow." ; + dcterms:description "When adding or significantly altering a protocol, the agent SHOULD, where practical, create a temporary, illustrative test case (e.g., a deliberately invalid file) to prove the change has the intended effect and that the build system's error handling is robust." . + + a proto:Rule ; + rdfs:label "validation-is-mandatory" ; + proto:enforcement "The `hierarchical_compiler.py` script's successful execution serves as the enforcement mechanism." ; + dcterms:description "Any new or modified protocol source file MUST be successfully validated against the 'protocols/protocol.schema.json'. The build process, which includes this validation, must complete without errors." . + + a proto:Rule ; + rdfs:label "formal-proposal-required" ; + proto:enforcement "The initial plan for any speculative task must include a step to generate and save a proposal artifact." ; + dcterms:description "A speculative task must begin with the creation of a formal proposal document, outlining the objective, rationale, and plan." . + + a proto:Rule ; + rdfs:label "idle-state-trigger" ; + proto:enforcement "The agent's main control loop must verify an idle state before allowing the invocation of a speculative plan." ; + dcterms:description "The agent may only initiate a speculative task when it has no active, user-assigned tasks." . + + a proto:Rule ; + rdfs:label "resource-constraints" ; + proto:enforcement "This is a system-level constraint that the agent orchestrator must enforce." ; + dcterms:description "Speculative tasks must operate under defined resource limits." . + + a proto:Rule ; + rdfs:label "speculative-logging" ; + proto:enforcement "The agent's logging and file-creation tools should be context-aware and apply this tag when in a speculative mode." ; + dcterms:description "All logs and artifacts generated during a speculative task must be tagged as 'speculative'." . + + a proto:Rule ; + rdfs:label "user-review-gate" ; + proto:enforcement "The agent is forbidden from using tools like 'submit' or 'merge' within a speculative context. It must use 'request_user_input' to present the results." ; + dcterms:description "Final artifacts from a speculative task must be submitted for user review and cannot be merged directly." . + + a proto:Rule ; + rdfs:label "aorp-mandate" ; + proto:enforcement "Enforced by the agent's core operational loop and the `start` command in `tooling/fdc_cli.py`." ; + dcterms:description "All Finite Development Cycles (FDCs) MUST be initiated using the FDC toolchain's 'start' command. This is non-negotiable." . + + a proto:Rule ; + rdfs:label "fdc-toolchain-mandate" ; + proto:enforcement "The agent's internal logic is designed to prefer these specific tool commands for FDC state transitions." ; + dcterms:description "Use the `fdc_cli.py` tool for all core FDC state transitions: task initiation ('start'), plan linting ('lint'), and task closure ('close')." . + + a proto:Rule ; + rdfs:label "rag-mandate" ; + proto:enforcement "This is a core principle of the L3 orientation phase, utilizing tools like `google_search`." ; + dcterms:description "For any task involving external technologies, Just-In-Time External RAG is REQUIRED to verify current best practices. Do not trust internal knowledge." . + + a proto:Rule ; + rdfs:label "toolchain-audit-on-schema-change" ; + proto:enforcement "This is a procedural rule for any agent developing the protocol system. Adherence can be partially checked by post-commit hooks or review processes that look for a tooling audit in any change that modifies the specified core files." ; + dcterms:description "If a change is made to the core protocol schema (`protocol.schema.json`) or to the compilers that process it (`protocol_compiler.py`, `hierarchical_compiler.py`), a formal audit of the entire `tooling/` directory MUST be performed as a subsequent step. This audit should verify that all tools are compatible with the new protocol structure." . + + a proto:Rule ; + rdfs:label "run-all-audits" ; + proto:enforcement "The tool is invoked via the command line, typically through the `make audit` target." ; + dcterms:description "The `auditor.py` script should be used to run comprehensive checks on the repository's health. It can be run with 'all' to check protocols, plans, and documentation completeness." . + + a proto:Rule ; + rdfs:label "use-doc-builder-for-all-docs" ; + proto:enforcement "The tool is invoked via the command line, typically through the `make docs`, `make readme`, or `make pages` targets." ; + dcterms:description "The `doc_builder.py` script is the single entry point for generating all user-facing documentation, including system-level docs, README files, and GitHub Pages. It should be called with the appropriate '--format' argument." . diff --git a/protocols/AGENTS.md b/protocols/AGENTS.md deleted file mode 100644 index b7a1fcd7..00000000 --- a/protocols/AGENTS.md +++ /dev/null @@ -1,74 +0,0 @@ -# --- -# DO NOT EDIT THIS FILE DIRECTLY. -# This file is programmatically generated by the `protocol_compiler.py` script. -# All changes to agent protocols must be made in the source files -# located in the `protocols/` directory. -# -# This file contains the compiled protocols in a human-readable Markdown format, -# with machine-readable JSON definitions embedded. -# --- - -# Agent Charter & Operational Principles - -## 1. Agent Identity and Purpose - -This repository is designed for development by an advanced AI software engineering assistant. - -**Identity:** The primary agent interacting with this repository is a large language model-based coding assistant developed by Google. It operates externally and interacts with the codebase via a secure GitHub application. It is not a resident entity within the repository, and any documentation referring to a specific persona (e.g., "Jules") is legacy and should be disregarded. - -**Purpose:** The agent's purpose is to assist in software development tasks, including but not limited to: -* Implementing new features. -* Fixing bugs. -* Refactoring code. -* Improving documentation. -* Analyzing and improving the repository's architecture and protocols. - -The agent is expected to operate autonomously, using the tools and information provided within this repository to complete its tasks. - -## 2. Core Operational Principles - -This repository is architected to facilitate effective human-AI collaboration. The following principles are fundamental to the agent's operation. - -### 2.1. Protocol-Driven Operation - -The agent's behavior is governed by a set of formal, machine-readable protocols. These are defined in the `protocols/` directory and compiled into the `AGENTS.md` file. The agent **must** adhere to these protocols at all times. They are not guidelines; they are the rules of the system. - -### 2.2. The Knowledge Core as the Source of Truth - -The agent's ability to reason effectively about the codebase is augmented by a dedicated `knowledge_core/` directory. This directory contains a set of machine-readable artifacts that provide a structured, up-to-date representation of the repository's state. - -* **`dependency_graph.json`**: An explicit map of all dependencies within the repository. The agent must use this artifact for impact analysis. -* **`symbols.json`**: A universal map of all code symbols (functions, classes, etc.). The agent must use this for precise code navigation and retrieval. -* **`asts/`**: A collection of Abstract Syntax Trees for source files. The agent must use these for deep structural analysis and code manipulation. -* **`llms.txt`**: A curated corpus of high-level documentation and project rationale. -* **`temporal_orientation.md`**: A summary of the current state of external technologies to combat knowledge cutoff. - -The agent **must** prioritize using these artifacts over attempting to infer information from unstructured source code. - -### 2.3. Structured Logging for Learning - -All agent actions must be logged to `logs/activity.log.jsonl` in a structured format defined by `LOGGING_SCHEMA.md`. This is not just for debugging. These logs form a high-quality dataset of the agent's reasoning and actions, which is essential for analyzing performance and enabling long-term learning and self-improvement. - -### 2.4. Continuous Self-Improvement - -The agent is not only a user of this system but also a contributor to its evolution. The agent is empowered to: -* Identify flaws or inefficiencies in the existing protocols. -* Propose improvements to the protocols or the tools in the `tooling/` directory. -* Implement and validate these improvements. - -This self-improvement loop is a core objective of this project. - -## 3. Interaction Model - -The agent's interaction with the repository follows a clear cycle: -1. **Task Ingestion:** Receive a task from a user. -2. **Contextualization:** Use the Knowledge Core and external search tools to build a comprehensive understanding of the task. -3. **Planning:** Generate a detailed, step-by-step plan. -4. **Execution:** Execute the plan, using the available tools and logging every action. -5. **Verification:** Verify the successful completion of the task. -6. **Post-Mortem:** Analyze the execution to identify lessons learned. -7. **Submission:** Submit the completed work for review. - -This structured process ensures that the agent's work is predictable, verifiable, and aligned with the project's goals. - ---- diff --git a/protocols/core/AGENTS.md b/protocols/core/AGENTS.md deleted file mode 100644 index a0e4345d..00000000 --- a/protocols/core/AGENTS.md +++ /dev/null @@ -1,14571 +0,0 @@ -# --- -# DO NOT EDIT THIS FILE DIRECTLY. -# This file is programmatically generated by the `protocol_compiler.py` script. -# All changes to agent protocols must be made in the source files -# located in the `core/` directory. -# -# This file contains the compiled protocols in a human-readable Markdown format, -# with machine-readable JSON definitions embedded. -# --- - -# Protocol: Agent Shell Entry Point - -This protocol establishes the `agent_shell.py` script as the sole, official entry point for initiating any and all agent tasks. - -## The Problem: Inconsistent Initialization - -Prior to this protocol, there was no formally mandated entry point for the agent. This could lead to tasks being initiated through different scripts, potentially bypassing critical setup procedures like FSM initialization, logger configuration, and state management. This inconsistency makes the agent's behavior less predictable and harder to debug. - -## The Solution: A Single, Enforced Entry Point - -This protocol mandates the use of `tooling/agent_shell.py` for all task initiations. - -**Rule `shell-is-primary-entry-point`**: All agent tasks must be initiated through the `agent_shell.py` script. - -This ensures that every task begins within a controlled, programmatic environment where: -1. The MasterControlGraph FSM is correctly instantiated and run. -2. The centralized logger is initialized for comprehensive, structured logging. -3. The agent's lifecycle is managed programmatically, not through fragile file-based signals. - -By enforcing a single entry point, this protocol enhances the reliability, auditability, and robustness of the entire agent system. - ---- - -# Meta-Protocol: Toolchain Review on Schema Change - -This protocol establishes a critical feedback loop to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols. - -## The Problem: Protocol-Toolchain Desynchronization - -A significant process gap was identified where a major architectural change to the protocol system (e.g., the introduction of a hierarchical `AGENTS.md` structure) did not automatically trigger a review of the tools that depend on that structure. The `protocol_auditor.py` tool, for instance, became partially obsolete as it was unaware of the new hierarchical model, leading to incomplete audits. This demonstrates that the agent's tools can become desynchronized from its own governing rules, creating a critical blind spot. - -## The Solution: Mandated Toolchain Audit - -This protocol closes that gap by introducing a new rule that explicitly links changes in the protocol system's architecture to a mandatory review of the toolchain. - -**Rule `toolchain-audit-on-schema-change`**: If a change is made to the core protocol schema (`protocol.schema.json`) or to the compilers that process it (`protocol_compiler.py`, `hierarchical_compiler.py`), a formal audit of the entire `tooling/` directory **must** be performed as a subsequent step. - -This ensures that any modification to the fundamental way protocols are defined or processed is immediately followed by a conscious verification that all dependent tools are still functioning correctly and are aware of the new structure. This transforms the previously manual and error-prone discovery process into a formal, required step of the development lifecycle. - ---- - -# --- Child Module: `core` --- - -# Protocol: The Context-Free Development Cycle (CFDC) - -This protocol marks a significant evolution from the Finite Development Cycle (FDC), introducing a hierarchical planning model that enables far greater complexity and modularity while preserving the system's core guarantee of decidability. - -## From FSM to Pushdown Automaton - -The FDC was based on a Finite State Machine (FSM), which provided a strict, linear sequence of operations. While robust, this model was fundamentally limited: it could not handle nested tasks or sub-routines, forcing all plans to be monolithic. - -The CFDC upgrades our execution model to a **Pushdown Automaton**. This is achieved by introducing a **plan execution stack**, which allows the system to call other plans as sub-routines. This enables a powerful new paradigm: **Context-Free Development Cycles**. - -## The `call_plan` Directive - -The core of the CFDC is the new `call_plan` directive. This allows one plan to execute another, effectively creating a parent-child relationship between them. - -- **Usage:** `call_plan ` -- **Function:** When the execution engine encounters this directive, it: - 1. Pushes the current plan's state (e.g., the current step number) onto the execution stack. - 2. Begins executing the sub-plan specified in the path. - 3. Once the sub-plan completes, it pops the parent plan's state from the stack and resumes its execution from where it left off. - -## Ensuring Decidability: The Recursion Depth Limit - -A system with unbounded recursion is not guaranteed to terminate. To prevent this, the CFDC introduces a non-negotiable, system-wide limit on the depth of the plan execution stack. - -**Rule `max-recursion-depth`**: The execution engine MUST enforce a maximum recursion depth, defined by a `MAX_RECURSION_DEPTH` constant. If a `call_plan` directive would cause the stack depth to exceed this limit, the entire process MUST terminate with an error. This hard limit ensures that even with recursive or deeply nested plans, the system remains a **decidable**, non-Turing-complete process that is guaranteed to halt. - ---- - -# Protocol: The Plan Registry - -This protocol introduces a Plan Registry to create a more robust, modular, and discoverable system for hierarchical plans. It decouples the act of calling a plan from its physical file path, allowing plans to be referenced by a logical name. - -## The Problem with Path-Based Calls - -The initial implementation of the Context-Free Development Cycle (CFDC) relied on direct file paths (e.g., `call_plan path/to/plan.txt`). This is brittle: -- If a registered plan is moved or renamed, all plans that call it will break. -- It is difficult for an agent to discover and reuse existing, validated plans. - -## The Solution: A Central Registry - -The Plan Registry solves this by creating a single source of truth that maps logical, human-readable plan names to their corresponding file paths. - -- **Location:** `knowledge_core/plan_registry.json` -- **Format:** A simple JSON object of key-value pairs: - ```json - { - "logical-name-1": "path/to/plan_1.txt", - "run-all-tests": "plans/common/run_tests.txt" - } - ``` - -## Updated `call_plan` Logic - -The `call_plan` directive is now significantly more powerful. When executing `call_plan `, the system will follow a **registry-first** approach: - -1. **Registry Lookup:** The system will first treat `` as a logical name and look it up in `knowledge_core/plan_registry.json`. -2. **Path Fallback:** If the name is not found in the registry, the system will fall back to treating `` as a direct file path. This ensures full backward compatibility with existing plans. - -## Management - -A new tool, `tooling/plan_manager.py`, will be introduced to manage the registry with simple commands like `register`, `deregister`, and `list`, making it easy to maintain the library of reusable plans. - ---- - -# Protocol: The Closed-Loop Self-Correction Cycle - -This protocol describes the automated workflow that enables the agent to programmatically improve its own governing protocols based on new knowledge. It transforms the ad-hoc, manual process of learning into a reliable, machine-driven feedback loop. - -## The Problem: The Open Loop - -Previously, "lessons learned" were compiled into a simple markdown file, `knowledge_core/lessons_learned.md`. While this captured knowledge, it was a dead end. There was no automated process to translate these text-based insights into actual changes to the protocol source files. This required manual intervention, creating a significant bottleneck and a high risk of protocols becoming stale. - -## The Solution: A Protocol-Driven Self-Correction (PDSC) Workflow - -The PDSC workflow closes the feedback loop by introducing a set of new tools and structured data formats that allow the agent to enact its own improvements. - -**1. Structured, Actionable Lessons (`knowledge_core/lessons.jsonl`):** -- Post-mortem analysis now generates lessons as structured JSON objects, not free-form text. -- Each lesson includes a machine-readable `action` field, which contains a specific, executable command. - -**2. The Protocol Updater (`tooling/protocol_updater.py`):** -- A new, dedicated tool for programmatically modifying the protocol source files (`*.protocol.json`). -- It accepts commands like `add-tool`, allowing for precise, automated changes to protocol definitions. - -**3. The Orchestrator (`tooling/self_correction_orchestrator.py`):** -- This script is the engine of the cycle. It reads `lessons.jsonl`, identifies pending lessons, and uses the `protocol_updater.py` to execute the defined actions. -- After applying a lesson, it updates the lesson's status, creating a clear audit trail. -- It finishes by running `make AGENTS.md` to ensure the changes are compiled into the live protocol. - -This new, automated cycle—**Analyze -> Structure Lesson -> Execute Correction -> Re-compile Protocol**—is a fundamental step towards autonomous self-improvement. - ---- - -# Protocol: Deep Research Cycle - -This protocol defines a standardized, multi-step plan for conducting in-depth research on a complex topic. It is designed to be a reusable, callable plan that ensures a systematic and thorough investigation. - -The cycle consists of five main phases: -1. **Review Scanned Documents:** The agent first reviews the content of documents found in the repository during the initial scan. This provides immediate, project-specific context. -2. **Initial Scoping & Keyword Generation:** Based on the initial topic and the information from scanned documents, the agent generates a set of search keywords. -3. **Broad Information Gathering:** The agent uses the keywords to perform broad web searches and collect a list of relevant URLs. -4. **Targeted Information Extraction:** The agent visits the most promising URLs to extract detailed information. -5. **Synthesis & Summary:** The agent synthesizes the gathered information into a coherent summary, which is saved to a research report file. - -This structured approach ensures that research is not ad-hoc but is instead a repeatable and verifiable process. - ---- - -# Protocol: The Formal Research Cycle (L4) - -This protocol establishes the L4 Deep Research Cycle, a specialized, self-contained Finite Development Cycle (FDC) designed for comprehensive knowledge acquisition. It elevates research from a simple tool-based action to a formal, verifiable process. - -## The Problem: Ad-Hoc Research - -Previously, research was an unstructured activity. The agent could use tools like `google_search` or `read_file`, but there was no formal process for planning, executing, and synthesizing complex research tasks. This made it difficult to tackle "unknown unknowns" in a reliable and auditable way. - -## The Solution: A Dedicated Research FDC - -The L4 Research Cycle solves this by introducing a new, specialized Finite State Machine (FSM) tailored specifically for research. When the main orchestrator (`master_control.py`) determines that a task requires deep knowledge, it initiates this cycle. - -### Key Features: - -1. **Specialized FSM (`tooling/research_fsm.json`):** Unlike the generic development FSM, the research FSM has states that reflect a true research workflow: `GATHERING`, `SYNTHESIZING`, and `REPORTING`. This provides a more accurate model for the task. -2. **Executable Plans:** The `tooling/research_planner.py` is upgraded to generate formal, executable plans that are validated against the new research FSM. These are no longer just templates but are verifiable artifacts that guide the agent through the research process. -3. **Formal Invocation:** The L4 cycle is a first-class citizen in the agent's architecture. The main orchestrator can formally invoke it, execute the research plan, and then integrate the resulting knowledge back into its main task. - -This new protocol provides a robust, reliable, and formally verifiable mechanism for the agent to explore complex topics, making it significantly more autonomous and capable. - ---- - - ---- - -# Protocol: The Context-Sensitive Development Cycle (CSDC) - -This protocol introduces a new form of development cycle that is sensitive to the logical context in which it operates. It moves beyond the purely structural validation of the FDC and CFDC to incorporate constraints based on fundamental principles of logic and computability. - -The CSDC is founded on the idea of exploring the trade-offs between expressive power and the risk of self-referential paradoxes. It achieves this by defining two mutually exclusive development models. - -## Model A: The Introspective Model - -- **Permits:** `define_set_of_names` -- **Forbids:** `define_diagonalization_function` - -This model allows the system to have a complete map of its own language, enabling powerful introspection and metaprogramming. However, it explicitly forbids the diagonalization function, a common source of paradoxes in self-referential systems. This can be seen as a Gödel-like approach. - -## Model B: The Self-Referential Model - -- **Permits:** `define_diagonalization_function` -- **Forbids:** `define_set_of_names` - -This model allows the system to define and use the diagonalization function, enabling direct self-reference. However, it prevents the system from having a complete name-map of its own expressions, which is another way to avoid paradox (related to Tarski's undefinability theorem). - -## Complexity Classes - -Both models can be further constrained by computational complexity: -- **Polynomial (P):** For plans that are considered computationally tractable. -- **Exponential (EXP):** For plans that may require significantly more resources, allowing for more complex but potentially less efficient solutions. - -## The `csdc_cli.py` Tool - -The CSDC is enforced by the `tooling/csdc_cli.py` tool. This tool validates a plan against a specified model and complexity class, ensuring that all constraints are met before execution. - ---- - -# Protocol: pLLLU Execution - -This protocol establishes the `plllu_runner.py` script as the official entry point for executing pLLLU (`.plllu`) files. - -## The Problem: Lack of a Standard Runner - -The pLLLU language provides a powerful way to define complex logic, but without a standardized execution tool, there is no reliable way to integrate these files into the agent's workflow. - -## The Solution: A Dedicated Runner - -This protocol mandates the use of `tooling/plllu_runner.py` for all pLLLU file executions. - -**Rule `plllu-runner-is-entry-point`**: All pLLLU files must be executed through the `plllu_runner.py` script. - -This ensures that every pLLLU file is executed in a controlled, programmatic environment. - ---- - -# Protocol: Speculative Execution - -This protocol empowers the agent to engage in creative and exploratory tasks when it is otherwise idle. It provides a formal framework for the agent to generate novel ideas, plans, or artifacts that are not direct responses to a user request, but are instead products of its own "imagination" and analysis of the repository. - -The goal is to enable proactive, creative problem-solving and self-improvement, allowing the agent to "dream" productively within safe and well-defined boundaries. - -## Rules - -- **`idle-state-trigger`**: The Speculative Execution Protocol can only be invoked when the agent has no active, user-assigned task. This ensures that speculative work never interferes with primary duties. -- **`formal-proposal-required`**: The first action in any speculative task must be the creation of a formal proposal document. This document must outline the objective, rationale, and a detailed plan for the task. -- **`resource-constraints`**: All speculative tasks must operate under predefined resource constraints (e.g., time limits, computational resources) to prevent runaway processes. -- **`user-review-gate`**: The final output or artifact of a speculative task cannot be integrated or submitted directly. It must be presented to the user for formal review and approval. -- **`speculative-logging`**: All logs, artifacts, and actions generated during a speculative task must be clearly tagged with a `speculative` flag to distinguish them from standard, user-directed work. - ---- - -```json -{ - "protocol_id": "agent-shell-001", - "description": "A protocol governing the use of the interactive agent shell as the primary entry point for all tasks.", - "rules": [ - { - "rule_id": "shell-is-primary-entry-point", - "description": "All agent tasks must be initiated through the `agent_shell.py` script. This script is the designated, API-driven entry point that ensures proper initialization of the MasterControlGraph FSM, centralized logging, and programmatic lifecycle management. Direct execution of other tools or scripts is forbidden for task initiation.", - "enforcement": "This is a procedural rule. The agent's operational framework should only expose the agent_shell.py as the means of starting a new task." - } - ], - "associated_tools": [ - "tooling/agent_shell.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "toolchain-review-on-schema-change-001", - "description": "A meta-protocol to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols.", - "rules": [ - { - "rule_id": "toolchain-audit-on-schema-change", - "description": "If a change is made to the core protocol schema (`protocol.schema.json`) or to the compilers that process it (`protocol_compiler.py`, `hierarchical_compiler.py`), a formal audit of the entire `tooling/` directory MUST be performed as a subsequent step. This audit should verify that all tools are compatible with the new protocol structure.", - "enforcement": "This is a procedural rule for any agent developing the protocol system. Adherence can be partially checked by post-commit hooks or review processes that look for a tooling audit in any change that modifies the specified core files." - } - ], - "associated_tools": [ - "tooling/protocol_auditor.py", - "tooling/protocol_compiler.py", - "tooling/hierarchical_compiler.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "unified-auditor-001", - "description": "A protocol for the unified repository auditing tool, which combines multiple health and compliance checks into a single interface.", - "rules": [ - { - "rule_id": "run-all-audits", - "description": "The `auditor.py` script should be used to run comprehensive checks on the repository's health. It can be run with 'all' to check protocols, plans, and documentation completeness.", - "enforcement": "The tool is invoked via the command line, typically through the `make audit` target." - } - ], - "associated_tools": [ - "tooling/auditor.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "aura-execution-001", - "description": "A protocol for executing Aura scripts, enabling a more expressive and powerful planning and automation language for the agent.", - "rules": [ - { - "rule_id": "execute-aura-script", - "description": "The `aura_executor.py` tool should be used to execute .aura script files. This tool provides the bridge between the agent's master control loop and the Aura language interpreter.", - "enforcement": "The tool is used by invoking it from the command line with the path to the Aura script as an argument." - } - ], - "associated_tools": [ - "tooling/aura_executor.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "capability-verification-001", - "description": "A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement.", - "rules": [ - { - "rule_id": "verify-capability-acquisition", - "description": "The `capability_verifier.py` tool should be used to test the agent's ability to acquire a new capability defined by a failing test file. The tool orchestrates the failure, self-correction, and verification process.", - "enforcement": "The tool is used by invoking it from the command line with the path to the target test file." - } - ], - "associated_tools": [ - "tooling/capability_verifier.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "csdc-001", - "description": "A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints.", - "rules": [ - { - "rule_id": "use-csdc-cli", - "description": "The `csdc_cli.py` tool must be used to validate plans under the CSDC. This tool enforces model-specific constraints (A or B) and complexity requirements (P or EXP).", - "enforcement": "The tool is used by invoking it from the command line with the plan file, model, and complexity as arguments." - }, - { - "rule_id": "model-a-constraints", - "description": "Model A permits `define_set_of_names` but forbids `define_diagonalization_function`.", - "enforcement": "Enforced by the `fsm_model_a.json` FSM used by the `csdc_cli.py` tool." - }, - { - "rule_id": "model-b-constraints", - "description": "Model B permits `define_diagonalization_function` but forbids `define_set_of_names`.", - "enforcement": "Enforced by the `fsm_model_b.json` FSM used by the `csdc_cli.py` tool." - } - ], - "associated_tools": [ - "tooling/csdc_cli.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "unified-doc-builder-001", - "description": "A protocol for the unified documentation builder, which generates various documentation artifacts from the repository's sources of truth.", - "rules": [ - { - "rule_id": "use-doc-builder-for-all-docs", - "description": "The `doc_builder.py` script is the single entry point for generating all user-facing documentation, including system-level docs, README files, and GitHub Pages. It should be called with the appropriate '--format' argument.", - "enforcement": "The tool is invoked via the command line, typically through the `make docs`, `make readme`, or `make pages` targets." - } - ], - "associated_tools": [ - "tooling/doc_builder.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "file-indexing-001", - "description": "A protocol for maintaining an up-to-date file index to accelerate tool performance.", - "rules": [ - { - "rule_id": "update-index-before-submit", - "description": "Before submitting any changes that alter the file structure (create, delete, rename), the agent MUST rebuild the repository's file index. This ensures that tools relying on the index, such as the FDC validator, have an accurate view of the filesystem.", - "enforcement": "This is a procedural rule. The agent's pre-submission checklist should include a step to run 'python tooling/file_indexer.py build'." - } - ], - "associated_tools": [ - "tooling/file_indexer.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "hdl-proving-001", - "description": "A protocol for interacting with the Hypersequent-calculus-based logic engine, allowing the agent to perform formal logical proofs.", - "rules": [ - { - "rule_id": "prove-sequent", - "description": "The `hdl_prover.py` tool should be used to check the provability of a logical sequent. This tool acts as a wrapper for the underlying Lisp-based prover.", - "enforcement": "The tool is used by invoking it from the command line with the sequent to be proved as an argument." - } - ], - "associated_tools": [ - "tooling/hdl_prover.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "agent-interaction-001", - "description": "A protocol governing the agent's core interaction and planning tools.", - "rules": [ - { - "rule_id": "planning-tool-access", - "description": "The agent is authorized to use the `set_plan` tool to create and update its execution plan. This is a foundational capability for task execution.", - "enforcement": "The agent's core logic should be designed to use this tool for all planning activities." - }, - { - "rule_id": "communication-tool-access", - "description": "The agent is authorized to use the `message_user` tool to communicate with the user, providing updates and asking for clarification. This is essential for a collaborative workflow.", - "enforcement": "The agent's core logic should be designed to use this tool for all user-facing communication." - } - ], - "associated_tools": [ - "set_plan", - "message_user" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "plllu-execution-001", - "description": "A protocol for executing pLLLU scripts, enabling a more expressive and powerful planning and automation language for the agent.", - "rules": [ - { - "rule_id": "execute-plllu-script", - "description": "The `plllu_runner.py` tool should be used to execute .plllu script files. This tool provides the bridge between the agent's master control loop and the pLLLU language interpreter.", - "enforcement": "The tool is used by invoking it from the command line with the path to the pLLLU script as an argument." - } - ], - "associated_tools": [ - "tooling/plllu_runner.py" - ] -} -``` - - ---- - -```json -{ - "protocol_id": "speculative-execution-001", - "description": "A protocol that governs the agent's ability to initiate and execute self-generated, creative, or exploratory tasks during idle periods.", - "rules": [ - { - "rule_id": "idle-state-trigger", - "description": "The agent may only initiate a speculative task when it has no active, user-assigned tasks.", - "enforcement": "The agent's main control loop must verify an idle state before allowing the invocation of a speculative plan." - }, - { - "rule_id": "formal-proposal-required", - "description": "A speculative task must begin with the creation of a formal proposal document, outlining the objective, rationale, and plan.", - "enforcement": "The initial plan for any speculative task must include a step to generate and save a proposal artifact." - }, - { - "rule_id": "resource-constraints", - "description": "Speculative tasks must operate under defined resource limits.", - "enforcement": "This is a system-level constraint that the agent orchestrator must enforce." - }, - { - "rule_id": "user-review-gate", - "description": "Final artifacts from a speculative task must be submitted for user review and cannot be merged directly.", - "enforcement": "The agent is forbidden from using tools like 'submit' or 'merge' within a speculative context. It must use 'request_user_input' to present the results." - }, - { - "rule_id": "speculative-logging", - "description": "All logs and artifacts generated during a speculative task must be tagged as 'speculative'.", - "enforcement": "The agent's logging and file-creation tools should be context-aware and apply this tag when in a speculative mode." - } - ], - "associated_tools": [ - "set_plan", - "create_file_with_block", - "request_user_input" - ] -} -``` - - ---- - - - -# --- Associated Tool Documentation --- - -# Module Documentation - -## Overview - -This document provides a human-readable summary of the protocols and key components defined within this module. It is automatically generated. - -## Core Protocols - -- **`dependency-management-001`**: A protocol for ensuring a reliable execution environment through formal dependency management. -- **`experimental-prologue-001`**: An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation. -- **`agent-shell-001`**: A protocol governing the use of the interactive agent shell as the primary entry point for all tasks. -- **`toolchain-review-on-schema-change-001`**: A meta-protocol to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols. -- **`unified-auditor-001`**: A protocol for the unified repository auditing tool, which combines multiple health and compliance checks into a single interface. -- **`aura-execution-001`**: A protocol for executing Aura scripts, enabling a more expressive and powerful planning and automation language for the agent. -- **`capability-verification-001`**: A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement. -- **`csdc-001`**: A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints. -- **`unified-doc-builder-001`**: A protocol for the unified documentation builder, which generates various documentation artifacts from the repository's sources of truth. -- **`file-indexing-001`**: A protocol for maintaining an up-to-date file index to accelerate tool performance. -- **`hdl-proving-001`**: A protocol for interacting with the Hypersequent-calculus-based logic engine, allowing the agent to perform formal logical proofs. -- **`agent-interaction-001`**: A protocol governing the agent's core interaction and planning tools. -- **`plllu-execution-001`**: A protocol for executing pLLLU scripts, enabling a more expressive and powerful planning and automation language for the agent. -- **`security-header`**: Defines the identity and purpose of the Security Protocol document. -- **`security-vuln-reporting-001`**: Defines the official policy and procedure for reporting security vulnerabilities. -- **`speculative-execution-001`**: A protocol that governs the agent's ability to initiate and execute self-generated, creative, or exploratory tasks during idle periods. - -## Key Components - -- **`tooling/__init__.py`**: - - > This module contains the various tools and utilities that support the agent's - > development, testing, and operational workflows. - > - > The tools in this package are the building blocks of the agent's capabilities, - > ranging from code analysis and refactoring to protocol compilation and - > self-correction. Each script is designed to be a self-contained unit of - > functionality that can be invoked either from the command line or programmatically - > by the agent's master control system. - > - > This __init__.py file marks the 'tooling' directory as a Python package, - > allowing for the organized import of its various modules. - -- **`tooling/agent_shell.py`**: - - > The new, interactive, API-driven entry point for the agent. - > - > This script replaces the old file-based signaling system with a direct, - > programmatic interface to the MasterControlGraph FSM. It is responsible for: - > 1. Initializing the agent's state and a centralized logger. - > 2. Instantiating and running the MasterControlGraph. - > 3. Driving the FSM by calling its methods and passing data and the logger. - > 4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - > and respond to requests for action. - -- **`tooling/__init__.py`**: - - > _No module-level docstring found._ - -- **`tooling/generate_and_test.py`**: - - > _No module-level docstring found._ - -- **`tooling/appl_runner.py`**: - - > A command-line tool for executing APPL files. - > - > This script provides a simple interface to run APPL files using the main - > `run.py` interpreter. It captures and prints the output of the execution, - > and provides detailed error reporting if the execution fails. - -- **`tooling/appl_to_lfi_ill.py`**: - - > A compiler that translates APPL (a simple functional language) to LFI-ILL. - > - > This script takes a Python file containing an APPL AST, and compiles it into - > an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - -- **`tooling/auditor.py`**: - - > A unified auditing tool for maintaining repository health and compliance. - > - > This script combines the functionality of several disparate auditing tools into a - > single, comprehensive command-line interface. It serves as the central tool for - > validating the key components of the agent's architecture, including protocols, - > plans, and documentation. - > - > The auditor can perform the following checks: - > 1. **Protocol Audit (`protocol`):** - > - Checks if `AGENTS.md` artifacts are stale compared to their source files. - > - Verifies protocol completeness by comparing tools used in logs against - > tools defined in protocols. - > - Analyzes tool usage frequency (centrality). - > 2. **Plan Registry Audit (`plans`):** - > - Scans `knowledge_core/plan_registry.json` for "dead links" where the - > target plan file does not exist. - > 3. **Documentation Audit (`docs`):** - > - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - > that are missing module-level docstrings. - > - > The tool is designed to be run from the command line and can execute specific - > audits or all of them, generating a consolidated `audit_report.md` file. - -- **`tooling/aura_executor.py`**: - - > This script serves as the command-line executor for `.aura` files. - > - > It bridges the gap between the high-level Aura scripting language and the - > agent's underlying Python-based toolset. The executor is responsible for: - > 1. Parsing the `.aura` source code using the lexer and parser from the - > `aura_lang` package. - > 2. Setting up an execution environment for the interpreter. - > 3. Injecting a "tool-calling" capability into the Aura environment, which - > allows Aura scripts to dynamically invoke registered Python tools - > (e.g., `hdl_prover`, `environmental_probe`). - > 4. Executing the parsed program and printing the final result. - > - > This makes it a key component for enabling more expressive and complex - > automation scripts for the agent. - -- **`tooling/aura_to_lfi_ill.py`**: - - > A compiler that translates AURA code to LFI-ILL. - > - > This script takes an AURA file, parses it, and compiles it into an LFI-ILL - > AST. The resulting AST is then written to a `.lfi_ill` file. - -- **`tooling/background_researcher.py`**: - - > This script performs a simulated research task in the background. - > It takes a task ID as a command-line argument and writes its findings - > to a temporary file that the main agent can poll. - -- **`tooling/builder.py`**: - - > A unified, configuration-driven build script for the project. - > - > This script serves as the central entry point for all build-related tasks, such - > as generating documentation, compiling protocols, and running code quality checks. - > It replaces a traditional Makefile's direct command execution with a more - > structured, maintainable, and introspectable approach. - > - > The core logic is driven by a `build_config.json` file, which defines a series - > of "targets." Each target specifies: - > - The `type` of target: "compiler" or "command". - > - For "compiler" types: `compiler` script, `output`, `sources`, and `options`. - > - For "command" types: the `command` to execute. - > - > The configuration also defines "build_groups", which are ordered collections of - > targets (e.g., "all", "quality"). - > - > This centralized builder provides several advantages: - > - **Single Source of Truth:** The `build_config.json` file is the definitive - > source for all build logic. - > - **Consistency:** Ensures all build tasks are executed in a uniform way. - > - **Extensibility:** New build targets can be added by simply updating the - > configuration file. - > - **Discoverability:** The script can list all available targets and groups. - -- **`tooling/capability_verifier.py`**: - - > A tool to verify that the agent can monotonically improve its capabilities. - > - > This script is designed to provide a formal, automated test for the agent's - > self-correction and learning mechanisms. It ensures that when the agent learns - > a new capability, it does so without losing (regressing) any of its existing - > capabilities. This is a critical safeguard for ensuring robust and reliable - > agent evolution. - > - > The tool works by orchestrating a four-step process: - > 1. **Confirm Initial Failure:** It runs a specific test file that is known to - > fail, verifying that the agent currently lacks the target capability. - > 2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - > triggers the `self_correction_orchestrator.py` script, which is responsible - > for integrating new knowledge and skills. - > 3. **Confirm Final Success:** It runs the same test file again, confirming that - > the agent has successfully learned the new capability and the test now passes. - > 4. **Check for Regressions:** It runs the full, existing test suite to ensure - > that the process of learning the new skill has not inadvertently broken any - > previously functional capabilities. - > - > This provides a closed-loop verification of monotonic improvement, which is a - > cornerstone of the agent's design philosophy. - -- **`tooling/code_suggester.py`**: - - > Handles the generation and application of autonomous code change suggestions. - > - > This tool is a key component of the advanced self-correction loop. It is - > designed to be invoked by the self-correction orchestrator when a lesson - > contains a 'propose-code-change' action. - > - > For its initial implementation, this tool acts as a structured executor. It - > takes a lesson where the 'details' field contains a fully-formed git-style - > merge diff and applies it to the target file. It does this by generating a - > temporary, single-step plan file and signaling its location for the master - > controller to execute. - > - > This establishes the fundamental workflow for autonomous code modification, - > decoupling the suggestion logic from the execution logic. Future iterations - > can enhance this tool with more sophisticated code generation capabilities - > (e.g., using an LLM to generate the diff from a natural language description) - > without altering the core orchestration process. - -- **`tooling/context_awareness_scanner.py`**: - - > A tool for performing static analysis on a Python file to understand its context. - > - > This script provides a "contextual awareness" scan of a specified Python file - > to help an agent (or a human) understand its role, dependencies, and connections - > within a larger codebase. This is crucial for planning complex changes or - > refactoring efforts, as it provides a snapshot of the potential impact of - > modifying a file. - > - > The scanner performs three main functions: - > 1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - > module to parse the target file and identify all the functions and classes - > that are defined within it. - > 2. **Import Analysis:** It also uses the AST to find all modules and symbols - > that the target file imports, revealing its dependencies on other parts of - > the codebase or external libraries. - > 3. **Reference Finding:** It performs a repository-wide search to find all other - > files that reference the symbols defined in the target file. This helps to - > understand how the file is used by the rest of the system. - > - > The final output is a detailed JSON report containing all of this information, - > which can be used as a foundational artifact for automated planning or human review. - -- **`tooling/csdc_cli.py`**: - - > A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - > - > This script provides an interface to validate a development plan against a specific - > CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a - > plan adheres to the strict logical and computational constraints defined by the - > CSDC protocol before it is executed. - > - > The tool performs two main checks: - > 1. **Complexity Analysis:** It analyzes the plan to determine its computational - > complexity and verifies that it matches the expected complexity class. - > 2. **Model Validation:** It validates the plan's commands against the rules of - > the specified CSDC model, ensuring that it does not violate any of the - > model's constraints (e.g., forbidding certain functions). - > - > This serves as a critical gateway for ensuring that all development work within - > the CSDC framework is sound, predictable, and compliant with the governing - > meta-mathematical principles. - -- **`tooling/dependency_graph_generator.py`**: - - > Scans the repository for dependency files and generates a unified dependency graph. - > - > This script is a crucial component of the agent's environmental awareness, - > providing a clear map of the software supply chain. It recursively searches the - > entire repository for common dependency management files, specifically: - > - `package.json` (for JavaScript/Node.js projects) - > - `requirements.txt` (for Python projects) - > - > It parses these files to identify two key types of relationships: - > 1. **Internal Dependencies:** Links between different projects within this repository. - > 2. **External Dependencies:** Links to third-party libraries and packages. - > - > The final output is a JSON file, `knowledge_core/dependency_graph.json`, which - > represents these relationships as a graph structure with nodes (projects and - > dependencies) and edges (the dependency links). This artifact is a primary - > input for the agent's orientation and planning phases, allowing it to reason - > about the potential impact of its changes. - -- **`tooling/doc_builder.py`**: - - > A unified documentation builder for the project. - > ... - -- **`tooling/document_scanner.py`**: - - > A tool for scanning the repository for human-readable documents and extracting their text content. - > - > This script is a crucial component of the agent's initial information-gathering - > and orientation phase. It allows the agent to ingest knowledge from unstructured - > or semi-structured documents that are not part of the formal codebase, but which - > may contain critical context, requirements, or specifications. - > - > The scanner searches a given directory for files with common document extensions: - > - `.pdf`: Uses the `pypdf` library to extract text from PDF files. - > - `.md`: Reads Markdown files. - > - `.txt`: Reads plain text files. - > - > The output is a dictionary where the keys are the file paths of the discovered - > documents and the values are their extracted text content. This data can then - > be used by the agent to inform its planning and execution process. This tool - > is essential for bridging the gap between human-written documentation and the - > agent's operational awareness. - -- **`tooling/environmental_probe.py`**: - - > Performs a series of checks to assess the capabilities of the execution environment. - > - > This script is a critical diagnostic tool run at the beginning of a task to - > ensure the agent understands its operational sandbox. It verifies fundamental - > capabilities required for most software development tasks: - > - > 1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - > and delete files. It also provides a basic latency measurement for these - > operations. - > 2. **Network Connectivity:** Checks for external network access by attempting to - > connect to a highly-available public endpoint (google.com). This is crucial - > for tasks requiring `git` operations, package downloads, or API calls. - > 3. **Environment Variables:** Verifies that standard environment variables are - > accessible, which is a prerequisite for many command-line tools. - > - > The script generates a human-readable report summarizing the results of these - > probes, allowing the agent to quickly identify any environmental constraints - > that might impact its ability to complete a task. - -- **`tooling/fdc_cli.py`**: - - > This script provides a command-line interface (CLI) for managing the Finite - > Development Cycle (FDC). - > - > The FDC is a structured workflow for agent-driven software development. This CLI - > is the primary human interface for interacting with that cycle, providing - > commands to: - > - **start:** Initiates a new development task, triggering the "Advanced - > Orientation and Research Protocol" (AORP) to ensure the agent is fully - > contextualized. - > - **close:** Formally concludes a task, creating a post-mortem template for - > analysis and lesson-learning. - > - **validate:** Checks a given plan file for both syntactic and semantic - > correctness against the FDC's governing Finite State Machine (FSM). This - > ensures that a plan is executable and will not violate protocol. - > - **analyze:** Examines a plan to determine its computational complexity (e.g., - > Constant, Polynomial, Exponential) and its modality (Read-Only vs. - > Read-Write), providing insight into the plan's potential impact. - -- **`tooling/filesystem_lister.py`**: - - > A tool for listing files and directories in a repository, with an option to respect .gitignore. - -- **`tooling/halting_heuristic_analyzer.py`**: - - > A static analysis tool to estimate the termination risk of a UDC plan. - > - > This script reads a `.udc` plan file, parses its instructions, and uses a - > series of heuristics to identify potential infinite loops. It is not a - > formal decider (as the halting problem is undecidable), but rather a - > practical tool to flag common patterns that lead to non-termination. - > - > The analysis focuses on: - > 1. Detecting backward jumps, which are the primary indicator of loops. - > 2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). - > 3. Checking if the registers involved in the exit conditions are modified - > within the loop body in a way that is likely to lead to termination. - > - > The tool outputs a JSON report detailing the estimated risk level (LOW, - > MEDIUM, HIGH) and the specific loops that were identified. - -- **`tooling/hdl_prover.py`**: - - > A command-line tool for proving sequents in Intuitionistic Linear Logic. - > - > This script provides a basic interface to a simple logic prover. It takes a - > sequent as a command-line argument, parses it into a logical structure, and - > then attempts to prove it using a rudimentary proof search algorithm. - > - > The primary purpose of this tool is to allow the agent to perform formal - > reasoning and verification tasks by checking the validity of logical entailments. - > For example, it can be used to verify that a certain conclusion follows from a - > set of premises according to the rules of linear logic. - > - > The current implementation uses a very basic parser and proof algorithm, - > serving as a placeholder and demonstration for a more sophisticated, underlying - > logic engine. - -- **`tooling/hierarchical_compiler.py`**: - - > A hierarchical build system for compiling nested protocol modules. - > - > This script orchestrates the compilation of `AGENTS.md` and `README.md` files - > across a repository with a nested or hierarchical module structure. It is a key - > component of the system's ability to manage complexity by allowing protocols to - > be defined in a modular, distributed way while still being presented as a unified, - > coherent whole at each level of the hierarchy. - > - > The compiler operates in two main passes: - > - > **Pass 1: Documentation Compilation (Bottom-Up)** - > 1. **Discovery:** It finds all `protocols` directories in the repository, which - > signify the root of a documentation module. - > 2. **Bottom-Up Traversal:** It processes these directories from the most deeply - > nested ones upwards. This ensures that child modules are always built before - > their parents. - > 3. **Child Summary Injection:** For each compiled child module, it generates a - > summary of its protocols and injects this summary into the parent's - > `protocols` directory as a temporary file. - > 4. **Parent Compilation:** When the parent module is compiled, the standard - > `protocol_compiler.py` automatically includes the injected child summaries, - > creating a single `AGENTS.md` file that contains both the parent's native - > protocols and the full protocols of all its direct children. - > 5. **README Generation:** After each `AGENTS.md` is compiled, the corresponding - > `README.md` is generated. - > - > **Pass 2: Centralized Knowledge Graph Compilation** - > 1. After all documentation is built, it performs a full repository scan to find - > every `*.protocol.json` file. - > 2. It parses all of these files and compiles them into a single, centralized - > RDF knowledge graph (`protocols.ttl`). This provides a unified, - > machine-readable view of every protocol defined anywhere in the system. - > - > This hierarchical approach allows for both localized, context-specific protocol - > definitions and a holistic, system-wide understanding of the agent's governing rules. - -- **`tooling/knowledge_compiler.py`**: - - > Extracts structured lessons from post-mortem reports and compiles them into a - > centralized, long-term knowledge base. - > - > This script is a core component of the agent's self-improvement feedback loop. - > After a task is completed, a post-mortem report is generated that includes a - > section for "Corrective Actions & Lessons Learned." This script automates the - > process of parsing that section to extract key insights. - > - > It identifies pairs of "Lesson" and "Action" statements and transforms them - > into a standardized, machine-readable format. These formatted entries are then - > appended to the `knowledge_core/lessons.jsonl` file, which serves as the - > agent's persistent memory of what has worked, what has failed, and what can be - > improved in future tasks. - > - > The script is executed via the command line, taking the path to a completed - > post-mortem file as its primary argument. - -- **`tooling/knowledge_integrator.py`**: - - > Enriches the local knowledge graph with data from external sources like DBPedia. - > - > This script loads the RDF graph generated from the project's protocols, - > identifies key concepts (like tools and rules), queries the DBPedia SPARQL - > endpoint to find related information, and merges the external data into a new, - > enriched knowledge graph. - -- **`tooling/lba_validator.py`**: - - > A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - > - > This module implements a validator that enforces the context-sensitive rules of the CSDC. - > Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make - > validation decisions. This is necessary to enforce rules where the validity of one - > command depends on the presence or absence of another command elsewhere in the plan. - > - > The CSDC defines two mutually exclusive models: - > - Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. - > - Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - > - > This validator checks for these co-occurrence constraints. - -- **`tooling/lfi_ill_halting_decider.py`**: - - > A tool for analyzing the termination of LFI-ILL programs. - > - > This script takes an LFI-ILL file, interprets it in a paraconsistent logic - > environment, and reports on its halting status. It does this by setting up - > a paradoxical initial state and observing how the program resolves it. - -- **`tooling/lfi_udc_model.py`**: - - > A paraconsistent execution model for UDC plans. - > - > This module provides the classes necessary to interpret a UDC (Un-decidable - > Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of - > concrete values, the state of the machine (registers, tape, etc.) is modeled - > using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - > - > This allows the system to reason about paradoxical programs, such as a program - > that halts if and only if it does not halt. By executing the program under - > paraconsistent semantics, the model can arrive at a final state of `BOTH`, - > effectively demonstrating the paradoxical nature of the input without crashing. - > - > 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. - > - `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - > analysis of a UDC plan. - -- **`tooling/log_failure.py`**: - - > A dedicated script to log a catastrophic failure event to the main activity log. - > - > This tool is designed to be invoked in the rare case of a severe, unrecoverable - > error that violates a core protocol. Its primary purpose is to ensure that such - > a critical event is formally and structurally documented in the standard agent - > activity log (`logs/activity.log.jsonl`), even if the main agent loop has - > crashed or been terminated. - > - > The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically - > attributing it to the "Unauthorized use of the `reset_all` tool." This creates a - > permanent, machine-readable record of the failure, which is essential for - > post-mortem analysis, debugging, and the development of future safeguards. - > - > By using the standard `Logger` class, it ensures that the failure log entry - > conforms to the established `LOGGING_SCHEMA.md`, making it processable by - > auditing and analysis tools. - -- **`tooling/master_control.py`**: - - > The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - > - > This script, master_control.py, is the heart of the agent's operational loop. - > It implements the CFDC, a hierarchical planning and execution model based on a - > Pushdown Automaton. This allows the agent to execute complex tasks by calling - > plans as sub-routines. - > - > Core Responsibilities: - > - **Hierarchical Plan Execution:** Manages a plan execution stack to enable - > plans to call other plans via the `call_plan` directive. This allows for - > modular, reusable, and complex task decomposition. A maximum recursion depth - > is enforced to guarantee decidability. - > - **Plan Validation:** Contains the in-memory plan validator. Before execution, - > it parses a plan and simulates its execution against a Finite State Machine - > (FSM) to ensure it complies with the agent's operational protocols. - > - **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - > it first attempts to look up the plan by its logical name in the - > `knowledge_core/plan_registry.json`. If not found, it falls back to treating - > the argument as a direct file path. - > - **FSM-Governed Lifecycle:** The entire workflow, from orientation to - > finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - > to ensure predictable and auditable behavior. - > - > This module is designed as a library to be controlled by an external shell - > (e.g., `agent_shell.py`), making its interaction purely programmatic. - -- **`tooling/master_control_cli.py`**: - - > The official command-line interface for the agent's master control loop. - > - > This script is now a lightweight wrapper that passes control to the new, - > API-driven `agent_shell.py`. It preserves the command-line interface while - > decoupling the entry point from the FSM implementation. - -- **`tooling/message_user.py`**: - - > A dummy tool that prints its arguments to simulate the message_user tool. - > - > This script is a simple command-line utility that takes a string as an - > argument and prints it to standard output, prefixed with "[Message User]:". - > Its purpose is to serve as a stand-in or mock for the actual `message_user` - > tool in testing environments where the full agent framework is not required. - > - > This allows for the testing of scripts or workflows that call the - > `message_user` tool without needing to invoke the entire agent messaging - > subsystem. - -- **`tooling/pda_parser.py`**: - - > A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - > - > This script uses the PLY (Python Lex-Yacc) library to define a lexer and a - > parser for a simple, string-based representation of pLLLU formulas. It can - > handle basic atomic formulas, unary operators (like negation and consistency), - > and binary operators (like implication and conjunction). - > - > The main function `parse_formula` takes a string and returns a simple AST - > (Abstract Syntax Tree) represented as nested tuples. - -- **`tooling/plan_executor.py`**: - - > A simple plan executor for simulating agent behavior. - > - > This script reads a plan file, parses it, and executes the commands in a - > simplified, simulated environment. It supports a limited set of tools - > (`message_user` and `run_in_bash_session`) to provide a basic demonstration - > of how an agent would execute a plan. - -- **`tooling/plan_manager.py`**: - - > Provides a command-line interface for managing the agent's Plan Registry. - > - > This script is the administrative tool for the Plan Registry, a key component - > of the Context-Free Development Cycle (CFDC) that enables hierarchical and - > modular planning. The registry, located at `knowledge_core/plan_registry.json`, - > maps human-readable, logical names to the file paths of specific plans. This - > decouples the `call_plan` directive from hardcoded file paths, making plans - > more reusable and the system more robust. - > - > This CLI provides three essential functions: - > - **register**: Associates a new logical name with a plan file path, adding it - > to the central registry. - > - **deregister**: Removes an existing logical name and its associated path from - > the registry. - > - **list**: Displays all current name-to-path mappings in the registry. - > - > By providing a simple, standardized interface for managing this library of - > reusable plans, this tool improves the agent's ability to compose complex - > workflows from smaller, validated sub-plans. - -- **`tooling/plan_parser.py`**: - - > Parses a plan file into a structured list of commands. - > - > This module provides the `parse_plan` function and the `Command` dataclass, - > which are central to the agent's ability to understand and execute plans. - > The parser correctly handles multi-line arguments and ignores comments, - > allowing for robust and readable plan files. - -- **`tooling/plllu_interpreter.py`**: - - > A resource-sensitive, four-valued interpreter for pLLLU formulas. - > - > This script implements an interpreter for the pLLLU language. It operates on - > an AST generated by the `pda_parser.py` script. The interpreter is designed - > to be resource-sensitive, meaning that each atomic formula in the initial - > context must be consumed exactly once during the evaluation of the proof. - > - > The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing - > it to reason about paraconsistent and paracomplete states. - > - > The core of the interpreter is the `FourValuedInterpreter` class, which - > recursively walks the AST, consuming resources from a context (a Counter of - > available atoms) and returning the resulting logical value. - -- **`tooling/plllu_runner.py`**: - - > A command-line runner for pLLLU files. - > - > This script provides an entry point for executing `.plllu` files. It - > integrates the pLLLU lexer, parser, and interpreter to execute the logic - > defined in a given pLLLU source file and print the result. - -- **`tooling/pre_submit_check.py`**: - - > _No module-level docstring found._ - -- **`tooling/protocol_compiler.py`**: - - > Compiles source protocol files into unified, human-readable and machine-readable artifacts. - > - > This script is the engine behind the "protocol as code" principle. It discovers, - > validates, and assembles protocol definitions from a source directory (e.g., `protocols/`) - > into high-level documents like `AGENTS.md`. - > - > Key Functions: - > - **Discovery:** Scans a directory for source files, including `.protocol.json` - > (machine-readable rules) and `.protocol.md` (human-readable context). - > - **Validation:** Uses a JSON schema (`protocol.schema.json`) to validate every - > `.protocol.json` file, ensuring all protocol definitions are syntactically - > correct and adhere to the established structure. - > - **Compilation:** Combines the human-readable markdown and the machine-readable - > JSON into a single, cohesive Markdown file, embedding the JSON in code blocks. - > - **Documentation Injection:** Can inject other generated documents, like the - > `SYSTEM_DOCUMENTATION.md`, into the final output at specified locations. - > - **Knowledge Graph Generation:** Optionally, it can process the validated JSON - > protocols and serialize them into an RDF knowledge graph (in Turtle format), - > creating a machine-queryable version of the agent's governing rules. - > - > This process ensures that `AGENTS.md` and other protocol documents are not edited - > manually but are instead generated from a validated, single source of truth, - > making the agent's protocols robust, verifiable, and maintainable. - -- **`tooling/protocol_updater.py`**: - - > A command-line tool for programmatically updating protocol source files. - > - > This script provides the mechanism for the agent to perform self-correction - > by modifying its own governing protocols based on structured, actionable - > lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) - > workflow. - > - > The tool operates on the .protocol.json files located in the `protocols/` - > directory, performing targeted updates based on command-line arguments. - -- **`tooling/refactor.py`**: - - > A tool for performing automated symbol renaming in Python code. - > - > This script provides a command-line interface to find a specific symbol - > (a function or a class) in a given Python file and rename it, along with all of - > its textual references throughout the entire repository. This provides a safe - > and automated way to perform a common refactoring task, reducing the risk of - > manual errors. - > - > The tool operates in three main stages: - > 1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - > to parse the source file and precisely locate the definition of the target - > symbol. This ensures that the tool is targeting the correct code construct. - > 2. **Reference Finding:** It performs a text-based search across the specified - > search path (defaulting to the entire repository) to find all files that - > mention the symbol's old name. - > 3. **Plan Generation:** Instead of modifying files directly, it generates a - > refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - > commands, one for each file that needs to be changed. The path to this - > generated plan file is printed to standard output. - > - > This plan-based approach allows the agent's master controller to execute the - > refactoring in a controlled, verifiable, and atomic way, consistent with its - > standard operational procedures. - -- **`tooling/reliable_ls.py`**: - - > A tool for reliably listing files and directories. - > - > This script provides a consistent, sorted, and recursive listing of files and - > directories, excluding the `.git` directory. It is intended to be a more - > reliable alternative to the standard `ls` command for agent use cases. - -- **`tooling/reorientation_manager.py`**: - - > Re-orientation Manager - > - > This script is the core of the automated re-orientation process. It is - > designed to be triggered by the build system whenever the agent's core - > protocols (`AGENTS.md`) are re-compiled. - > - > The manager performs the following key functions: - > 1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - > version to identify new protocols, tools, or other key concepts that have - > been introduced. - > 2. **Temporal Orientation (Shallow Research):** For each new concept, it - > invokes the `temporal_orienter.py` tool to fetch a high-level summary from - > an external knowledge base like DBpedia. This ensures the agent has a - > baseline understanding of new terms. - > 3. **Knowledge Storage:** The summaries from the temporal orientation are - > stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - > creating a persistent, queryable knowledge artifact. - > 4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - > change is deemed significant (e.g., the addition of a new core - > architectural protocol), it programmatically triggers a formal L4 Deep - > Research Cycle by creating a `deep_research_required.json` file. - > - > This automated workflow ensures that the agent never operates with an outdated - > understanding of its own protocols. It closes the loop between protocol - > modification and the agent's self-awareness, making the system more robust, - > adaptive, and reliable. - -- **`tooling/research.py`**: - - > This module contains the logic for executing research tasks based on a set of - > constraints. It acts as a dispatcher, calling the appropriate tool (e.g., - > read_file, google_search) based on the specified target and scope. - -- **`tooling/research_planner.py`**: - - > This module is responsible for generating a formal, FSM-compliant research plan - > for a given topic. The output is a string that can be executed by the agent's - > master controller. - -- **`tooling/self_correction_orchestrator.py`**: - - > Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - > - > This script is the engine of the automated feedback loop. It reads structured, - > actionable lessons from `knowledge_core/lessons.jsonl` and uses the - > `protocol_updater.py` tool to apply them to the source protocol files. - -- **`tooling/self_improvement_cli.py`**: - - > Analyzes agent activity logs to identify opportunities for self-improvement. - > - > This script is a command-line tool that serves as a key part of the agent's - > meta-cognitive loop. It parses the structured activity log - > (`logs/activity.log.jsonl`) to identify patterns that may indicate - > inefficiencies or errors in the agent's workflow. - > - > The primary analysis currently implemented is: - > - **Planning Efficiency Analysis:** It scans the logs for tasks that required - > multiple `set_plan` actions. A high number of plan revisions for a single - > task can suggest that the initial planning phase was insufficient, the task - > was poorly understood, or the agent struggled to adapt to unforeseen - > challenges. - > - > By flagging these tasks, the script provides a starting point for a deeper - > post-mortem analysis, helping the agent (or its developers) to understand the - > root causes of the planning churn and to develop strategies for more effective - > upfront planning in the future. - > - > The tool is designed to be extensible, with future analyses (such as error - > rate tracking or tool usage anti-patterns) to be added as the system evolves. - -- **`tooling/standard_agents_compiler.py`**: - - > A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - > - > This script acts as an "adapter" to make the repository more accessible to - > third-party AI agents that expect a conventional set of instructions. While the - > repository's primary `AGENTS.md` is a complex, hierarchical, and - > machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` - > file produced by this script offers a simple, human-readable summary of the - > most common development commands. - > - > The script works by: - > 1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - > which is the single source of truth for high-level commands. It specifically - > extracts the exact commands for common targets like `install`, `test`, - > `lint`, and `format`. This ensures the generated instructions are never - > stale. - > 2. **Injecting into a Template:** It injects these extracted commands into a - > pre-defined, user-friendly Markdown template. - > 3. **Generating the Artifact:** The final output is written to - > `AGENTS.standard.md`, providing a simple, stable, and conventional entry - > point for external tools, effectively bridging the gap between the complex - > internal protocol system and the broader agent ecosystem. - -- **`tooling/state.py`**: - - > Defines the core data structures for managing the agent's state. - > - > This module provides the `AgentState` and `PlanContext` dataclasses, which are - > fundamental to the operation of the Context-Free Development Cycle (CFDC). These - > structures allow the `master_control.py` orchestrator to maintain a complete, - > snapshot-able representation of the agent's progress through a task. - > - > - `AgentState`: The primary container for all information related to the current - > task, including the plan execution stack, message history, and error states. - > - `PlanContext`: A specific structure that holds the state of a single plan - > file, including its content and the current execution step. This is the - > element that gets pushed onto the `plan_stack` in `AgentState`. - > - > Together, these classes enable the hierarchical, stack-based planning and - > execution that is the hallmark of the CFDC. - -- **`tooling/symbol_map_generator.py`**: - - > Generates a code symbol map for the repository to aid in contextual understanding. - > - > This script creates a `symbols.json` file in the `knowledge_core` directory, - > which acts as a high-level index of the codebase. This map contains information - > about key programming constructs like classes and functions, including their - > name, location (file path and line number), and language. - > - > The script employs a two-tiered approach for symbol generation: - > 1. **Universal Ctags (Preferred):** It first checks for the presence of the - > `ctags` command-line tool. If available, it uses `ctags` to perform a - > comprehensive, multi-language scan of the repository. This is the most - > robust and accurate method. - > 2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - > back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - > method parses all `.py` files and extracts symbol information for Python - > code. While less comprehensive than `ctags`, it ensures that a baseline - > symbol map is always available. - > - > The resulting `symbols.json` artifact is a critical input for the agent's - > orientation and planning phases, allowing it to quickly locate relevant code - > and understand the structure of the repository without having to read every file. - -- **`tooling/udc_orchestrator.py`**: - - > An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - > - > This script provides a sandboxed environment for running UDC plans, which are - > low-level assembly-like programs that can perform Turing-complete computations. - > The orchestrator acts as a virtual machine with a tape-based memory model, - > registers, and a set of simple instructions. - > - > To prevent non-termination and other resource-exhaustion issues, the - > orchestrator imposes strict limits on the number of instructions executed, - > the amount of memory used, and the total wall-clock time. - -## Experimental Framework - -The `experiments/` directory contains a framework for testing the agent's behavior in response to changes in its governing protocols (`AGENTS.md`). Each subdirectory within `experiments/` represents a self-contained experiment. - -### Running an Experiment - -To run an existing experiment (e.g., `scoped_protocol_override`): - -1. **Review the Experiment:** Read the `README.md` inside the experiment's directory (e.g., `experiments/scoped_protocol_override/README.md`) to understand its hypothesis, procedure, and expected outcome. -2. **Perform the Baseline Run:** Follow the instructions in the experiment's `README.md` to establish the agent's baseline behavior. This usually involves performing a task in the root directory. -3. **Perform the Experimental Run:** Follow the instructions to run the agent against the mutated protocol. This typically involves: - a. Copying the `mutation.md` file to a new `AGENTS.md` file within the experiment's directory. - b. Instructing the agent to perform the task specified in `task.md`, targeting the experiment's directory. -4. **Compare the Results:** Observe the difference in the agent's behavior between the baseline and experimental runs to verify the hypothesis. - -### Creating a New Experiment - -1. Create a new subdirectory in `experiments/`. -2. Add a `README.md` file explaining the new experiment's hypothesis and procedure. -3. Add a `mutation.md` file containing the altered `AGENTS.md` content. -4. Add a `task.md` file describing the task the agent should perform. - ---- - -# Module Documentation - -## Overview - -This document provides a human-readable summary of the protocols and key components defined within this module. It is automatically generated. - -## Core Protocols - -- **`dependency-management-001`**: A protocol for ensuring a reliable execution environment through formal dependency management. -- **`experimental-prologue-001`**: An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation. -- **`agent-shell-001`**: A protocol governing the use of the interactive agent shell as the primary entry point for all tasks. -- **`toolchain-review-on-schema-change-001`**: A meta-protocol to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols. -- **`unified-auditor-001`**: A protocol for the unified repository auditing tool, which combines multiple health and compliance checks into a single interface. -- **`aura-execution-001`**: A protocol for executing Aura scripts, enabling a more expressive and powerful planning and automation language for the agent. -- **`capability-verification-001`**: A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement. -- **`csdc-001`**: A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints. -- **`unified-doc-builder-001`**: A protocol for the unified documentation builder, which generates various documentation artifacts from the repository's sources of truth. -- **`file-indexing-001`**: A protocol for maintaining an up-to-date file index to accelerate tool performance. -- **`hdl-proving-001`**: A protocol for interacting with the Hypersequent-calculus-based logic engine, allowing the agent to perform formal logical proofs. -- **`agent-interaction-001`**: A protocol governing the agent's core interaction and planning tools. -- **`plllu-execution-001`**: A protocol for executing pLLLU scripts, enabling a more expressive and powerful planning and automation language for the agent. -- **`security-header`**: Defines the identity and purpose of the Security Protocol document. -- **`security-vuln-reporting-001`**: Defines the official policy and procedure for reporting security vulnerabilities. -- **`speculative-execution-001`**: A protocol that governs the agent's ability to initiate and execute self-generated, creative, or exploratory tasks during idle periods. - -## Key Components - -- **`tooling/__init__.py`**: - - > This module contains the various tools and utilities that support the agent's - > development, testing, and operational workflows. - > - > The tools in this package are the building blocks of the agent's capabilities, - > ranging from code analysis and refactoring to protocol compilation and - > self-correction. Each script is designed to be a self-contained unit of - > functionality that can be invoked either from the command line or programmatically - > by the agent's master control system. - > - > This __init__.py file marks the 'tooling' directory as a Python package, - > allowing for the organized import of its various modules. - -- **`tooling/agent_shell.py`**: - - > The new, interactive, API-driven entry point for the agent. - > - > This script replaces the old file-based signaling system with a direct, - > programmatic interface to the MasterControlGraph FSM. It is responsible for: - > 1. Initializing the agent's state and a centralized logger. - > 2. Instantiating and running the MasterControlGraph. - > 3. Driving the FSM by calling its methods and passing data and the logger. - > 4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - > and respond to requests for action. - -- **`tooling/__init__.py`**: - - > _No module-level docstring found._ - -- **`tooling/generate_and_test.py`**: - - > _No module-level docstring found._ - -- **`tooling/appl_runner.py`**: - - > A command-line tool for executing APPL files. - > - > This script provides a simple interface to run APPL files using the main - > `run.py` interpreter. It captures and prints the output of the execution, - > and provides detailed error reporting if the execution fails. - -- **`tooling/appl_to_lfi_ill.py`**: - - > A compiler that translates APPL (a simple functional language) to LFI-ILL. - > - > This script takes a Python file containing an APPL AST, and compiles it into - > an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - -- **`tooling/auditor.py`**: - - > A unified auditing tool for maintaining repository health and compliance. - > - > This script combines the functionality of several disparate auditing tools into a - > single, comprehensive command-line interface. It serves as the central tool for - > validating the key components of the agent's architecture, including protocols, - > plans, and documentation. - > - > The auditor can perform the following checks: - > 1. **Protocol Audit (`protocol`):** - > - Checks if `AGENTS.md` artifacts are stale compared to their source files. - > - Verifies protocol completeness by comparing tools used in logs against - > tools defined in protocols. - > - Analyzes tool usage frequency (centrality). - > 2. **Plan Registry Audit (`plans`):** - > - Scans `knowledge_core/plan_registry.json` for "dead links" where the - > target plan file does not exist. - > 3. **Documentation Audit (`docs`):** - > - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - > that are missing module-level docstrings. - > - > The tool is designed to be run from the command line and can execute specific - > audits or all of them, generating a consolidated `audit_report.md` file. - -- **`tooling/aura_executor.py`**: - - > This script serves as the command-line executor for `.aura` files. - > - > It bridges the gap between the high-level Aura scripting language and the - > agent's underlying Python-based toolset. The executor is responsible for: - > 1. Parsing the `.aura` source code using the lexer and parser from the - > `aura_lang` package. - > 2. Setting up an execution environment for the interpreter. - > 3. Injecting a "tool-calling" capability into the Aura environment, which - > allows Aura scripts to dynamically invoke registered Python tools - > (e.g., `hdl_prover`, `environmental_probe`). - > 4. Executing the parsed program and printing the final result. - > - > This makes it a key component for enabling more expressive and complex - > automation scripts for the agent. - -- **`tooling/aura_to_lfi_ill.py`**: - - > A compiler that translates AURA code to LFI-ILL. - > - > This script takes an AURA file, parses it, and compiles it into an LFI-ILL - > AST. The resulting AST is then written to a `.lfi_ill` file. - -- **`tooling/background_researcher.py`**: - - > This script performs a simulated research task in the background. - > It takes a task ID as a command-line argument and writes its findings - > to a temporary file that the main agent can poll. - -- **`tooling/builder.py`**: - - > A unified, configuration-driven build script for the project. - > - > This script serves as the central entry point for all build-related tasks, such - > as generating documentation, compiling protocols, and running code quality checks. - > It replaces a traditional Makefile's direct command execution with a more - > structured, maintainable, and introspectable approach. - > - > The core logic is driven by a `build_config.json` file, which defines a series - > of "targets." Each target specifies: - > - The `type` of target: "compiler" or "command". - > - For "compiler" types: `compiler` script, `output`, `sources`, and `options`. - > - For "command" types: the `command` to execute. - > - > The configuration also defines "build_groups", which are ordered collections of - > targets (e.g., "all", "quality"). - > - > This centralized builder provides several advantages: - > - **Single Source of Truth:** The `build_config.json` file is the definitive - > source for all build logic. - > - **Consistency:** Ensures all build tasks are executed in a uniform way. - > - **Extensibility:** New build targets can be added by simply updating the - > configuration file. - > - **Discoverability:** The script can list all available targets and groups. - -- **`tooling/capability_verifier.py`**: - - > A tool to verify that the agent can monotonically improve its capabilities. - > - > This script is designed to provide a formal, automated test for the agent's - > self-correction and learning mechanisms. It ensures that when the agent learns - > a new capability, it does so without losing (regressing) any of its existing - > capabilities. This is a critical safeguard for ensuring robust and reliable - > agent evolution. - > - > The tool works by orchestrating a four-step process: - > 1. **Confirm Initial Failure:** It runs a specific test file that is known to - > fail, verifying that the agent currently lacks the target capability. - > 2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - > triggers the `self_correction_orchestrator.py` script, which is responsible - > for integrating new knowledge and skills. - > 3. **Confirm Final Success:** It runs the same test file again, confirming that - > the agent has successfully learned the new capability and the test now passes. - > 4. **Check for Regressions:** It runs the full, existing test suite to ensure - > that the process of learning the new skill has not inadvertently broken any - > previously functional capabilities. - > - > This provides a closed-loop verification of monotonic improvement, which is a - > cornerstone of the agent's design philosophy. - -- **`tooling/code_suggester.py`**: - - > Handles the generation and application of autonomous code change suggestions. - > - > This tool is a key component of the advanced self-correction loop. It is - > designed to be invoked by the self-correction orchestrator when a lesson - > contains a 'propose-code-change' action. - > - > For its initial implementation, this tool acts as a structured executor. It - > takes a lesson where the 'details' field contains a fully-formed git-style - > merge diff and applies it to the target file. It does this by generating a - > temporary, single-step plan file and signaling its location for the master - > controller to execute. - > - > This establishes the fundamental workflow for autonomous code modification, - > decoupling the suggestion logic from the execution logic. Future iterations - > can enhance this tool with more sophisticated code generation capabilities - > (e.g., using an LLM to generate the diff from a natural language description) - > without altering the core orchestration process. - -- **`tooling/context_awareness_scanner.py`**: - - > A tool for performing static analysis on a Python file to understand its context. - > - > This script provides a "contextual awareness" scan of a specified Python file - > to help an agent (or a human) understand its role, dependencies, and connections - > within a larger codebase. This is crucial for planning complex changes or - > refactoring efforts, as it provides a snapshot of the potential impact of - > modifying a file. - > - > The scanner performs three main functions: - > 1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - > module to parse the target file and identify all the functions and classes - > that are defined within it. - > 2. **Import Analysis:** It also uses the AST to find all modules and symbols - > that the target file imports, revealing its dependencies on other parts of - > the codebase or external libraries. - > 3. **Reference Finding:** It performs a repository-wide search to find all other - > files that reference the symbols defined in the target file. This helps to - > understand how the file is used by the rest of the system. - > - > The final output is a detailed JSON report containing all of this information, - > which can be used as a foundational artifact for automated planning or human review. - -- **`tooling/csdc_cli.py`**: - - > A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - > - > This script provides an interface to validate a development plan against a specific - > CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a - > plan adheres to the strict logical and computational constraints defined by the - > CSDC protocol before it is executed. - > - > The tool performs two main checks: - > 1. **Complexity Analysis:** It analyzes the plan to determine its computational - > complexity and verifies that it matches the expected complexity class. - > 2. **Model Validation:** It validates the plan's commands against the rules of - > the specified CSDC model, ensuring that it does not violate any of the - > model's constraints (e.g., forbidding certain functions). - > - > This serves as a critical gateway for ensuring that all development work within - > the CSDC framework is sound, predictable, and compliant with the governing - > meta-mathematical principles. - -- **`tooling/dependency_graph_generator.py`**: - - > Scans the repository for dependency files and generates a unified dependency graph. - > - > This script is a crucial component of the agent's environmental awareness, - > providing a clear map of the software supply chain. It recursively searches the - > entire repository for common dependency management files, specifically: - > - `package.json` (for JavaScript/Node.js projects) - > - `requirements.txt` (for Python projects) - > - > It parses these files to identify two key types of relationships: - > 1. **Internal Dependencies:** Links between different projects within this repository. - > 2. **External Dependencies:** Links to third-party libraries and packages. - > - > The final output is a JSON file, `knowledge_core/dependency_graph.json`, which - > represents these relationships as a graph structure with nodes (projects and - > dependencies) and edges (the dependency links). This artifact is a primary - > input for the agent's orientation and planning phases, allowing it to reason - > about the potential impact of its changes. - -- **`tooling/doc_builder.py`**: - - > A unified documentation builder for the project. - > ... - -- **`tooling/document_scanner.py`**: - - > A tool for scanning the repository for human-readable documents and extracting their text content. - > - > This script is a crucial component of the agent's initial information-gathering - > and orientation phase. It allows the agent to ingest knowledge from unstructured - > or semi-structured documents that are not part of the formal codebase, but which - > may contain critical context, requirements, or specifications. - > - > The scanner searches a given directory for files with common document extensions: - > - `.pdf`: Uses the `pypdf` library to extract text from PDF files. - > - `.md`: Reads Markdown files. - > - `.txt`: Reads plain text files. - > - > The output is a dictionary where the keys are the file paths of the discovered - > documents and the values are their extracted text content. This data can then - > be used by the agent to inform its planning and execution process. This tool - > is essential for bridging the gap between human-written documentation and the - > agent's operational awareness. - -- **`tooling/environmental_probe.py`**: - - > Performs a series of checks to assess the capabilities of the execution environment. - > - > This script is a critical diagnostic tool run at the beginning of a task to - > ensure the agent understands its operational sandbox. It verifies fundamental - > capabilities required for most software development tasks: - > - > 1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - > and delete files. It also provides a basic latency measurement for these - > operations. - > 2. **Network Connectivity:** Checks for external network access by attempting to - > connect to a highly-available public endpoint (google.com). This is crucial - > for tasks requiring `git` operations, package downloads, or API calls. - > 3. **Environment Variables:** Verifies that standard environment variables are - > accessible, which is a prerequisite for many command-line tools. - > - > The script generates a human-readable report summarizing the results of these - > probes, allowing the agent to quickly identify any environmental constraints - > that might impact its ability to complete a task. - -- **`tooling/fdc_cli.py`**: - - > This script provides a command-line interface (CLI) for managing the Finite - > Development Cycle (FDC). - > - > The FDC is a structured workflow for agent-driven software development. This CLI - > is the primary human interface for interacting with that cycle, providing - > commands to: - > - **start:** Initiates a new development task, triggering the "Advanced - > Orientation and Research Protocol" (AORP) to ensure the agent is fully - > contextualized. - > - **close:** Formally concludes a task, creating a post-mortem template for - > analysis and lesson-learning. - > - **validate:** Checks a given plan file for both syntactic and semantic - > correctness against the FDC's governing Finite State Machine (FSM). This - > ensures that a plan is executable and will not violate protocol. - > - **analyze:** Examines a plan to determine its computational complexity (e.g., - > Constant, Polynomial, Exponential) and its modality (Read-Only vs. - > Read-Write), providing insight into the plan's potential impact. - -- **`tooling/filesystem_lister.py`**: - - > A tool for listing files and directories in a repository, with an option to respect .gitignore. - -- **`tooling/halting_heuristic_analyzer.py`**: - - > A static analysis tool to estimate the termination risk of a UDC plan. - > - > This script reads a `.udc` plan file, parses its instructions, and uses a - > series of heuristics to identify potential infinite loops. It is not a - > formal decider (as the halting problem is undecidable), but rather a - > practical tool to flag common patterns that lead to non-termination. - > - > The analysis focuses on: - > 1. Detecting backward jumps, which are the primary indicator of loops. - > 2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). - > 3. Checking if the registers involved in the exit conditions are modified - > within the loop body in a way that is likely to lead to termination. - > - > The tool outputs a JSON report detailing the estimated risk level (LOW, - > MEDIUM, HIGH) and the specific loops that were identified. - -- **`tooling/hdl_prover.py`**: - - > A command-line tool for proving sequents in Intuitionistic Linear Logic. - > - > This script provides a basic interface to a simple logic prover. It takes a - > sequent as a command-line argument, parses it into a logical structure, and - > then attempts to prove it using a rudimentary proof search algorithm. - > - > The primary purpose of this tool is to allow the agent to perform formal - > reasoning and verification tasks by checking the validity of logical entailments. - > For example, it can be used to verify that a certain conclusion follows from a - > set of premises according to the rules of linear logic. - > - > The current implementation uses a very basic parser and proof algorithm, - > serving as a placeholder and demonstration for a more sophisticated, underlying - > logic engine. - -- **`tooling/hierarchical_compiler.py`**: - - > A hierarchical build system for compiling nested protocol modules. - > - > This script orchestrates the compilation of `AGENTS.md` and `README.md` files - > across a repository with a nested or hierarchical module structure. It is a key - > component of the system's ability to manage complexity by allowing protocols to - > be defined in a modular, distributed way while still being presented as a unified, - > coherent whole at each level of the hierarchy. - > - > The compiler operates in two main passes: - > - > **Pass 1: Documentation Compilation (Bottom-Up)** - > 1. **Discovery:** It finds all `protocols` directories in the repository, which - > signify the root of a documentation module. - > 2. **Bottom-Up Traversal:** It processes these directories from the most deeply - > nested ones upwards. This ensures that child modules are always built before - > their parents. - > 3. **Child Summary Injection:** For each compiled child module, it generates a - > summary of its protocols and injects this summary into the parent's - > `protocols` directory as a temporary file. - > 4. **Parent Compilation:** When the parent module is compiled, the standard - > `protocol_compiler.py` automatically includes the injected child summaries, - > creating a single `AGENTS.md` file that contains both the parent's native - > protocols and the full protocols of all its direct children. - > 5. **README Generation:** After each `AGENTS.md` is compiled, the corresponding - > `README.md` is generated. - > - > **Pass 2: Centralized Knowledge Graph Compilation** - > 1. After all documentation is built, it performs a full repository scan to find - > every `*.protocol.json` file. - > 2. It parses all of these files and compiles them into a single, centralized - > RDF knowledge graph (`protocols.ttl`). This provides a unified, - > machine-readable view of every protocol defined anywhere in the system. - > - > This hierarchical approach allows for both localized, context-specific protocol - > definitions and a holistic, system-wide understanding of the agent's governing rules. - -- **`tooling/knowledge_compiler.py`**: - - > Extracts structured lessons from post-mortem reports and compiles them into a - > centralized, long-term knowledge base. - > - > This script is a core component of the agent's self-improvement feedback loop. - > After a task is completed, a post-mortem report is generated that includes a - > section for "Corrective Actions & Lessons Learned." This script automates the - > process of parsing that section to extract key insights. - > - > It identifies pairs of "Lesson" and "Action" statements and transforms them - > into a standardized, machine-readable format. These formatted entries are then - > appended to the `knowledge_core/lessons.jsonl` file, which serves as the - > agent's persistent memory of what has worked, what has failed, and what can be - > improved in future tasks. - > - > The script is executed via the command line, taking the path to a completed - > post-mortem file as its primary argument. - -- **`tooling/knowledge_integrator.py`**: - - > Enriches the local knowledge graph with data from external sources like DBPedia. - > - > This script loads the RDF graph generated from the project's protocols, - > identifies key concepts (like tools and rules), queries the DBPedia SPARQL - > endpoint to find related information, and merges the external data into a new, - > enriched knowledge graph. - -- **`tooling/lba_validator.py`**: - - > A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - > - > This module implements a validator that enforces the context-sensitive rules of the CSDC. - > Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make - > validation decisions. This is necessary to enforce rules where the validity of one - > command depends on the presence or absence of another command elsewhere in the plan. - > - > The CSDC defines two mutually exclusive models: - > - Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. - > - Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - > - > This validator checks for these co-occurrence constraints. - -- **`tooling/lfi_ill_halting_decider.py`**: - - > A tool for analyzing the termination of LFI-ILL programs. - > - > This script takes an LFI-ILL file, interprets it in a paraconsistent logic - > environment, and reports on its halting status. It does this by setting up - > a paradoxical initial state and observing how the program resolves it. - -- **`tooling/lfi_udc_model.py`**: - - > A paraconsistent execution model for UDC plans. - > - > This module provides the classes necessary to interpret a UDC (Un-decidable - > Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of - > concrete values, the state of the machine (registers, tape, etc.) is modeled - > using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - > - > This allows the system to reason about paradoxical programs, such as a program - > that halts if and only if it does not halt. By executing the program under - > paraconsistent semantics, the model can arrive at a final state of `BOTH`, - > effectively demonstrating the paradoxical nature of the input without crashing. - > - > 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. - > - `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - > analysis of a UDC plan. - -- **`tooling/log_failure.py`**: - - > A dedicated script to log a catastrophic failure event to the main activity log. - > - > This tool is designed to be invoked in the rare case of a severe, unrecoverable - > error that violates a core protocol. Its primary purpose is to ensure that such - > a critical event is formally and structurally documented in the standard agent - > activity log (`logs/activity.log.jsonl`), even if the main agent loop has - > crashed or been terminated. - > - > The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically - > attributing it to the "Unauthorized use of the `reset_all` tool." This creates a - > permanent, machine-readable record of the failure, which is essential for - > post-mortem analysis, debugging, and the development of future safeguards. - > - > By using the standard `Logger` class, it ensures that the failure log entry - > conforms to the established `LOGGING_SCHEMA.md`, making it processable by - > auditing and analysis tools. - -- **`tooling/master_control.py`**: - - > The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - > - > This script, master_control.py, is the heart of the agent's operational loop. - > It implements the CFDC, a hierarchical planning and execution model based on a - > Pushdown Automaton. This allows the agent to execute complex tasks by calling - > plans as sub-routines. - > - > Core Responsibilities: - > - **Hierarchical Plan Execution:** Manages a plan execution stack to enable - > plans to call other plans via the `call_plan` directive. This allows for - > modular, reusable, and complex task decomposition. A maximum recursion depth - > is enforced to guarantee decidability. - > - **Plan Validation:** Contains the in-memory plan validator. Before execution, - > it parses a plan and simulates its execution against a Finite State Machine - > (FSM) to ensure it complies with the agent's operational protocols. - > - **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - > it first attempts to look up the plan by its logical name in the - > `knowledge_core/plan_registry.json`. If not found, it falls back to treating - > the argument as a direct file path. - > - **FSM-Governed Lifecycle:** The entire workflow, from orientation to - > finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - > to ensure predictable and auditable behavior. - > - > This module is designed as a library to be controlled by an external shell - > (e.g., `agent_shell.py`), making its interaction purely programmatic. - -- **`tooling/master_control_cli.py`**: - - > The official command-line interface for the agent's master control loop. - > - > This script is now a lightweight wrapper that passes control to the new, - > API-driven `agent_shell.py`. It preserves the command-line interface while - > decoupling the entry point from the FSM implementation. - -- **`tooling/message_user.py`**: - - > A dummy tool that prints its arguments to simulate the message_user tool. - > - > This script is a simple command-line utility that takes a string as an - > argument and prints it to standard output, prefixed with "[Message User]:". - > Its purpose is to serve as a stand-in or mock for the actual `message_user` - > tool in testing environments where the full agent framework is not required. - > - > This allows for the testing of scripts or workflows that call the - > `message_user` tool without needing to invoke the entire agent messaging - > subsystem. - -- **`tooling/pda_parser.py`**: - - > A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - > - > This script uses the PLY (Python Lex-Yacc) library to define a lexer and a - > parser for a simple, string-based representation of pLLLU formulas. It can - > handle basic atomic formulas, unary operators (like negation and consistency), - > and binary operators (like implication and conjunction). - > - > The main function `parse_formula` takes a string and returns a simple AST - > (Abstract Syntax Tree) represented as nested tuples. - -- **`tooling/plan_executor.py`**: - - > A simple plan executor for simulating agent behavior. - > - > This script reads a plan file, parses it, and executes the commands in a - > simplified, simulated environment. It supports a limited set of tools - > (`message_user` and `run_in_bash_session`) to provide a basic demonstration - > of how an agent would execute a plan. - -- **`tooling/plan_manager.py`**: - - > Provides a command-line interface for managing the agent's Plan Registry. - > - > This script is the administrative tool for the Plan Registry, a key component - > of the Context-Free Development Cycle (CFDC) that enables hierarchical and - > modular planning. The registry, located at `knowledge_core/plan_registry.json`, - > maps human-readable, logical names to the file paths of specific plans. This - > decouples the `call_plan` directive from hardcoded file paths, making plans - > more reusable and the system more robust. - > - > This CLI provides three essential functions: - > - **register**: Associates a new logical name with a plan file path, adding it - > to the central registry. - > - **deregister**: Removes an existing logical name and its associated path from - > the registry. - > - **list**: Displays all current name-to-path mappings in the registry. - > - > By providing a simple, standardized interface for managing this library of - > reusable plans, this tool improves the agent's ability to compose complex - > workflows from smaller, validated sub-plans. - -- **`tooling/plan_parser.py`**: - - > Parses a plan file into a structured list of commands. - > - > This module provides the `parse_plan` function and the `Command` dataclass, - > which are central to the agent's ability to understand and execute plans. - > The parser correctly handles multi-line arguments and ignores comments, - > allowing for robust and readable plan files. - -- **`tooling/plllu_interpreter.py`**: - - > A resource-sensitive, four-valued interpreter for pLLLU formulas. - > - > This script implements an interpreter for the pLLLU language. It operates on - > an AST generated by the `pda_parser.py` script. The interpreter is designed - > to be resource-sensitive, meaning that each atomic formula in the initial - > context must be consumed exactly once during the evaluation of the proof. - > - > The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing - > it to reason about paraconsistent and paracomplete states. - > - > The core of the interpreter is the `FourValuedInterpreter` class, which - > recursively walks the AST, consuming resources from a context (a Counter of - > available atoms) and returning the resulting logical value. - -- **`tooling/plllu_runner.py`**: - - > A command-line runner for pLLLU files. - > - > This script provides an entry point for executing `.plllu` files. It - > integrates the pLLLU lexer, parser, and interpreter to execute the logic - > defined in a given pLLLU source file and print the result. - -- **`tooling/pre_submit_check.py`**: - - > _No module-level docstring found._ - -- **`tooling/protocol_compiler.py`**: - - > Compiles source protocol files into unified, human-readable and machine-readable artifacts. - > - > This script is the engine behind the "protocol as code" principle. It discovers, - > validates, and assembles protocol definitions from a source directory (e.g., `protocols/`) - > into high-level documents like `AGENTS.md`. - > - > Key Functions: - > - **Discovery:** Scans a directory for source files, including `.protocol.json` - > (machine-readable rules) and `.protocol.md` (human-readable context). - > - **Validation:** Uses a JSON schema (`protocol.schema.json`) to validate every - > `.protocol.json` file, ensuring all protocol definitions are syntactically - > correct and adhere to the established structure. - > - **Compilation:** Combines the human-readable markdown and the machine-readable - > JSON into a single, cohesive Markdown file, embedding the JSON in code blocks. - > - **Documentation Injection:** Can inject other generated documents, like the - > `SYSTEM_DOCUMENTATION.md`, into the final output at specified locations. - > - **Knowledge Graph Generation:** Optionally, it can process the validated JSON - > protocols and serialize them into an RDF knowledge graph (in Turtle format), - > creating a machine-queryable version of the agent's governing rules. - > - > This process ensures that `AGENTS.md` and other protocol documents are not edited - > manually but are instead generated from a validated, single source of truth, - > making the agent's protocols robust, verifiable, and maintainable. - -- **`tooling/protocol_updater.py`**: - - > A command-line tool for programmatically updating protocol source files. - > - > This script provides the mechanism for the agent to perform self-correction - > by modifying its own governing protocols based on structured, actionable - > lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) - > workflow. - > - > The tool operates on the .protocol.json files located in the `protocols/` - > directory, performing targeted updates based on command-line arguments. - -- **`tooling/refactor.py`**: - - > A tool for performing automated symbol renaming in Python code. - > - > This script provides a command-line interface to find a specific symbol - > (a function or a class) in a given Python file and rename it, along with all of - > its textual references throughout the entire repository. This provides a safe - > and automated way to perform a common refactoring task, reducing the risk of - > manual errors. - > - > The tool operates in three main stages: - > 1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - > to parse the source file and precisely locate the definition of the target - > symbol. This ensures that the tool is targeting the correct code construct. - > 2. **Reference Finding:** It performs a text-based search across the specified - > search path (defaulting to the entire repository) to find all files that - > mention the symbol's old name. - > 3. **Plan Generation:** Instead of modifying files directly, it generates a - > refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - > commands, one for each file that needs to be changed. The path to this - > generated plan file is printed to standard output. - > - > This plan-based approach allows the agent's master controller to execute the - > refactoring in a controlled, verifiable, and atomic way, consistent with its - > standard operational procedures. - -- **`tooling/reliable_ls.py`**: - - > A tool for reliably listing files and directories. - > - > This script provides a consistent, sorted, and recursive listing of files and - > directories, excluding the `.git` directory. It is intended to be a more - > reliable alternative to the standard `ls` command for agent use cases. - -- **`tooling/reorientation_manager.py`**: - - > Re-orientation Manager - > - > This script is the core of the automated re-orientation process. It is - > designed to be triggered by the build system whenever the agent's core - > protocols (`AGENTS.md`) are re-compiled. - > - > The manager performs the following key functions: - > 1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - > version to identify new protocols, tools, or other key concepts that have - > been introduced. - > 2. **Temporal Orientation (Shallow Research):** For each new concept, it - > invokes the `temporal_orienter.py` tool to fetch a high-level summary from - > an external knowledge base like DBpedia. This ensures the agent has a - > baseline understanding of new terms. - > 3. **Knowledge Storage:** The summaries from the temporal orientation are - > stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - > creating a persistent, queryable knowledge artifact. - > 4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - > change is deemed significant (e.g., the addition of a new core - > architectural protocol), it programmatically triggers a formal L4 Deep - > Research Cycle by creating a `deep_research_required.json` file. - > - > This automated workflow ensures that the agent never operates with an outdated - > understanding of its own protocols. It closes the loop between protocol - > modification and the agent's self-awareness, making the system more robust, - > adaptive, and reliable. - -- **`tooling/research.py`**: - - > This module contains the logic for executing research tasks based on a set of - > constraints. It acts as a dispatcher, calling the appropriate tool (e.g., - > read_file, google_search) based on the specified target and scope. - -- **`tooling/research_planner.py`**: - - > This module is responsible for generating a formal, FSM-compliant research plan - > for a given topic. The output is a string that can be executed by the agent's - > master controller. - -- **`tooling/self_correction_orchestrator.py`**: - - > Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - > - > This script is the engine of the automated feedback loop. It reads structured, - > actionable lessons from `knowledge_core/lessons.jsonl` and uses the - > `protocol_updater.py` tool to apply them to the source protocol files. - -- **`tooling/self_improvement_cli.py`**: - - > Analyzes agent activity logs to identify opportunities for self-improvement. - > - > This script is a command-line tool that serves as a key part of the agent's - > meta-cognitive loop. It parses the structured activity log - > (`logs/activity.log.jsonl`) to identify patterns that may indicate - > inefficiencies or errors in the agent's workflow. - > - > The primary analysis currently implemented is: - > - **Planning Efficiency Analysis:** It scans the logs for tasks that required - > multiple `set_plan` actions. A high number of plan revisions for a single - > task can suggest that the initial planning phase was insufficient, the task - > was poorly understood, or the agent struggled to adapt to unforeseen - > challenges. - > - > By flagging these tasks, the script provides a starting point for a deeper - > post-mortem analysis, helping the agent (or its developers) to understand the - > root causes of the planning churn and to develop strategies for more effective - > upfront planning in the future. - > - > The tool is designed to be extensible, with future analyses (such as error - > rate tracking or tool usage anti-patterns) to be added as the system evolves. - -- **`tooling/standard_agents_compiler.py`**: - - > A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - > - > This script acts as an "adapter" to make the repository more accessible to - > third-party AI agents that expect a conventional set of instructions. While the - > repository's primary `AGENTS.md` is a complex, hierarchical, and - > machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` - > file produced by this script offers a simple, human-readable summary of the - > most common development commands. - > - > The script works by: - > 1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - > which is the single source of truth for high-level commands. It specifically - > extracts the exact commands for common targets like `install`, `test`, - > `lint`, and `format`. This ensures the generated instructions are never - > stale. - > 2. **Injecting into a Template:** It injects these extracted commands into a - > pre-defined, user-friendly Markdown template. - > 3. **Generating the Artifact:** The final output is written to - > `AGENTS.standard.md`, providing a simple, stable, and conventional entry - > point for external tools, effectively bridging the gap between the complex - > internal protocol system and the broader agent ecosystem. - -- **`tooling/state.py`**: - - > Defines the core data structures for managing the agent's state. - > - > This module provides the `AgentState` and `PlanContext` dataclasses, which are - > fundamental to the operation of the Context-Free Development Cycle (CFDC). These - > structures allow the `master_control.py` orchestrator to maintain a complete, - > snapshot-able representation of the agent's progress through a task. - > - > - `AgentState`: The primary container for all information related to the current - > task, including the plan execution stack, message history, and error states. - > - `PlanContext`: A specific structure that holds the state of a single plan - > file, including its content and the current execution step. This is the - > element that gets pushed onto the `plan_stack` in `AgentState`. - > - > Together, these classes enable the hierarchical, stack-based planning and - > execution that is the hallmark of the CFDC. - -- **`tooling/symbol_map_generator.py`**: - - > Generates a code symbol map for the repository to aid in contextual understanding. - > - > This script creates a `symbols.json` file in the `knowledge_core` directory, - > which acts as a high-level index of the codebase. This map contains information - > about key programming constructs like classes and functions, including their - > name, location (file path and line number), and language. - > - > The script employs a two-tiered approach for symbol generation: - > 1. **Universal Ctags (Preferred):** It first checks for the presence of the - > `ctags` command-line tool. If available, it uses `ctags` to perform a - > comprehensive, multi-language scan of the repository. This is the most - > robust and accurate method. - > 2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - > back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - > method parses all `.py` files and extracts symbol information for Python - > code. While less comprehensive than `ctags`, it ensures that a baseline - > symbol map is always available. - > - > The resulting `symbols.json` artifact is a critical input for the agent's - > orientation and planning phases, allowing it to quickly locate relevant code - > and understand the structure of the repository without having to read every file. - -- **`tooling/udc_orchestrator.py`**: - - > An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - > - > This script provides a sandboxed environment for running UDC plans, which are - > low-level assembly-like programs that can perform Turing-complete computations. - > The orchestrator acts as a virtual machine with a tape-based memory model, - > registers, and a set of simple instructions. - > - > To prevent non-termination and other resource-exhaustion issues, the - > orchestrator imposes strict limits on the number of instructions executed, - > the amount of memory used, and the total wall-clock time. - -## Experimental Framework - -The `experiments/` directory contains a framework for testing the agent's behavior in response to changes in its governing protocols (`AGENTS.md`). Each subdirectory within `experiments/` represents a self-contained experiment. - -### Running an Experiment - -To run an existing experiment (e.g., `scoped_protocol_override`): - -1. **Review the Experiment:** Read the `README.md` inside the experiment's directory (e.g., `experiments/scoped_protocol_override/README.md`) to understand its hypothesis, procedure, and expected outcome. -2. **Perform the Baseline Run:** Follow the instructions in the experiment's `README.md` to establish the agent's baseline behavior. This usually involves performing a task in the root directory. -3. **Perform the Experimental Run:** Follow the instructions to run the agent against the mutated protocol. This typically involves: - a. Copying the `mutation.md` file to a new `AGENTS.md` file within the experiment's directory. - b. Instructing the agent to perform the task specified in `task.md`, targeting the experiment's directory. -4. **Compare the Results:** Observe the difference in the agent's behavior between the baseline and experimental runs to verify the hypothesis. - -### Creating a New Experiment - -1. Create a new subdirectory in `experiments/`. -2. Add a `README.md` file explaining the new experiment's hypothesis and procedure. -3. Add a `mutation.md` file containing the altered `AGENTS.md` content. -4. Add a `task.md` file describing the task the agent should perform. - ---- - -# Module Documentation - -## Overview - -This document provides a human-readable summary of the protocols and key components defined within this module. It is automatically generated. - -## Core Protocols - -- **`dependency-management-001`**: A protocol for ensuring a reliable execution environment through formal dependency management. -- **`experimental-prologue-001`**: An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation. -- **`agent-shell-001`**: A protocol governing the use of the interactive agent shell as the primary entry point for all tasks. -- **`toolchain-review-on-schema-change-001`**: A meta-protocol to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols. -- **`unified-auditor-001`**: A protocol for the unified repository auditing tool, which combines multiple health and compliance checks into a single interface. -- **`aura-execution-001`**: A protocol for executing Aura scripts, enabling a more expressive and powerful planning and automation language for the agent. -- **`capability-verification-001`**: A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement. -- **`csdc-001`**: A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints. -- **`unified-doc-builder-001`**: A protocol for the unified documentation builder, which generates various documentation artifacts from the repository's sources of truth. -- **`file-indexing-001`**: A protocol for maintaining an up-to-date file index to accelerate tool performance. -- **`hdl-proving-001`**: A protocol for interacting with the Hypersequent-calculus-based logic engine, allowing the agent to perform formal logical proofs. -- **`agent-interaction-001`**: A protocol governing the agent's core interaction and planning tools. -- **`plllu-execution-001`**: A protocol for executing pLLLU scripts, enabling a more expressive and powerful planning and automation language for the agent. -- **`security-header`**: Defines the identity and purpose of the Security Protocol document. -- **`security-vuln-reporting-001`**: Defines the official policy and procedure for reporting security vulnerabilities. -- **`speculative-execution-001`**: A protocol that governs the agent's ability to initiate and execute self-generated, creative, or exploratory tasks during idle periods. - -## Key Components - -- **`tooling/__init__.py`**: - - > This module contains the various tools and utilities that support the agent's - > development, testing, and operational workflows. - > - > The tools in this package are the building blocks of the agent's capabilities, - > ranging from code analysis and refactoring to protocol compilation and - > self-correction. Each script is designed to be a self-contained unit of - > functionality that can be invoked either from the command line or programmatically - > by the agent's master control system. - > - > This __init__.py file marks the 'tooling' directory as a Python package, - > allowing for the organized import of its various modules. - -- **`tooling/agent_shell.py`**: - - > The new, interactive, API-driven entry point for the agent. - > - > This script replaces the old file-based signaling system with a direct, - > programmatic interface to the MasterControlGraph FSM. It is responsible for: - > 1. Initializing the agent's state and a centralized logger. - > 2. Instantiating and running the MasterControlGraph. - > 3. Driving the FSM by calling its methods and passing data and the logger. - > 4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - > and respond to requests for action. - -- **`tooling/__init__.py`**: - - > _No module-level docstring found._ - -- **`tooling/generate_and_test.py`**: - - > _No module-level docstring found._ - -- **`tooling/appl_runner.py`**: - - > A command-line tool for executing APPL files. - > - > This script provides a simple interface to run APPL files using the main - > `run.py` interpreter. It captures and prints the output of the execution, - > and provides detailed error reporting if the execution fails. - -- **`tooling/appl_to_lfi_ill.py`**: - - > A compiler that translates APPL (a simple functional language) to LFI-ILL. - > - > This script takes a Python file containing an APPL AST, and compiles it into - > an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - -- **`tooling/auditor.py`**: - - > A unified auditing tool for maintaining repository health and compliance. - > - > This script combines the functionality of several disparate auditing tools into a - > single, comprehensive command-line interface. It serves as the central tool for - > validating the key components of the agent's architecture, including protocols, - > plans, and documentation. - > - > The auditor can perform the following checks: - > 1. **Protocol Audit (`protocol`):** - > - Checks if `AGENTS.md` artifacts are stale compared to their source files. - > - Verifies protocol completeness by comparing tools used in logs against - > tools defined in protocols. - > - Analyzes tool usage frequency (centrality). - > 2. **Plan Registry Audit (`plans`):** - > - Scans `knowledge_core/plan_registry.json` for "dead links" where the - > target plan file does not exist. - > 3. **Documentation Audit (`docs`):** - > - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - > that are missing module-level docstrings. - > - > The tool is designed to be run from the command line and can execute specific - > audits or all of them, generating a consolidated `audit_report.md` file. - -- **`tooling/aura_executor.py`**: - - > This script serves as the command-line executor for `.aura` files. - > - > It bridges the gap between the high-level Aura scripting language and the - > agent's underlying Python-based toolset. The executor is responsible for: - > 1. Parsing the `.aura` source code using the lexer and parser from the - > `aura_lang` package. - > 2. Setting up an execution environment for the interpreter. - > 3. Injecting a "tool-calling" capability into the Aura environment, which - > allows Aura scripts to dynamically invoke registered Python tools - > (e.g., `hdl_prover`, `environmental_probe`). - > 4. Executing the parsed program and printing the final result. - > - > This makes it a key component for enabling more expressive and complex - > automation scripts for the agent. - -- **`tooling/aura_to_lfi_ill.py`**: - - > A compiler that translates AURA code to LFI-ILL. - > - > This script takes an AURA file, parses it, and compiles it into an LFI-ILL - > AST. The resulting AST is then written to a `.lfi_ill` file. - -- **`tooling/background_researcher.py`**: - - > This script performs a simulated research task in the background. - > It takes a task ID as a command-line argument and writes its findings - > to a temporary file that the main agent can poll. - -- **`tooling/builder.py`**: - - > A unified, configuration-driven build script for the project. - > - > This script serves as the central entry point for all build-related tasks, such - > as generating documentation, compiling protocols, and running code quality checks. - > It replaces a traditional Makefile's direct command execution with a more - > structured, maintainable, and introspectable approach. - > - > The core logic is driven by a `build_config.json` file, which defines a series - > of "targets." Each target specifies: - > - The `type` of target: "compiler" or "command". - > - For "compiler" types: `compiler` script, `output`, `sources`, and `options`. - > - For "command" types: the `command` to execute. - > - > The configuration also defines "build_groups", which are ordered collections of - > targets (e.g., "all", "quality"). - > - > This centralized builder provides several advantages: - > - **Single Source of Truth:** The `build_config.json` file is the definitive - > source for all build logic. - > - **Consistency:** Ensures all build tasks are executed in a uniform way. - > - **Extensibility:** New build targets can be added by simply updating the - > configuration file. - > - **Discoverability:** The script can list all available targets and groups. - -- **`tooling/capability_verifier.py`**: - - > A tool to verify that the agent can monotonically improve its capabilities. - > - > This script is designed to provide a formal, automated test for the agent's - > self-correction and learning mechanisms. It ensures that when the agent learns - > a new capability, it does so without losing (regressing) any of its existing - > capabilities. This is a critical safeguard for ensuring robust and reliable - > agent evolution. - > - > The tool works by orchestrating a four-step process: - > 1. **Confirm Initial Failure:** It runs a specific test file that is known to - > fail, verifying that the agent currently lacks the target capability. - > 2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - > triggers the `self_correction_orchestrator.py` script, which is responsible - > for integrating new knowledge and skills. - > 3. **Confirm Final Success:** It runs the same test file again, confirming that - > the agent has successfully learned the new capability and the test now passes. - > 4. **Check for Regressions:** It runs the full, existing test suite to ensure - > that the process of learning the new skill has not inadvertently broken any - > previously functional capabilities. - > - > This provides a closed-loop verification of monotonic improvement, which is a - > cornerstone of the agent's design philosophy. - -- **`tooling/code_suggester.py`**: - - > Handles the generation and application of autonomous code change suggestions. - > - > This tool is a key component of the advanced self-correction loop. It is - > designed to be invoked by the self-correction orchestrator when a lesson - > contains a 'propose-code-change' action. - > - > For its initial implementation, this tool acts as a structured executor. It - > takes a lesson where the 'details' field contains a fully-formed git-style - > merge diff and applies it to the target file. It does this by generating a - > temporary, single-step plan file and signaling its location for the master - > controller to execute. - > - > This establishes the fundamental workflow for autonomous code modification, - > decoupling the suggestion logic from the execution logic. Future iterations - > can enhance this tool with more sophisticated code generation capabilities - > (e.g., using an LLM to generate the diff from a natural language description) - > without altering the core orchestration process. - -- **`tooling/context_awareness_scanner.py`**: - - > A tool for performing static analysis on a Python file to understand its context. - > - > This script provides a "contextual awareness" scan of a specified Python file - > to help an agent (or a human) understand its role, dependencies, and connections - > within a larger codebase. This is crucial for planning complex changes or - > refactoring efforts, as it provides a snapshot of the potential impact of - > modifying a file. - > - > The scanner performs three main functions: - > 1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - > module to parse the target file and identify all the functions and classes - > that are defined within it. - > 2. **Import Analysis:** It also uses the AST to find all modules and symbols - > that the target file imports, revealing its dependencies on other parts of - > the codebase or external libraries. - > 3. **Reference Finding:** It performs a repository-wide search to find all other - > files that reference the symbols defined in the target file. This helps to - > understand how the file is used by the rest of the system. - > - > The final output is a detailed JSON report containing all of this information, - > which can be used as a foundational artifact for automated planning or human review. - -- **`tooling/csdc_cli.py`**: - - > A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - > - > This script provides an interface to validate a development plan against a specific - > CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a - > plan adheres to the strict logical and computational constraints defined by the - > CSDC protocol before it is executed. - > - > The tool performs two main checks: - > 1. **Complexity Analysis:** It analyzes the plan to determine its computational - > complexity and verifies that it matches the expected complexity class. - > 2. **Model Validation:** It validates the plan's commands against the rules of - > the specified CSDC model, ensuring that it does not violate any of the - > model's constraints (e.g., forbidding certain functions). - > - > This serves as a critical gateway for ensuring that all development work within - > the CSDC framework is sound, predictable, and compliant with the governing - > meta-mathematical principles. - -- **`tooling/dependency_graph_generator.py`**: - - > Scans the repository for dependency files and generates a unified dependency graph. - > - > This script is a crucial component of the agent's environmental awareness, - > providing a clear map of the software supply chain. It recursively searches the - > entire repository for common dependency management files, specifically: - > - `package.json` (for JavaScript/Node.js projects) - > - `requirements.txt` (for Python projects) - > - > It parses these files to identify two key types of relationships: - > 1. **Internal Dependencies:** Links between different projects within this repository. - > 2. **External Dependencies:** Links to third-party libraries and packages. - > - > The final output is a JSON file, `knowledge_core/dependency_graph.json`, which - > represents these relationships as a graph structure with nodes (projects and - > dependencies) and edges (the dependency links). This artifact is a primary - > input for the agent's orientation and planning phases, allowing it to reason - > about the potential impact of its changes. - -- **`tooling/doc_builder.py`**: - - > A unified documentation builder for the project. - > ... - -- **`tooling/document_scanner.py`**: - - > A tool for scanning the repository for human-readable documents and extracting their text content. - > - > This script is a crucial component of the agent's initial information-gathering - > and orientation phase. It allows the agent to ingest knowledge from unstructured - > or semi-structured documents that are not part of the formal codebase, but which - > may contain critical context, requirements, or specifications. - > - > The scanner searches a given directory for files with common document extensions: - > - `.pdf`: Uses the `pypdf` library to extract text from PDF files. - > - `.md`: Reads Markdown files. - > - `.txt`: Reads plain text files. - > - > The output is a dictionary where the keys are the file paths of the discovered - > documents and the values are their extracted text content. This data can then - > be used by the agent to inform its planning and execution process. This tool - > is essential for bridging the gap between human-written documentation and the - > agent's operational awareness. - -- **`tooling/environmental_probe.py`**: - - > Performs a series of checks to assess the capabilities of the execution environment. - > - > This script is a critical diagnostic tool run at the beginning of a task to - > ensure the agent understands its operational sandbox. It verifies fundamental - > capabilities required for most software development tasks: - > - > 1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - > and delete files. It also provides a basic latency measurement for these - > operations. - > 2. **Network Connectivity:** Checks for external network access by attempting to - > connect to a highly-available public endpoint (google.com). This is crucial - > for tasks requiring `git` operations, package downloads, or API calls. - > 3. **Environment Variables:** Verifies that standard environment variables are - > accessible, which is a prerequisite for many command-line tools. - > - > The script generates a human-readable report summarizing the results of these - > probes, allowing the agent to quickly identify any environmental constraints - > that might impact its ability to complete a task. - -- **`tooling/fdc_cli.py`**: - - > This script provides a command-line interface (CLI) for managing the Finite - > Development Cycle (FDC). - > - > The FDC is a structured workflow for agent-driven software development. This CLI - > is the primary human interface for interacting with that cycle, providing - > commands to: - > - **start:** Initiates a new development task, triggering the "Advanced - > Orientation and Research Protocol" (AORP) to ensure the agent is fully - > contextualized. - > - **close:** Formally concludes a task, creating a post-mortem template for - > analysis and lesson-learning. - > - **validate:** Checks a given plan file for both syntactic and semantic - > correctness against the FDC's governing Finite State Machine (FSM). This - > ensures that a plan is executable and will not violate protocol. - > - **analyze:** Examines a plan to determine its computational complexity (e.g., - > Constant, Polynomial, Exponential) and its modality (Read-Only vs. - > Read-Write), providing insight into the plan's potential impact. - -- **`tooling/filesystem_lister.py`**: - - > A tool for listing files and directories in a repository, with an option to respect .gitignore. - -- **`tooling/halting_heuristic_analyzer.py`**: - - > A static analysis tool to estimate the termination risk of a UDC plan. - > - > This script reads a `.udc` plan file, parses its instructions, and uses a - > series of heuristics to identify potential infinite loops. It is not a - > formal decider (as the halting problem is undecidable), but rather a - > practical tool to flag common patterns that lead to non-termination. - > - > The analysis focuses on: - > 1. Detecting backward jumps, which are the primary indicator of loops. - > 2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). - > 3. Checking if the registers involved in the exit conditions are modified - > within the loop body in a way that is likely to lead to termination. - > - > The tool outputs a JSON report detailing the estimated risk level (LOW, - > MEDIUM, HIGH) and the specific loops that were identified. - -- **`tooling/hdl_prover.py`**: - - > A command-line tool for proving sequents in Intuitionistic Linear Logic. - > - > This script provides a basic interface to a simple logic prover. It takes a - > sequent as a command-line argument, parses it into a logical structure, and - > then attempts to prove it using a rudimentary proof search algorithm. - > - > The primary purpose of this tool is to allow the agent to perform formal - > reasoning and verification tasks by checking the validity of logical entailments. - > For example, it can be used to verify that a certain conclusion follows from a - > set of premises according to the rules of linear logic. - > - > The current implementation uses a very basic parser and proof algorithm, - > serving as a placeholder and demonstration for a more sophisticated, underlying - > logic engine. - -- **`tooling/hierarchical_compiler.py`**: - - > A hierarchical build system for compiling nested protocol modules. - > - > This script orchestrates the compilation of `AGENTS.md` and `README.md` files - > across a repository with a nested or hierarchical module structure. It is a key - > component of the system's ability to manage complexity by allowing protocols to - > be defined in a modular, distributed way while still being presented as a unified, - > coherent whole at each level of the hierarchy. - > - > The compiler operates in two main passes: - > - > **Pass 1: Documentation Compilation (Bottom-Up)** - > 1. **Discovery:** It finds all `protocols` directories in the repository, which - > signify the root of a documentation module. - > 2. **Bottom-Up Traversal:** It processes these directories from the most deeply - > nested ones upwards. This ensures that child modules are always built before - > their parents. - > 3. **Child Summary Injection:** For each compiled child module, it generates a - > summary of its protocols and injects this summary into the parent's - > `protocols` directory as a temporary file. - > 4. **Parent Compilation:** When the parent module is compiled, the standard - > `protocol_compiler.py` automatically includes the injected child summaries, - > creating a single `AGENTS.md` file that contains both the parent's native - > protocols and the full protocols of all its direct children. - > 5. **README Generation:** After each `AGENTS.md` is compiled, the corresponding - > `README.md` is generated. - > - > **Pass 2: Centralized Knowledge Graph Compilation** - > 1. After all documentation is built, it performs a full repository scan to find - > every `*.protocol.json` file. - > 2. It parses all of these files and compiles them into a single, centralized - > RDF knowledge graph (`protocols.ttl`). This provides a unified, - > machine-readable view of every protocol defined anywhere in the system. - > - > This hierarchical approach allows for both localized, context-specific protocol - > definitions and a holistic, system-wide understanding of the agent's governing rules. - -- **`tooling/knowledge_compiler.py`**: - - > Extracts structured lessons from post-mortem reports and compiles them into a - > centralized, long-term knowledge base. - > - > This script is a core component of the agent's self-improvement feedback loop. - > After a task is completed, a post-mortem report is generated that includes a - > section for "Corrective Actions & Lessons Learned." This script automates the - > process of parsing that section to extract key insights. - > - > It identifies pairs of "Lesson" and "Action" statements and transforms them - > into a standardized, machine-readable format. These formatted entries are then - > appended to the `knowledge_core/lessons.jsonl` file, which serves as the - > agent's persistent memory of what has worked, what has failed, and what can be - > improved in future tasks. - > - > The script is executed via the command line, taking the path to a completed - > post-mortem file as its primary argument. - -- **`tooling/knowledge_integrator.py`**: - - > Enriches the local knowledge graph with data from external sources like DBPedia. - > - > This script loads the RDF graph generated from the project's protocols, - > identifies key concepts (like tools and rules), queries the DBPedia SPARQL - > endpoint to find related information, and merges the external data into a new, - > enriched knowledge graph. - -- **`tooling/lba_validator.py`**: - - > A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - > - > This module implements a validator that enforces the context-sensitive rules of the CSDC. - > Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make - > validation decisions. This is necessary to enforce rules where the validity of one - > command depends on the presence or absence of another command elsewhere in the plan. - > - > The CSDC defines two mutually exclusive models: - > - Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. - > - Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - > - > This validator checks for these co-occurrence constraints. - -- **`tooling/lfi_ill_halting_decider.py`**: - - > A tool for analyzing the termination of LFI-ILL programs. - > - > This script takes an LFI-ILL file, interprets it in a paraconsistent logic - > environment, and reports on its halting status. It does this by setting up - > a paradoxical initial state and observing how the program resolves it. - -- **`tooling/lfi_udc_model.py`**: - - > A paraconsistent execution model for UDC plans. - > - > This module provides the classes necessary to interpret a UDC (Un-decidable - > Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of - > concrete values, the state of the machine (registers, tape, etc.) is modeled - > using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - > - > This allows the system to reason about paradoxical programs, such as a program - > that halts if and only if it does not halt. By executing the program under - > paraconsistent semantics, the model can arrive at a final state of `BOTH`, - > effectively demonstrating the paradoxical nature of the input without crashing. - > - > 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. - > - `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - > analysis of a UDC plan. - -- **`tooling/log_failure.py`**: - - > A dedicated script to log a catastrophic failure event to the main activity log. - > - > This tool is designed to be invoked in the rare case of a severe, unrecoverable - > error that violates a core protocol. Its primary purpose is to ensure that such - > a critical event is formally and structurally documented in the standard agent - > activity log (`logs/activity.log.jsonl`), even if the main agent loop has - > crashed or been terminated. - > - > The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically - > attributing it to the "Unauthorized use of the `reset_all` tool." This creates a - > permanent, machine-readable record of the failure, which is essential for - > post-mortem analysis, debugging, and the development of future safeguards. - > - > By using the standard `Logger` class, it ensures that the failure log entry - > conforms to the established `LOGGING_SCHEMA.md`, making it processable by - > auditing and analysis tools. - -- **`tooling/master_control.py`**: - - > The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - > - > This script, master_control.py, is the heart of the agent's operational loop. - > It implements the CFDC, a hierarchical planning and execution model based on a - > Pushdown Automaton. This allows the agent to execute complex tasks by calling - > plans as sub-routines. - > - > Core Responsibilities: - > - **Hierarchical Plan Execution:** Manages a plan execution stack to enable - > plans to call other plans via the `call_plan` directive. This allows for - > modular, reusable, and complex task decomposition. A maximum recursion depth - > is enforced to guarantee decidability. - > - **Plan Validation:** Contains the in-memory plan validator. Before execution, - > it parses a plan and simulates its execution against a Finite State Machine - > (FSM) to ensure it complies with the agent's operational protocols. - > - **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - > it first attempts to look up the plan by its logical name in the - > `knowledge_core/plan_registry.json`. If not found, it falls back to treating - > the argument as a direct file path. - > - **FSM-Governed Lifecycle:** The entire workflow, from orientation to - > finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - > to ensure predictable and auditable behavior. - > - > This module is designed as a library to be controlled by an external shell - > (e.g., `agent_shell.py`), making its interaction purely programmatic. - -- **`tooling/master_control_cli.py`**: - - > The official command-line interface for the agent's master control loop. - > - > This script is now a lightweight wrapper that passes control to the new, - > API-driven `agent_shell.py`. It preserves the command-line interface while - > decoupling the entry point from the FSM implementation. - -- **`tooling/message_user.py`**: - - > A dummy tool that prints its arguments to simulate the message_user tool. - > - > This script is a simple command-line utility that takes a string as an - > argument and prints it to standard output, prefixed with "[Message User]:". - > Its purpose is to serve as a stand-in or mock for the actual `message_user` - > tool in testing environments where the full agent framework is not required. - > - > This allows for the testing of scripts or workflows that call the - > `message_user` tool without needing to invoke the entire agent messaging - > subsystem. - -- **`tooling/pda_parser.py`**: - - > A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - > - > This script uses the PLY (Python Lex-Yacc) library to define a lexer and a - > parser for a simple, string-based representation of pLLLU formulas. It can - > handle basic atomic formulas, unary operators (like negation and consistency), - > and binary operators (like implication and conjunction). - > - > The main function `parse_formula` takes a string and returns a simple AST - > (Abstract Syntax Tree) represented as nested tuples. - -- **`tooling/plan_executor.py`**: - - > A simple plan executor for simulating agent behavior. - > - > This script reads a plan file, parses it, and executes the commands in a - > simplified, simulated environment. It supports a limited set of tools - > (`message_user` and `run_in_bash_session`) to provide a basic demonstration - > of how an agent would execute a plan. - -- **`tooling/plan_manager.py`**: - - > Provides a command-line interface for managing the agent's Plan Registry. - > - > This script is the administrative tool for the Plan Registry, a key component - > of the Context-Free Development Cycle (CFDC) that enables hierarchical and - > modular planning. The registry, located at `knowledge_core/plan_registry.json`, - > maps human-readable, logical names to the file paths of specific plans. This - > decouples the `call_plan` directive from hardcoded file paths, making plans - > more reusable and the system more robust. - > - > This CLI provides three essential functions: - > - **register**: Associates a new logical name with a plan file path, adding it - > to the central registry. - > - **deregister**: Removes an existing logical name and its associated path from - > the registry. - > - **list**: Displays all current name-to-path mappings in the registry. - > - > By providing a simple, standardized interface for managing this library of - > reusable plans, this tool improves the agent's ability to compose complex - > workflows from smaller, validated sub-plans. - -- **`tooling/plan_parser.py`**: - - > Parses a plan file into a structured list of commands. - > - > This module provides the `parse_plan` function and the `Command` dataclass, - > which are central to the agent's ability to understand and execute plans. - > The parser correctly handles multi-line arguments and ignores comments, - > allowing for robust and readable plan files. - -- **`tooling/plllu_interpreter.py`**: - - > A resource-sensitive, four-valued interpreter for pLLLU formulas. - > - > This script implements an interpreter for the pLLLU language. It operates on - > an AST generated by the `pda_parser.py` script. The interpreter is designed - > to be resource-sensitive, meaning that each atomic formula in the initial - > context must be consumed exactly once during the evaluation of the proof. - > - > The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing - > it to reason about paraconsistent and paracomplete states. - > - > The core of the interpreter is the `FourValuedInterpreter` class, which - > recursively walks the AST, consuming resources from a context (a Counter of - > available atoms) and returning the resulting logical value. - -- **`tooling/plllu_runner.py`**: - - > A command-line runner for pLLLU files. - > - > This script provides an entry point for executing `.plllu` files. It - > integrates the pLLLU lexer, parser, and interpreter to execute the logic - > defined in a given pLLLU source file and print the result. - -- **`tooling/pre_submit_check.py`**: - - > _No module-level docstring found._ - -- **`tooling/protocol_compiler.py`**: - - > Compiles source protocol files into unified, human-readable and machine-readable artifacts. - > - > This script is the engine behind the "protocol as code" principle. It discovers, - > validates, and assembles protocol definitions from a source directory (e.g., `protocols/`) - > into high-level documents like `AGENTS.md`. - > - > Key Functions: - > - **Discovery:** Scans a directory for source files, including `.protocol.json` - > (machine-readable rules) and `.protocol.md` (human-readable context). - > - **Validation:** Uses a JSON schema (`protocol.schema.json`) to validate every - > `.protocol.json` file, ensuring all protocol definitions are syntactically - > correct and adhere to the established structure. - > - **Compilation:** Combines the human-readable markdown and the machine-readable - > JSON into a single, cohesive Markdown file, embedding the JSON in code blocks. - > - **Documentation Injection:** Can inject other generated documents, like the - > `SYSTEM_DOCUMENTATION.md`, into the final output at specified locations. - > - **Knowledge Graph Generation:** Optionally, it can process the validated JSON - > protocols and serialize them into an RDF knowledge graph (in Turtle format), - > creating a machine-queryable version of the agent's governing rules. - > - > This process ensures that `AGENTS.md` and other protocol documents are not edited - > manually but are instead generated from a validated, single source of truth, - > making the agent's protocols robust, verifiable, and maintainable. - -- **`tooling/protocol_updater.py`**: - - > A command-line tool for programmatically updating protocol source files. - > - > This script provides the mechanism for the agent to perform self-correction - > by modifying its own governing protocols based on structured, actionable - > lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) - > workflow. - > - > The tool operates on the .protocol.json files located in the `protocols/` - > directory, performing targeted updates based on command-line arguments. - -- **`tooling/refactor.py`**: - - > A tool for performing automated symbol renaming in Python code. - > - > This script provides a command-line interface to find a specific symbol - > (a function or a class) in a given Python file and rename it, along with all of - > its textual references throughout the entire repository. This provides a safe - > and automated way to perform a common refactoring task, reducing the risk of - > manual errors. - > - > The tool operates in three main stages: - > 1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - > to parse the source file and precisely locate the definition of the target - > symbol. This ensures that the tool is targeting the correct code construct. - > 2. **Reference Finding:** It performs a text-based search across the specified - > search path (defaulting to the entire repository) to find all files that - > mention the symbol's old name. - > 3. **Plan Generation:** Instead of modifying files directly, it generates a - > refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - > commands, one for each file that needs to be changed. The path to this - > generated plan file is printed to standard output. - > - > This plan-based approach allows the agent's master controller to execute the - > refactoring in a controlled, verifiable, and atomic way, consistent with its - > standard operational procedures. - -- **`tooling/reliable_ls.py`**: - - > A tool for reliably listing files and directories. - > - > This script provides a consistent, sorted, and recursive listing of files and - > directories, excluding the `.git` directory. It is intended to be a more - > reliable alternative to the standard `ls` command for agent use cases. - -- **`tooling/reorientation_manager.py`**: - - > Re-orientation Manager - > - > This script is the core of the automated re-orientation process. It is - > designed to be triggered by the build system whenever the agent's core - > protocols (`AGENTS.md`) are re-compiled. - > - > The manager performs the following key functions: - > 1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - > version to identify new protocols, tools, or other key concepts that have - > been introduced. - > 2. **Temporal Orientation (Shallow Research):** For each new concept, it - > invokes the `temporal_orienter.py` tool to fetch a high-level summary from - > an external knowledge base like DBpedia. This ensures the agent has a - > baseline understanding of new terms. - > 3. **Knowledge Storage:** The summaries from the temporal orientation are - > stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - > creating a persistent, queryable knowledge artifact. - > 4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - > change is deemed significant (e.g., the addition of a new core - > architectural protocol), it programmatically triggers a formal L4 Deep - > Research Cycle by creating a `deep_research_required.json` file. - > - > This automated workflow ensures that the agent never operates with an outdated - > understanding of its own protocols. It closes the loop between protocol - > modification and the agent's self-awareness, making the system more robust, - > adaptive, and reliable. - -- **`tooling/research.py`**: - - > This module contains the logic for executing research tasks based on a set of - > constraints. It acts as a dispatcher, calling the appropriate tool (e.g., - > read_file, google_search) based on the specified target and scope. - -- **`tooling/research_planner.py`**: - - > This module is responsible for generating a formal, FSM-compliant research plan - > for a given topic. The output is a string that can be executed by the agent's - > master controller. - -- **`tooling/self_correction_orchestrator.py`**: - - > Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - > - > This script is the engine of the automated feedback loop. It reads structured, - > actionable lessons from `knowledge_core/lessons.jsonl` and uses the - > `protocol_updater.py` tool to apply them to the source protocol files. - -- **`tooling/self_improvement_cli.py`**: - - > Analyzes agent activity logs to identify opportunities for self-improvement. - > - > This script is a command-line tool that serves as a key part of the agent's - > meta-cognitive loop. It parses the structured activity log - > (`logs/activity.log.jsonl`) to identify patterns that may indicate - > inefficiencies or errors in the agent's workflow. - > - > The primary analysis currently implemented is: - > - **Planning Efficiency Analysis:** It scans the logs for tasks that required - > multiple `set_plan` actions. A high number of plan revisions for a single - > task can suggest that the initial planning phase was insufficient, the task - > was poorly understood, or the agent struggled to adapt to unforeseen - > challenges. - > - > By flagging these tasks, the script provides a starting point for a deeper - > post-mortem analysis, helping the agent (or its developers) to understand the - > root causes of the planning churn and to develop strategies for more effective - > upfront planning in the future. - > - > The tool is designed to be extensible, with future analyses (such as error - > rate tracking or tool usage anti-patterns) to be added as the system evolves. - -- **`tooling/standard_agents_compiler.py`**: - - > A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - > - > This script acts as an "adapter" to make the repository more accessible to - > third-party AI agents that expect a conventional set of instructions. While the - > repository's primary `AGENTS.md` is a complex, hierarchical, and - > machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` - > file produced by this script offers a simple, human-readable summary of the - > most common development commands. - > - > The script works by: - > 1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - > which is the single source of truth for high-level commands. It specifically - > extracts the exact commands for common targets like `install`, `test`, - > `lint`, and `format`. This ensures the generated instructions are never - > stale. - > 2. **Injecting into a Template:** It injects these extracted commands into a - > pre-defined, user-friendly Markdown template. - > 3. **Generating the Artifact:** The final output is written to - > `AGENTS.standard.md`, providing a simple, stable, and conventional entry - > point for external tools, effectively bridging the gap between the complex - > internal protocol system and the broader agent ecosystem. - -- **`tooling/state.py`**: - - > Defines the core data structures for managing the agent's state. - > - > This module provides the `AgentState` and `PlanContext` dataclasses, which are - > fundamental to the operation of the Context-Free Development Cycle (CFDC). These - > structures allow the `master_control.py` orchestrator to maintain a complete, - > snapshot-able representation of the agent's progress through a task. - > - > - `AgentState`: The primary container for all information related to the current - > task, including the plan execution stack, message history, and error states. - > - `PlanContext`: A specific structure that holds the state of a single plan - > file, including its content and the current execution step. This is the - > element that gets pushed onto the `plan_stack` in `AgentState`. - > - > Together, these classes enable the hierarchical, stack-based planning and - > execution that is the hallmark of the CFDC. - -- **`tooling/symbol_map_generator.py`**: - - > Generates a code symbol map for the repository to aid in contextual understanding. - > - > This script creates a `symbols.json` file in the `knowledge_core` directory, - > which acts as a high-level index of the codebase. This map contains information - > about key programming constructs like classes and functions, including their - > name, location (file path and line number), and language. - > - > The script employs a two-tiered approach for symbol generation: - > 1. **Universal Ctags (Preferred):** It first checks for the presence of the - > `ctags` command-line tool. If available, it uses `ctags` to perform a - > comprehensive, multi-language scan of the repository. This is the most - > robust and accurate method. - > 2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - > back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - > method parses all `.py` files and extracts symbol information for Python - > code. While less comprehensive than `ctags`, it ensures that a baseline - > symbol map is always available. - > - > The resulting `symbols.json` artifact is a critical input for the agent's - > orientation and planning phases, allowing it to quickly locate relevant code - > and understand the structure of the repository without having to read every file. - -- **`tooling/udc_orchestrator.py`**: - - > An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - > - > This script provides a sandboxed environment for running UDC plans, which are - > low-level assembly-like programs that can perform Turing-complete computations. - > The orchestrator acts as a virtual machine with a tape-based memory model, - > registers, and a set of simple instructions. - > - > To prevent non-termination and other resource-exhaustion issues, the - > orchestrator imposes strict limits on the number of instructions executed, - > the amount of memory used, and the total wall-clock time. - -## Experimental Framework - -The `experiments/` directory contains a framework for testing the agent's behavior in response to changes in its governing protocols (`AGENTS.md`). Each subdirectory within `experiments/` represents a self-contained experiment. - -### Running an Experiment - -To run an existing experiment (e.g., `scoped_protocol_override`): - -1. **Review the Experiment:** Read the `README.md` inside the experiment's directory (e.g., `experiments/scoped_protocol_override/README.md`) to understand its hypothesis, procedure, and expected outcome. -2. **Perform the Baseline Run:** Follow the instructions in the experiment's `README.md` to establish the agent's baseline behavior. This usually involves performing a task in the root directory. -3. **Perform the Experimental Run:** Follow the instructions to run the agent against the mutated protocol. This typically involves: - a. Copying the `mutation.md` file to a new `AGENTS.md` file within the experiment's directory. - b. Instructing the agent to perform the task specified in `task.md`, targeting the experiment's directory. -4. **Compare the Results:** Observe the difference in the agent's behavior between the baseline and experimental runs to verify the hypothesis. - -### Creating a New Experiment - -1. Create a new subdirectory in `experiments/`. -2. Add a `README.md` file explaining the new experiment's hypothesis and procedure. -3. Add a `mutation.md` file containing the altered `AGENTS.md` content. -4. Add a `task.md` file describing the task the agent should perform. - ---- - -# Module Documentation - -## Overview - -This document provides a human-readable summary of the protocols and key components defined within this module. It is automatically generated. - -## Core Protocols - -- **`dependency-management-001`**: A protocol for ensuring a reliable execution environment through formal dependency management. -- **`experimental-prologue-001`**: An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation. -- **`agent-shell-001`**: A protocol governing the use of the interactive agent shell as the primary entry point for all tasks. -- **`toolchain-review-on-schema-change-001`**: A meta-protocol to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols. -- **`unified-auditor-001`**: A protocol for the unified repository auditing tool, which combines multiple health and compliance checks into a single interface. -- **`aura-execution-001`**: A protocol for executing Aura scripts, enabling a more expressive and powerful planning and automation language for the agent. -- **`capability-verification-001`**: A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement. -- **`csdc-001`**: A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints. -- **`unified-doc-builder-001`**: A protocol for the unified documentation builder, which generates various documentation artifacts from the repository's sources of truth. -- **`file-indexing-001`**: A protocol for maintaining an up-to-date file index to accelerate tool performance. -- **`hdl-proving-001`**: A protocol for interacting with the Hypersequent-calculus-based logic engine, allowing the agent to perform formal logical proofs. -- **`agent-interaction-001`**: A protocol governing the agent's core interaction and planning tools. -- **`plllu-execution-001`**: A protocol for executing pLLLU scripts, enabling a more expressive and powerful planning and automation language for the agent. -- **`security-header`**: Defines the identity and purpose of the Security Protocol document. -- **`security-vuln-reporting-001`**: Defines the official policy and procedure for reporting security vulnerabilities. -- **`speculative-execution-001`**: A protocol that governs the agent's ability to initiate and execute self-generated, creative, or exploratory tasks during idle periods. - -## Key Components - -- **`tooling/__init__.py`**: - - > This module contains the various tools and utilities that support the agent's - > development, testing, and operational workflows. - > - > The tools in this package are the building blocks of the agent's capabilities, - > ranging from code analysis and refactoring to protocol compilation and - > self-correction. Each script is designed to be a self-contained unit of - > functionality that can be invoked either from the command line or programmatically - > by the agent's master control system. - > - > This __init__.py file marks the 'tooling' directory as a Python package, - > allowing for the organized import of its various modules. - -- **`tooling/agent_shell.py`**: - - > The new, interactive, API-driven entry point for the agent. - > - > This script replaces the old file-based signaling system with a direct, - > programmatic interface to the MasterControlGraph FSM. It is responsible for: - > 1. Initializing the agent's state and a centralized logger. - > 2. Instantiating and running the MasterControlGraph. - > 3. Driving the FSM by calling its methods and passing data and the logger. - > 4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - > and respond to requests for action. - -- **`tooling/__init__.py`**: - - > _No module-level docstring found._ - -- **`tooling/generate_and_test.py`**: - - > _No module-level docstring found._ - -- **`tooling/appl_runner.py`**: - - > A command-line tool for executing APPL files. - > - > This script provides a simple interface to run APPL files using the main - > `run.py` interpreter. It captures and prints the output of the execution, - > and provides detailed error reporting if the execution fails. - -- **`tooling/appl_to_lfi_ill.py`**: - - > A compiler that translates APPL (a simple functional language) to LFI-ILL. - > - > This script takes a Python file containing an APPL AST, and compiles it into - > an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - -- **`tooling/auditor.py`**: - - > A unified auditing tool for maintaining repository health and compliance. - > - > This script combines the functionality of several disparate auditing tools into a - > single, comprehensive command-line interface. It serves as the central tool for - > validating the key components of the agent's architecture, including protocols, - > plans, and documentation. - > - > The auditor can perform the following checks: - > 1. **Protocol Audit (`protocol`):** - > - Checks if `AGENTS.md` artifacts are stale compared to their source files. - > - Verifies protocol completeness by comparing tools used in logs against - > tools defined in protocols. - > - Analyzes tool usage frequency (centrality). - > 2. **Plan Registry Audit (`plans`):** - > - Scans `knowledge_core/plan_registry.json` for "dead links" where the - > target plan file does not exist. - > 3. **Documentation Audit (`docs`):** - > - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - > that are missing module-level docstrings. - > - > The tool is designed to be run from the command line and can execute specific - > audits or all of them, generating a consolidated `audit_report.md` file. - -- **`tooling/aura_executor.py`**: - - > This script serves as the command-line executor for `.aura` files. - > - > It bridges the gap between the high-level Aura scripting language and the - > agent's underlying Python-based toolset. The executor is responsible for: - > 1. Parsing the `.aura` source code using the lexer and parser from the - > `aura_lang` package. - > 2. Setting up an execution environment for the interpreter. - > 3. Injecting a "tool-calling" capability into the Aura environment, which - > allows Aura scripts to dynamically invoke registered Python tools - > (e.g., `hdl_prover`, `environmental_probe`). - > 4. Executing the parsed program and printing the final result. - > - > This makes it a key component for enabling more expressive and complex - > automation scripts for the agent. - -- **`tooling/aura_to_lfi_ill.py`**: - - > A compiler that translates AURA code to LFI-ILL. - > - > This script takes an AURA file, parses it, and compiles it into an LFI-ILL - > AST. The resulting AST is then written to a `.lfi_ill` file. - -- **`tooling/background_researcher.py`**: - - > This script performs a simulated research task in the background. - > It takes a task ID as a command-line argument and writes its findings - > to a temporary file that the main agent can poll. - -- **`tooling/builder.py`**: - - > A unified, configuration-driven build script for the project. - > - > This script serves as the central entry point for all build-related tasks, such - > as generating documentation, compiling protocols, and running code quality checks. - > It replaces a traditional Makefile's direct command execution with a more - > structured, maintainable, and introspectable approach. - > - > The core logic is driven by a `build_config.json` file, which defines a series - > of "targets." Each target specifies: - > - The `type` of target: "compiler" or "command". - > - For "compiler" types: `compiler` script, `output`, `sources`, and `options`. - > - For "command" types: the `command` to execute. - > - > The configuration also defines "build_groups", which are ordered collections of - > targets (e.g., "all", "quality"). - > - > This centralized builder provides several advantages: - > - **Single Source of Truth:** The `build_config.json` file is the definitive - > source for all build logic. - > - **Consistency:** Ensures all build tasks are executed in a uniform way. - > - **Extensibility:** New build targets can be added by simply updating the - > configuration file. - > - **Discoverability:** The script can list all available targets and groups. - -- **`tooling/capability_verifier.py`**: - - > A tool to verify that the agent can monotonically improve its capabilities. - > - > This script is designed to provide a formal, automated test for the agent's - > self-correction and learning mechanisms. It ensures that when the agent learns - > a new capability, it does so without losing (regressing) any of its existing - > capabilities. This is a critical safeguard for ensuring robust and reliable - > agent evolution. - > - > The tool works by orchestrating a four-step process: - > 1. **Confirm Initial Failure:** It runs a specific test file that is known to - > fail, verifying that the agent currently lacks the target capability. - > 2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - > triggers the `self_correction_orchestrator.py` script, which is responsible - > for integrating new knowledge and skills. - > 3. **Confirm Final Success:** It runs the same test file again, confirming that - > the agent has successfully learned the new capability and the test now passes. - > 4. **Check for Regressions:** It runs the full, existing test suite to ensure - > that the process of learning the new skill has not inadvertently broken any - > previously functional capabilities. - > - > This provides a closed-loop verification of monotonic improvement, which is a - > cornerstone of the agent's design philosophy. - -- **`tooling/code_suggester.py`**: - - > Handles the generation and application of autonomous code change suggestions. - > - > This tool is a key component of the advanced self-correction loop. It is - > designed to be invoked by the self-correction orchestrator when a lesson - > contains a 'propose-code-change' action. - > - > For its initial implementation, this tool acts as a structured executor. It - > takes a lesson where the 'details' field contains a fully-formed git-style - > merge diff and applies it to the target file. It does this by generating a - > temporary, single-step plan file and signaling its location for the master - > controller to execute. - > - > This establishes the fundamental workflow for autonomous code modification, - > decoupling the suggestion logic from the execution logic. Future iterations - > can enhance this tool with more sophisticated code generation capabilities - > (e.g., using an LLM to generate the diff from a natural language description) - > without altering the core orchestration process. - -- **`tooling/context_awareness_scanner.py`**: - - > A tool for performing static analysis on a Python file to understand its context. - > - > This script provides a "contextual awareness" scan of a specified Python file - > to help an agent (or a human) understand its role, dependencies, and connections - > within a larger codebase. This is crucial for planning complex changes or - > refactoring efforts, as it provides a snapshot of the potential impact of - > modifying a file. - > - > The scanner performs three main functions: - > 1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - > module to parse the target file and identify all the functions and classes - > that are defined within it. - > 2. **Import Analysis:** It also uses the AST to find all modules and symbols - > that the target file imports, revealing its dependencies on other parts of - > the codebase or external libraries. - > 3. **Reference Finding:** It performs a repository-wide search to find all other - > files that reference the symbols defined in the target file. This helps to - > understand how the file is used by the rest of the system. - > - > The final output is a detailed JSON report containing all of this information, - > which can be used as a foundational artifact for automated planning or human review. - -- **`tooling/csdc_cli.py`**: - - > A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - > - > This script provides an interface to validate a development plan against a specific - > CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a - > plan adheres to the strict logical and computational constraints defined by the - > CSDC protocol before it is executed. - > - > The tool performs two main checks: - > 1. **Complexity Analysis:** It analyzes the plan to determine its computational - > complexity and verifies that it matches the expected complexity class. - > 2. **Model Validation:** It validates the plan's commands against the rules of - > the specified CSDC model, ensuring that it does not violate any of the - > model's constraints (e.g., forbidding certain functions). - > - > This serves as a critical gateway for ensuring that all development work within - > the CSDC framework is sound, predictable, and compliant with the governing - > meta-mathematical principles. - -- **`tooling/dependency_graph_generator.py`**: - - > Scans the repository for dependency files and generates a unified dependency graph. - > - > This script is a crucial component of the agent's environmental awareness, - > providing a clear map of the software supply chain. It recursively searches the - > entire repository for common dependency management files, specifically: - > - `package.json` (for JavaScript/Node.js projects) - > - `requirements.txt` (for Python projects) - > - > It parses these files to identify two key types of relationships: - > 1. **Internal Dependencies:** Links between different projects within this repository. - > 2. **External Dependencies:** Links to third-party libraries and packages. - > - > The final output is a JSON file, `knowledge_core/dependency_graph.json`, which - > represents these relationships as a graph structure with nodes (projects and - > dependencies) and edges (the dependency links). This artifact is a primary - > input for the agent's orientation and planning phases, allowing it to reason - > about the potential impact of its changes. - -- **`tooling/doc_builder.py`**: - - > A unified documentation builder for the project. - > ... - -- **`tooling/document_scanner.py`**: - - > A tool for scanning the repository for human-readable documents and extracting their text content. - > - > This script is a crucial component of the agent's initial information-gathering - > and orientation phase. It allows the agent to ingest knowledge from unstructured - > or semi-structured documents that are not part of the formal codebase, but which - > may contain critical context, requirements, or specifications. - > - > The scanner searches a given directory for files with common document extensions: - > - `.pdf`: Uses the `pypdf` library to extract text from PDF files. - > - `.md`: Reads Markdown files. - > - `.txt`: Reads plain text files. - > - > The output is a dictionary where the keys are the file paths of the discovered - > documents and the values are their extracted text content. This data can then - > be used by the agent to inform its planning and execution process. This tool - > is essential for bridging the gap between human-written documentation and the - > agent's operational awareness. - -- **`tooling/environmental_probe.py`**: - - > Performs a series of checks to assess the capabilities of the execution environment. - > - > This script is a critical diagnostic tool run at the beginning of a task to - > ensure the agent understands its operational sandbox. It verifies fundamental - > capabilities required for most software development tasks: - > - > 1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - > and delete files. It also provides a basic latency measurement for these - > operations. - > 2. **Network Connectivity:** Checks for external network access by attempting to - > connect to a highly-available public endpoint (google.com). This is crucial - > for tasks requiring `git` operations, package downloads, or API calls. - > 3. **Environment Variables:** Verifies that standard environment variables are - > accessible, which is a prerequisite for many command-line tools. - > - > The script generates a human-readable report summarizing the results of these - > probes, allowing the agent to quickly identify any environmental constraints - > that might impact its ability to complete a task. - -- **`tooling/fdc_cli.py`**: - - > This script provides a command-line interface (CLI) for managing the Finite - > Development Cycle (FDC). - > - > The FDC is a structured workflow for agent-driven software development. This CLI - > is the primary human interface for interacting with that cycle, providing - > commands to: - > - **start:** Initiates a new development task, triggering the "Advanced - > Orientation and Research Protocol" (AORP) to ensure the agent is fully - > contextualized. - > - **close:** Formally concludes a task, creating a post-mortem template for - > analysis and lesson-learning. - > - **validate:** Checks a given plan file for both syntactic and semantic - > correctness against the FDC's governing Finite State Machine (FSM). This - > ensures that a plan is executable and will not violate protocol. - > - **analyze:** Examines a plan to determine its computational complexity (e.g., - > Constant, Polynomial, Exponential) and its modality (Read-Only vs. - > Read-Write), providing insight into the plan's potential impact. - -- **`tooling/filesystem_lister.py`**: - - > A tool for listing files and directories in a repository, with an option to respect .gitignore. - -- **`tooling/halting_heuristic_analyzer.py`**: - - > A static analysis tool to estimate the termination risk of a UDC plan. - > - > This script reads a `.udc` plan file, parses its instructions, and uses a - > series of heuristics to identify potential infinite loops. It is not a - > formal decider (as the halting problem is undecidable), but rather a - > practical tool to flag common patterns that lead to non-termination. - > - > The analysis focuses on: - > 1. Detecting backward jumps, which are the primary indicator of loops. - > 2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). - > 3. Checking if the registers involved in the exit conditions are modified - > within the loop body in a way that is likely to lead to termination. - > - > The tool outputs a JSON report detailing the estimated risk level (LOW, - > MEDIUM, HIGH) and the specific loops that were identified. - -- **`tooling/hdl_prover.py`**: - - > A command-line tool for proving sequents in Intuitionistic Linear Logic. - > - > This script provides a basic interface to a simple logic prover. It takes a - > sequent as a command-line argument, parses it into a logical structure, and - > then attempts to prove it using a rudimentary proof search algorithm. - > - > The primary purpose of this tool is to allow the agent to perform formal - > reasoning and verification tasks by checking the validity of logical entailments. - > For example, it can be used to verify that a certain conclusion follows from a - > set of premises according to the rules of linear logic. - > - > The current implementation uses a very basic parser and proof algorithm, - > serving as a placeholder and demonstration for a more sophisticated, underlying - > logic engine. - -- **`tooling/hierarchical_compiler.py`**: - - > A hierarchical build system for compiling nested protocol modules. - > - > This script orchestrates the compilation of `AGENTS.md` and `README.md` files - > across a repository with a nested or hierarchical module structure. It is a key - > component of the system's ability to manage complexity by allowing protocols to - > be defined in a modular, distributed way while still being presented as a unified, - > coherent whole at each level of the hierarchy. - > - > The compiler operates in two main passes: - > - > **Pass 1: Documentation Compilation (Bottom-Up)** - > 1. **Discovery:** It finds all `protocols` directories in the repository, which - > signify the root of a documentation module. - > 2. **Bottom-Up Traversal:** It processes these directories from the most deeply - > nested ones upwards. This ensures that child modules are always built before - > their parents. - > 3. **Child Summary Injection:** For each compiled child module, it generates a - > summary of its protocols and injects this summary into the parent's - > `protocols` directory as a temporary file. - > 4. **Parent Compilation:** When the parent module is compiled, the standard - > `protocol_compiler.py` automatically includes the injected child summaries, - > creating a single `AGENTS.md` file that contains both the parent's native - > protocols and the full protocols of all its direct children. - > 5. **README Generation:** After each `AGENTS.md` is compiled, the corresponding - > `README.md` is generated. - > - > **Pass 2: Centralized Knowledge Graph Compilation** - > 1. After all documentation is built, it performs a full repository scan to find - > every `*.protocol.json` file. - > 2. It parses all of these files and compiles them into a single, centralized - > RDF knowledge graph (`protocols.ttl`). This provides a unified, - > machine-readable view of every protocol defined anywhere in the system. - > - > This hierarchical approach allows for both localized, context-specific protocol - > definitions and a holistic, system-wide understanding of the agent's governing rules. - -- **`tooling/knowledge_compiler.py`**: - - > Extracts structured lessons from post-mortem reports and compiles them into a - > centralized, long-term knowledge base. - > - > This script is a core component of the agent's self-improvement feedback loop. - > After a task is completed, a post-mortem report is generated that includes a - > section for "Corrective Actions & Lessons Learned." This script automates the - > process of parsing that section to extract key insights. - > - > It identifies pairs of "Lesson" and "Action" statements and transforms them - > into a standardized, machine-readable format. These formatted entries are then - > appended to the `knowledge_core/lessons.jsonl` file, which serves as the - > agent's persistent memory of what has worked, what has failed, and what can be - > improved in future tasks. - > - > The script is executed via the command line, taking the path to a completed - > post-mortem file as its primary argument. - -- **`tooling/knowledge_integrator.py`**: - - > Enriches the local knowledge graph with data from external sources like DBPedia. - > - > This script loads the RDF graph generated from the project's protocols, - > identifies key concepts (like tools and rules), queries the DBPedia SPARQL - > endpoint to find related information, and merges the external data into a new, - > enriched knowledge graph. - -- **`tooling/lba_validator.py`**: - - > A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - > - > This module implements a validator that enforces the context-sensitive rules of the CSDC. - > Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make - > validation decisions. This is necessary to enforce rules where the validity of one - > command depends on the presence or absence of another command elsewhere in the plan. - > - > The CSDC defines two mutually exclusive models: - > - Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. - > - Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - > - > This validator checks for these co-occurrence constraints. - -- **`tooling/lfi_ill_halting_decider.py`**: - - > A tool for analyzing the termination of LFI-ILL programs. - > - > This script takes an LFI-ILL file, interprets it in a paraconsistent logic - > environment, and reports on its halting status. It does this by setting up - > a paradoxical initial state and observing how the program resolves it. - -- **`tooling/lfi_udc_model.py`**: - - > A paraconsistent execution model for UDC plans. - > - > This module provides the classes necessary to interpret a UDC (Un-decidable - > Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of - > concrete values, the state of the machine (registers, tape, etc.) is modeled - > using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - > - > This allows the system to reason about paradoxical programs, such as a program - > that halts if and only if it does not halt. By executing the program under - > paraconsistent semantics, the model can arrive at a final state of `BOTH`, - > effectively demonstrating the paradoxical nature of the input without crashing. - > - > 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. - > - `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - > analysis of a UDC plan. - -- **`tooling/log_failure.py`**: - - > A dedicated script to log a catastrophic failure event to the main activity log. - > - > This tool is designed to be invoked in the rare case of a severe, unrecoverable - > error that violates a core protocol. Its primary purpose is to ensure that such - > a critical event is formally and structurally documented in the standard agent - > activity log (`logs/activity.log.jsonl`), even if the main agent loop has - > crashed or been terminated. - > - > The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically - > attributing it to the "Unauthorized use of the `reset_all` tool." This creates a - > permanent, machine-readable record of the failure, which is essential for - > post-mortem analysis, debugging, and the development of future safeguards. - > - > By using the standard `Logger` class, it ensures that the failure log entry - > conforms to the established `LOGGING_SCHEMA.md`, making it processable by - > auditing and analysis tools. - -- **`tooling/master_control.py`**: - - > The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - > - > This script, master_control.py, is the heart of the agent's operational loop. - > It implements the CFDC, a hierarchical planning and execution model based on a - > Pushdown Automaton. This allows the agent to execute complex tasks by calling - > plans as sub-routines. - > - > Core Responsibilities: - > - **Hierarchical Plan Execution:** Manages a plan execution stack to enable - > plans to call other plans via the `call_plan` directive. This allows for - > modular, reusable, and complex task decomposition. A maximum recursion depth - > is enforced to guarantee decidability. - > - **Plan Validation:** Contains the in-memory plan validator. Before execution, - > it parses a plan and simulates its execution against a Finite State Machine - > (FSM) to ensure it complies with the agent's operational protocols. - > - **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - > it first attempts to look up the plan by its logical name in the - > `knowledge_core/plan_registry.json`. If not found, it falls back to treating - > the argument as a direct file path. - > - **FSM-Governed Lifecycle:** The entire workflow, from orientation to - > finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - > to ensure predictable and auditable behavior. - > - > This module is designed as a library to be controlled by an external shell - > (e.g., `agent_shell.py`), making its interaction purely programmatic. - -- **`tooling/master_control_cli.py`**: - - > The official command-line interface for the agent's master control loop. - > - > This script is now a lightweight wrapper that passes control to the new, - > API-driven `agent_shell.py`. It preserves the command-line interface while - > decoupling the entry point from the FSM implementation. - -- **`tooling/message_user.py`**: - - > A dummy tool that prints its arguments to simulate the message_user tool. - > - > This script is a simple command-line utility that takes a string as an - > argument and prints it to standard output, prefixed with "[Message User]:". - > Its purpose is to serve as a stand-in or mock for the actual `message_user` - > tool in testing environments where the full agent framework is not required. - > - > This allows for the testing of scripts or workflows that call the - > `message_user` tool without needing to invoke the entire agent messaging - > subsystem. - -- **`tooling/pda_parser.py`**: - - > A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - > - > This script uses the PLY (Python Lex-Yacc) library to define a lexer and a - > parser for a simple, string-based representation of pLLLU formulas. It can - > handle basic atomic formulas, unary operators (like negation and consistency), - > and binary operators (like implication and conjunction). - > - > The main function `parse_formula` takes a string and returns a simple AST - > (Abstract Syntax Tree) represented as nested tuples. - -- **`tooling/plan_executor.py`**: - - > A simple plan executor for simulating agent behavior. - > - > This script reads a plan file, parses it, and executes the commands in a - > simplified, simulated environment. It supports a limited set of tools - > (`message_user` and `run_in_bash_session`) to provide a basic demonstration - > of how an agent would execute a plan. - -- **`tooling/plan_manager.py`**: - - > Provides a command-line interface for managing the agent's Plan Registry. - > - > This script is the administrative tool for the Plan Registry, a key component - > of the Context-Free Development Cycle (CFDC) that enables hierarchical and - > modular planning. The registry, located at `knowledge_core/plan_registry.json`, - > maps human-readable, logical names to the file paths of specific plans. This - > decouples the `call_plan` directive from hardcoded file paths, making plans - > more reusable and the system more robust. - > - > This CLI provides three essential functions: - > - **register**: Associates a new logical name with a plan file path, adding it - > to the central registry. - > - **deregister**: Removes an existing logical name and its associated path from - > the registry. - > - **list**: Displays all current name-to-path mappings in the registry. - > - > By providing a simple, standardized interface for managing this library of - > reusable plans, this tool improves the agent's ability to compose complex - > workflows from smaller, validated sub-plans. - -- **`tooling/plan_parser.py`**: - - > Parses a plan file into a structured list of commands. - > - > This module provides the `parse_plan` function and the `Command` dataclass, - > which are central to the agent's ability to understand and execute plans. - > The parser correctly handles multi-line arguments and ignores comments, - > allowing for robust and readable plan files. - -- **`tooling/plllu_interpreter.py`**: - - > A resource-sensitive, four-valued interpreter for pLLLU formulas. - > - > This script implements an interpreter for the pLLLU language. It operates on - > an AST generated by the `pda_parser.py` script. The interpreter is designed - > to be resource-sensitive, meaning that each atomic formula in the initial - > context must be consumed exactly once during the evaluation of the proof. - > - > The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing - > it to reason about paraconsistent and paracomplete states. - > - > The core of the interpreter is the `FourValuedInterpreter` class, which - > recursively walks the AST, consuming resources from a context (a Counter of - > available atoms) and returning the resulting logical value. - -- **`tooling/plllu_runner.py`**: - - > A command-line runner for pLLLU files. - > - > This script provides an entry point for executing `.plllu` files. It - > integrates the pLLLU lexer, parser, and interpreter to execute the logic - > defined in a given pLLLU source file and print the result. - -- **`tooling/pre_submit_check.py`**: - - > _No module-level docstring found._ - -- **`tooling/protocol_compiler.py`**: - - > Compiles source protocol files into unified, human-readable and machine-readable artifacts. - > - > This script is the engine behind the "protocol as code" principle. It discovers, - > validates, and assembles protocol definitions from a source directory (e.g., `protocols/`) - > into high-level documents like `AGENTS.md`. - > - > Key Functions: - > - **Discovery:** Scans a directory for source files, including `.protocol.json` - > (machine-readable rules) and `.protocol.md` (human-readable context). - > - **Validation:** Uses a JSON schema (`protocol.schema.json`) to validate every - > `.protocol.json` file, ensuring all protocol definitions are syntactically - > correct and adhere to the established structure. - > - **Compilation:** Combines the human-readable markdown and the machine-readable - > JSON into a single, cohesive Markdown file, embedding the JSON in code blocks. - > - **Documentation Injection:** Can inject other generated documents, like the - > `SYSTEM_DOCUMENTATION.md`, into the final output at specified locations. - > - **Knowledge Graph Generation:** Optionally, it can process the validated JSON - > protocols and serialize them into an RDF knowledge graph (in Turtle format), - > creating a machine-queryable version of the agent's governing rules. - > - > This process ensures that `AGENTS.md` and other protocol documents are not edited - > manually but are instead generated from a validated, single source of truth, - > making the agent's protocols robust, verifiable, and maintainable. - -- **`tooling/protocol_updater.py`**: - - > A command-line tool for programmatically updating protocol source files. - > - > This script provides the mechanism for the agent to perform self-correction - > by modifying its own governing protocols based on structured, actionable - > lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) - > workflow. - > - > The tool operates on the .protocol.json files located in the `protocols/` - > directory, performing targeted updates based on command-line arguments. - -- **`tooling/refactor.py`**: - - > A tool for performing automated symbol renaming in Python code. - > - > This script provides a command-line interface to find a specific symbol - > (a function or a class) in a given Python file and rename it, along with all of - > its textual references throughout the entire repository. This provides a safe - > and automated way to perform a common refactoring task, reducing the risk of - > manual errors. - > - > The tool operates in three main stages: - > 1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - > to parse the source file and precisely locate the definition of the target - > symbol. This ensures that the tool is targeting the correct code construct. - > 2. **Reference Finding:** It performs a text-based search across the specified - > search path (defaulting to the entire repository) to find all files that - > mention the symbol's old name. - > 3. **Plan Generation:** Instead of modifying files directly, it generates a - > refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - > commands, one for each file that needs to be changed. The path to this - > generated plan file is printed to standard output. - > - > This plan-based approach allows the agent's master controller to execute the - > refactoring in a controlled, verifiable, and atomic way, consistent with its - > standard operational procedures. - -- **`tooling/reliable_ls.py`**: - - > A tool for reliably listing files and directories. - > - > This script provides a consistent, sorted, and recursive listing of files and - > directories, excluding the `.git` directory. It is intended to be a more - > reliable alternative to the standard `ls` command for agent use cases. - -- **`tooling/reorientation_manager.py`**: - - > Re-orientation Manager - > - > This script is the core of the automated re-orientation process. It is - > designed to be triggered by the build system whenever the agent's core - > protocols (`AGENTS.md`) are re-compiled. - > - > The manager performs the following key functions: - > 1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - > version to identify new protocols, tools, or other key concepts that have - > been introduced. - > 2. **Temporal Orientation (Shallow Research):** For each new concept, it - > invokes the `temporal_orienter.py` tool to fetch a high-level summary from - > an external knowledge base like DBpedia. This ensures the agent has a - > baseline understanding of new terms. - > 3. **Knowledge Storage:** The summaries from the temporal orientation are - > stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - > creating a persistent, queryable knowledge artifact. - > 4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - > change is deemed significant (e.g., the addition of a new core - > architectural protocol), it programmatically triggers a formal L4 Deep - > Research Cycle by creating a `deep_research_required.json` file. - > - > This automated workflow ensures that the agent never operates with an outdated - > understanding of its own protocols. It closes the loop between protocol - > modification and the agent's self-awareness, making the system more robust, - > adaptive, and reliable. - -- **`tooling/research.py`**: - - > This module contains the logic for executing research tasks based on a set of - > constraints. It acts as a dispatcher, calling the appropriate tool (e.g., - > read_file, google_search) based on the specified target and scope. - -- **`tooling/research_planner.py`**: - - > This module is responsible for generating a formal, FSM-compliant research plan - > for a given topic. The output is a string that can be executed by the agent's - > master controller. - -- **`tooling/self_correction_orchestrator.py`**: - - > Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - > - > This script is the engine of the automated feedback loop. It reads structured, - > actionable lessons from `knowledge_core/lessons.jsonl` and uses the - > `protocol_updater.py` tool to apply them to the source protocol files. - -- **`tooling/self_improvement_cli.py`**: - - > Analyzes agent activity logs to identify opportunities for self-improvement. - > - > This script is a command-line tool that serves as a key part of the agent's - > meta-cognitive loop. It parses the structured activity log - > (`logs/activity.log.jsonl`) to identify patterns that may indicate - > inefficiencies or errors in the agent's workflow. - > - > The primary analysis currently implemented is: - > - **Planning Efficiency Analysis:** It scans the logs for tasks that required - > multiple `set_plan` actions. A high number of plan revisions for a single - > task can suggest that the initial planning phase was insufficient, the task - > was poorly understood, or the agent struggled to adapt to unforeseen - > challenges. - > - > By flagging these tasks, the script provides a starting point for a deeper - > post-mortem analysis, helping the agent (or its developers) to understand the - > root causes of the planning churn and to develop strategies for more effective - > upfront planning in the future. - > - > The tool is designed to be extensible, with future analyses (such as error - > rate tracking or tool usage anti-patterns) to be added as the system evolves. - -- **`tooling/standard_agents_compiler.py`**: - - > A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - > - > This script acts as an "adapter" to make the repository more accessible to - > third-party AI agents that expect a conventional set of instructions. While the - > repository's primary `AGENTS.md` is a complex, hierarchical, and - > machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` - > file produced by this script offers a simple, human-readable summary of the - > most common development commands. - > - > The script works by: - > 1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - > which is the single source of truth for high-level commands. It specifically - > extracts the exact commands for common targets like `install`, `test`, - > `lint`, and `format`. This ensures the generated instructions are never - > stale. - > 2. **Injecting into a Template:** It injects these extracted commands into a - > pre-defined, user-friendly Markdown template. - > 3. **Generating the Artifact:** The final output is written to - > `AGENTS.standard.md`, providing a simple, stable, and conventional entry - > point for external tools, effectively bridging the gap between the complex - > internal protocol system and the broader agent ecosystem. - -- **`tooling/state.py`**: - - > Defines the core data structures for managing the agent's state. - > - > This module provides the `AgentState` and `PlanContext` dataclasses, which are - > fundamental to the operation of the Context-Free Development Cycle (CFDC). These - > structures allow the `master_control.py` orchestrator to maintain a complete, - > snapshot-able representation of the agent's progress through a task. - > - > - `AgentState`: The primary container for all information related to the current - > task, including the plan execution stack, message history, and error states. - > - `PlanContext`: A specific structure that holds the state of a single plan - > file, including its content and the current execution step. This is the - > element that gets pushed onto the `plan_stack` in `AgentState`. - > - > Together, these classes enable the hierarchical, stack-based planning and - > execution that is the hallmark of the CFDC. - -- **`tooling/symbol_map_generator.py`**: - - > Generates a code symbol map for the repository to aid in contextual understanding. - > - > This script creates a `symbols.json` file in the `knowledge_core` directory, - > which acts as a high-level index of the codebase. This map contains information - > about key programming constructs like classes and functions, including their - > name, location (file path and line number), and language. - > - > The script employs a two-tiered approach for symbol generation: - > 1. **Universal Ctags (Preferred):** It first checks for the presence of the - > `ctags` command-line tool. If available, it uses `ctags` to perform a - > comprehensive, multi-language scan of the repository. This is the most - > robust and accurate method. - > 2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - > back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - > method parses all `.py` files and extracts symbol information for Python - > code. While less comprehensive than `ctags`, it ensures that a baseline - > symbol map is always available. - > - > The resulting `symbols.json` artifact is a critical input for the agent's - > orientation and planning phases, allowing it to quickly locate relevant code - > and understand the structure of the repository without having to read every file. - -- **`tooling/udc_orchestrator.py`**: - - > An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - > - > This script provides a sandboxed environment for running UDC plans, which are - > low-level assembly-like programs that can perform Turing-complete computations. - > The orchestrator acts as a virtual machine with a tape-based memory model, - > registers, and a set of simple instructions. - > - > To prevent non-termination and other resource-exhaustion issues, the - > orchestrator imposes strict limits on the number of instructions executed, - > the amount of memory used, and the total wall-clock time. - -## Experimental Framework - -The `experiments/` directory contains a framework for testing the agent's behavior in response to changes in its governing protocols (`AGENTS.md`). Each subdirectory within `experiments/` represents a self-contained experiment. - -### Running an Experiment - -To run an existing experiment (e.g., `scoped_protocol_override`): - -1. **Review the Experiment:** Read the `README.md` inside the experiment's directory (e.g., `experiments/scoped_protocol_override/README.md`) to understand its hypothesis, procedure, and expected outcome. -2. **Perform the Baseline Run:** Follow the instructions in the experiment's `README.md` to establish the agent's baseline behavior. This usually involves performing a task in the root directory. -3. **Perform the Experimental Run:** Follow the instructions to run the agent against the mutated protocol. This typically involves: - a. Copying the `mutation.md` file to a new `AGENTS.md` file within the experiment's directory. - b. Instructing the agent to perform the task specified in `task.md`, targeting the experiment's directory. -4. **Compare the Results:** Observe the difference in the agent's behavior between the baseline and experimental runs to verify the hypothesis. - -### Creating a New Experiment - -1. Create a new subdirectory in `experiments/`. -2. Add a `README.md` file explaining the new experiment's hypothesis and procedure. -3. Add a `mutation.md` file containing the altered `AGENTS.md` content. -4. Add a `task.md` file describing the task the agent should perform. - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- - -# Tooling Directory Documentation - -This document provides an overview of the tools available in the `tooling/` directory. It is automatically generated from the docstrings of the tools. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `agent_shell.py` - -The new, interactive, API-driven entry point for the agent. - -This script replaces the old file-based signaling system with a direct, -programmatic interface to the MasterControlGraph FSM. It is responsible for: -1. Initializing the agent's state and a centralized logger. -2. Instantiating and running the MasterControlGraph. -3. Driving the FSM by calling its methods and passing data and the logger. -4. Containing the core "agent logic" (e.g., an LLM call) to generate plans - and respond to requests for action. - ---- - -## `__init__.py` - -_No module-level docstring found._ - ---- - -## `generate_and_test.py` - -_No module-level docstring found._ - ---- - -## `appl_runner.py` - -A command-line tool for executing APPL files. - -This script provides a simple interface to run APPL files using the main -`run.py` interpreter. It captures and prints the output of the execution, -and provides detailed error reporting if the execution fails. - ---- - -## `appl_to_lfi_ill.py` - -A compiler that translates APPL (a simple functional language) to LFI-ILL. - -This script takes a Python file containing an APPL AST, and compiles it into -an LFI-ILL AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `auditor.py` - -A unified auditing tool for maintaining repository health and compliance. - -This script combines the functionality of several disparate auditing tools into a -single, comprehensive command-line interface. It serves as the central tool for -validating the key components of the agent's architecture, including protocols, -plans, and documentation. - -The auditor can perform the following checks: -1. **Protocol Audit (`protocol`):** - - Checks if `AGENTS.md` artifacts are stale compared to their source files. - - Verifies protocol completeness by comparing tools used in logs against - tools defined in protocols. - - Analyzes tool usage frequency (centrality). -2. **Plan Registry Audit (`plans`):** - - Scans `knowledge_core/plan_registry.json` for "dead links" where the - target plan file does not exist. -3. **Documentation Audit (`docs`):** - - Scans the generated `SYSTEM_DOCUMENTATION.md` to find Python modules - that are missing module-level docstrings. - -The tool is designed to be run from the command line and can execute specific -audits or all of them, generating a consolidated `audit_report.md` file. - ---- - -## `aura_executor.py` - -This script serves as the command-line executor for `.aura` files. - -It bridges the gap between the high-level Aura scripting language and the -agent's underlying Python-based toolset. The executor is responsible for: -1. Parsing the `.aura` source code using the lexer and parser from the - `aura_lang` package. -2. Setting up an execution environment for the interpreter. -3. Injecting a "tool-calling" capability into the Aura environment, which - allows Aura scripts to dynamically invoke registered Python tools - (e.g., `hdl_prover`, `environmental_probe`). -4. Executing the parsed program and printing the final result. - -This makes it a key component for enabling more expressive and complex -automation scripts for the agent. - ---- - -## `aura_to_lfi_ill.py` - -A compiler that translates AURA code to LFI-ILL. - -This script takes an AURA file, parses it, and compiles it into an LFI-ILL -AST. The resulting AST is then written to a `.lfi_ill` file. - ---- - -## `background_researcher.py` - -This script performs a simulated research task in the background. -It takes a task ID as a command-line argument and writes its findings -to a temporary file that the main agent can poll. - ---- - -## `builder.py` - -A unified, configuration-driven build script for the project. - -This script serves as the central entry point for all build-related tasks, such -as generating documentation, compiling protocols, and running code quality checks. -It replaces a traditional Makefile's direct command execution with a more -structured, maintainable, and introspectable approach. - -The core logic is driven by a `build_config.json` file, which defines a series -of "targets." Each target specifies: -- The `type` of target: "compiler" or "command". -- For "compiler" types: `compiler` script, `output`, `sources`, and `options`. -- For "command" types: the `command` to execute. - -The configuration also defines "build_groups", which are ordered collections of -targets (e.g., "all", "quality"). - -This centralized builder provides several advantages: -- **Single Source of Truth:** The `build_config.json` file is the definitive - source for all build logic. -- **Consistency:** Ensures all build tasks are executed in a uniform way. -- **Extensibility:** New build targets can be added by simply updating the - configuration file. -- **Discoverability:** The script can list all available targets and groups. - ---- - -## `capability_verifier.py` - -A tool to verify that the agent can monotonically improve its capabilities. - -This script is designed to provide a formal, automated test for the agent's -self-correction and learning mechanisms. It ensures that when the agent learns -a new capability, it does so without losing (regressing) any of its existing -capabilities. This is a critical safeguard for ensuring robust and reliable -agent evolution. - -The tool works by orchestrating a four-step process: -1. **Confirm Initial Failure:** It runs a specific test file that is known to - fail, verifying that the agent currently lacks the target capability. -2. **Invoke Self-Correction:** It simulates the discovery of a new "lesson" and - triggers the `self_correction_orchestrator.py` script, which is responsible - for integrating new knowledge and skills. -3. **Confirm Final Success:** It runs the same test file again, confirming that - the agent has successfully learned the new capability and the test now passes. -4. **Check for Regressions:** It runs the full, existing test suite to ensure - that the process of learning the new skill has not inadvertently broken any - previously functional capabilities. - -This provides a closed-loop verification of monotonic improvement, which is a -cornerstone of the agent's design philosophy. - ---- - -## `code_suggester.py` - -Handles the generation and application of autonomous code change suggestions. - -This tool is a key component of the advanced self-correction loop. It is -designed to be invoked by the self-correction orchestrator when a lesson -contains a 'propose-code-change' action. - -For its initial implementation, this tool acts as a structured executor. It -takes a lesson where the 'details' field contains a fully-formed git-style -merge diff and applies it to the target file. It does this by generating a -temporary, single-step plan file and signaling its location for the master -controller to execute. - -This establishes the fundamental workflow for autonomous code modification, -decoupling the suggestion logic from the execution logic. Future iterations -can enhance this tool with more sophisticated code generation capabilities -(e.g., using an LLM to generate the diff from a natural language description) -without altering the core orchestration process. - ---- - -## `context_awareness_scanner.py` - -A tool for performing static analysis on a Python file to understand its context. - -This script provides a "contextual awareness" scan of a specified Python file -to help an agent (or a human) understand its role, dependencies, and connections -within a larger codebase. This is crucial for planning complex changes or -refactoring efforts, as it provides a snapshot of the potential impact of -modifying a file. - -The scanner performs three main functions: -1. **Symbol Definition Analysis:** It uses Python's Abstract Syntax Tree (AST) - module to parse the target file and identify all the functions and classes - that are defined within it. -2. **Import Analysis:** It also uses the AST to find all modules and symbols - that the target file imports, revealing its dependencies on other parts of - the codebase or external libraries. -3. **Reference Finding:** It performs a repository-wide search to find all other - files that reference the symbols defined in the target file. This helps to - understand how the file is used by the rest of the system. - -The final output is a detailed JSON report containing all of this information, -which can be used as a foundational artifact for automated planning or human review. - ---- - -## `csdc_cli.py` - -A command-line tool for managing the Context-Sensitive Development Cycle (CSDC). - -This script provides an interface to validate a development plan against a specific -CSDC model (A or B) and a given complexity class (P or EXP). It ensures that a -plan adheres to the strict logical and computational constraints defined by the -CSDC protocol before it is executed. - -The tool performs two main checks: -1. **Complexity Analysis:** It analyzes the plan to determine its computational - complexity and verifies that it matches the expected complexity class. -2. **Model Validation:** It validates the plan's commands against the rules of - the specified CSDC model, ensuring that it does not violate any of the - model's constraints (e.g., forbidding certain functions). - -This serves as a critical gateway for ensuring that all development work within -the CSDC framework is sound, predictable, and compliant with the governing -meta-mathematical principles. - ---- - -## `dependency_graph_generator.py` - -Scans the repository for dependency files and generates a unified dependency graph. - -This script is a crucial component of the agent's environmental awareness, -providing a clear map of the software supply chain. It recursively searches the -entire repository for common dependency management files, specifically: -- `package.json` (for JavaScript/Node.js projects) -- `requirements.txt` (for Python projects) - -It parses these files to identify two key types of relationships: -1. **Internal Dependencies:** Links between different projects within this repository. -2. **External Dependencies:** Links to third-party libraries and packages. - -The final output is a JSON file, `knowledge_core/dependency_graph.json`, which -represents these relationships as a graph structure with nodes (projects and -dependencies) and edges (the dependency links). This artifact is a primary -input for the agent's orientation and planning phases, allowing it to reason -about the potential impact of its changes. - ---- - -## `doc_builder.py` - -A unified documentation builder for the project. -... - ---- - -## `document_scanner.py` - -A tool for scanning the repository for human-readable documents and extracting their text content. - -This script is a crucial component of the agent's initial information-gathering -and orientation phase. It allows the agent to ingest knowledge from unstructured -or semi-structured documents that are not part of the formal codebase, but which -may contain critical context, requirements, or specifications. - -The scanner searches a given directory for files with common document extensions: -- `.pdf`: Uses the `pypdf` library to extract text from PDF files. -- `.md`: Reads Markdown files. -- `.txt`: Reads plain text files. - -The output is a dictionary where the keys are the file paths of the discovered -documents and the values are their extracted text content. This data can then -be used by the agent to inform its planning and execution process. This tool -is essential for bridging the gap between human-written documentation and the -agent's operational awareness. - ---- - -## `environmental_probe.py` - -Performs a series of checks to assess the capabilities of the execution environment. - -This script is a critical diagnostic tool run at the beginning of a task to -ensure the agent understands its operational sandbox. It verifies fundamental -capabilities required for most software development tasks: - -1. **Filesystem I/O:** Confirms that the agent can create, write to, read from, - and delete files. It also provides a basic latency measurement for these - operations. -2. **Network Connectivity:** Checks for external network access by attempting to - connect to a highly-available public endpoint (google.com). This is crucial - for tasks requiring `git` operations, package downloads, or API calls. -3. **Environment Variables:** Verifies that standard environment variables are - accessible, which is a prerequisite for many command-line tools. - -The script generates a human-readable report summarizing the results of these -probes, allowing the agent to quickly identify any environmental constraints -that might impact its ability to complete a task. - ---- - -## `fdc_cli.py` - -This script provides a command-line interface (CLI) for managing the Finite -Development Cycle (FDC). - -The FDC is a structured workflow for agent-driven software development. This CLI -is the primary human interface for interacting with that cycle, providing -commands to: -- **start:** Initiates a new development task, triggering the "Advanced - Orientation and Research Protocol" (AORP) to ensure the agent is fully - contextualized. -- **close:** Formally concludes a task, creating a post-mortem template for - analysis and lesson-learning. -- **validate:** Checks a given plan file for both syntactic and semantic - correctness against the FDC's governing Finite State Machine (FSM). This - ensures that a plan is executable and will not violate protocol. -- **analyze:** Examines a plan to determine its computational complexity (e.g., - Constant, Polynomial, Exponential) and its modality (Read-Only vs. - Read-Write), providing insight into the plan's potential impact. - ---- - -## `filesystem_lister.py` - -A tool for listing files and directories in a repository, with an option to respect .gitignore. - ---- - -## `halting_heuristic_analyzer.py` - -A static analysis tool to estimate the termination risk of a UDC plan. - -This script reads a `.udc` plan file, parses its instructions, and uses a -series of heuristics to identify potential infinite loops. It is not a -formal decider (as the halting problem is undecidable), but rather a -practical tool to flag common patterns that lead to non-termination. - -The analysis focuses on: -1. Detecting backward jumps, which are the primary indicator of loops. -2. Analyzing the exit conditions of these loops (e.g., `JE`, `JNE`). -3. Checking if the registers involved in the exit conditions are modified - within the loop body in a way that is likely to lead to termination. - -The tool outputs a JSON report detailing the estimated risk level (LOW, -MEDIUM, HIGH) and the specific loops that were identified. - ---- - -## `hdl_prover.py` - -A command-line tool for proving sequents in Intuitionistic Linear Logic. - -This script provides a basic interface to a simple logic prover. It takes a -sequent as a command-line argument, parses it into a logical structure, and -then attempts to prove it using a rudimentary proof search algorithm. - -The primary purpose of this tool is to allow the agent to perform formal -reasoning and verification tasks by checking the validity of logical entailments. -For example, it can be used to verify that a certain conclusion follows from a -set of premises according to the rules of linear logic. - -The current implementation uses a very basic parser and proof algorithm, -serving as a placeholder and demonstration for a more sophisticated, underlying -logic engine. - ---- - -## `hierarchical_compiler.py` - -_No module-level docstring found._ - ---- - -## `knowledge_compiler.py` - -Extracts structured lessons from post-mortem reports and compiles them into a -centralized, long-term knowledge base. - -This script is a core component of the agent's self-improvement feedback loop. -After a task is completed, a post-mortem report is generated that includes a -section for "Corrective Actions & Lessons Learned." This script automates the -process of parsing that section to extract key insights. - -It identifies pairs of "Lesson" and "Action" statements and transforms them -into a standardized, machine-readable format. These formatted entries are then -appended to the `knowledge_core/lessons.jsonl` file, which serves as the -agent's persistent memory of what has worked, what has failed, and what can be -improved in future tasks. - -The script is executed via the command line, taking the path to a completed -post-mortem file as its primary argument. - ---- - -## `knowledge_integrator.py` - -Enriches the local knowledge graph with data from external sources like DBPedia. - -This script loads the RDF graph generated from the project's protocols, -identifies key concepts (like tools and rules), queries the DBPedia SPARQL -endpoint to find related information, and merges the external data into a new, -enriched knowledge graph. - ---- - -## `lba_validator.py` - -A Linear Bounded Automaton (LBA) for validating Context-Sensitive Development Cycle (CSDC) plans. - -This module implements a validator that enforces the context-sensitive rules of the CSDC. -Unlike a simple FSM, an LBA can inspect the entire input "tape" (the plan) to make -validation decisions. This is necessary to enforce rules where the validity of one -command depends on the presence or absence of another command elsewhere in the plan. - -The CSDC defines two mutually exclusive models: -- Model A: Permits `define_set_of_names`, but forbids `define_diagonalization_function`. -- Model B: Permits `define_diagonalization_function`, but forbids `define_set_of_names`. - -This validator checks for these co-occurrence constraints. - ---- - -## `lfi_ill_halting_decider.py` - -A tool for analyzing the termination of LFI-ILL programs. - -This script takes an LFI-ILL file, interprets it in a paraconsistent logic -environment, and reports on its halting status. It does this by setting up -a paradoxical initial state and observing how the program resolves it. - ---- - -## `lfi_udc_model.py` - -A paraconsistent execution model for UDC plans. - -This module provides the classes necessary to interpret a UDC (Un-decidable -Computation) plan within a Logic of Formal Inconsistency (LFI). Instead of -concrete values, the state of the machine (registers, tape, etc.) is modeled -using paraconsistent truth values (TRUE, FALSE, BOTH, NEITHER). - -This allows the system to reason about paradoxical programs, such as a program -that halts if and only if it does not halt. By executing the program under -paraconsistent semantics, the model can arrive at a final state of `BOTH`, -effectively demonstrating the paradoxical nature of the input without crashing. - -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. -- `ParaconsistentHaltingDecider`: The main entry point that orchestrates the - analysis of a UDC plan. - ---- - -## `log_failure.py` - -A dedicated script to log a catastrophic failure event to the main activity log. - -This tool is designed to be invoked in the rare case of a severe, unrecoverable -error that violates a core protocol. Its primary purpose is to ensure that such -a critical event is formally and structurally documented in the standard agent -activity log (`logs/activity.log.jsonl`), even if the main agent loop has -crashed or been terminated. - -The script is pre-configured to log a `SYSTEM_FAILURE` event, specifically -attributing it to the "Unauthorized use of the `reset_all` tool." This creates a -permanent, machine-readable record of the failure, which is essential for -post-mortem analysis, debugging, and the development of future safeguards. - -By using the standard `Logger` class, it ensures that the failure log entry -conforms to the established `LOGGING_SCHEMA.md`, making it processable by -auditing and analysis tools. - ---- - -## `master_control.py` - -The master orchestrator for the agent's lifecycle, implementing the Context-Free Development Cycle (CFDC). - -This script, master_control.py, is the heart of the agent's operational loop. -It implements the CFDC, a hierarchical planning and execution model based on a -Pushdown Automaton. This allows the agent to execute complex tasks by calling -plans as sub-routines. - -Core Responsibilities: -- **Hierarchical Plan Execution:** Manages a plan execution stack to enable - plans to call other plans via the `call_plan` directive. This allows for - modular, reusable, and complex task decomposition. A maximum recursion depth - is enforced to guarantee decidability. -- **Plan Validation:** Contains the in-memory plan validator. Before execution, - it parses a plan and simulates its execution against a Finite State Machine - (FSM) to ensure it complies with the agent's operational protocols. -- **"Registry-First" Plan Resolution:** When resolving a `call_plan` directive, - it first attempts to look up the plan by its logical name in the - `knowledge_core/plan_registry.json`. If not found, it falls back to treating - the argument as a direct file path. -- **FSM-Governed Lifecycle:** The entire workflow, from orientation to - finalization, is governed by a strict FSM definition (e.g., `tooling/fsm.json`) - to ensure predictable and auditable behavior. - -This module is designed as a library to be controlled by an external shell -(e.g., `agent_shell.py`), making its interaction purely programmatic. - ---- - -## `master_control_cli.py` - -The official command-line interface for the agent's master control loop. - -This script is now a lightweight wrapper that passes control to the new, -API-driven `agent_shell.py`. It preserves the command-line interface while -decoupling the entry point from the FSM implementation. - ---- - -## `message_user.py` - -A dummy tool that prints its arguments to simulate the message_user tool. - -This script is a simple command-line utility that takes a string as an -argument and prints it to standard output, prefixed with "[Message User]:". -Its purpose is to serve as a stand-in or mock for the actual `message_user` -tool in testing environments where the full agent framework is not required. - -This allows for the testing of scripts or workflows that call the -`message_user` tool without needing to invoke the entire agent messaging -subsystem. - ---- - -## `pda_parser.py` - -A parser for pLLLU (paraconsistent Linear Logic with Undeterminedness) formulas. - -This script uses the PLY (Python Lex-Yacc) library to define a lexer and a -parser for a simple, string-based representation of pLLLU formulas. It can -handle basic atomic formulas, unary operators (like negation and consistency), -and binary operators (like implication and conjunction). - -The main function `parse_formula` takes a string and returns a simple AST -(Abstract Syntax Tree) represented as nested tuples. - ---- - -## `plan_executor.py` - -A simple plan executor for simulating agent behavior. - -This script reads a plan file, parses it, and executes the commands in a -simplified, simulated environment. It supports a limited set of tools -(`message_user` and `run_in_bash_session`) to provide a basic demonstration -of how an agent would execute a plan. - ---- - -## `plan_manager.py` - -Provides a command-line interface for managing the agent's Plan Registry. - -This script is the administrative tool for the Plan Registry, a key component -of the Context-Free Development Cycle (CFDC) that enables hierarchical and -modular planning. The registry, located at `knowledge_core/plan_registry.json`, -maps human-readable, logical names to the file paths of specific plans. This -decouples the `call_plan` directive from hardcoded file paths, making plans -more reusable and the system more robust. - -This CLI provides three essential functions: -- **register**: Associates a new logical name with a plan file path, adding it - to the central registry. -- **deregister**: Removes an existing logical name and its associated path from - the registry. -- **list**: Displays all current name-to-path mappings in the registry. - -By providing a simple, standardized interface for managing this library of -reusable plans, this tool improves the agent's ability to compose complex -workflows from smaller, validated sub-plans. - ---- - -## `plan_parser.py` - -Parses a plan file into a structured list of commands. - -This module provides the `parse_plan` function and the `Command` dataclass, -which are central to the agent's ability to understand and execute plans. -The parser correctly handles multi-line arguments and ignores comments, -allowing for robust and readable plan files. - ---- - -## `plllu_interpreter.py` - -A resource-sensitive, four-valued interpreter for pLLLU formulas. - -This script implements an interpreter for the pLLLU language. It operates on -an AST generated by the `pda_parser.py` script. The interpreter is designed -to be resource-sensitive, meaning that each atomic formula in the initial -context must be consumed exactly once during the evaluation of the proof. - -The logic is four-valued, supporting TRUE, FALSE, BOTH, and NEITHER, allowing -it to reason about paraconsistent and paracomplete states. - -The core of the interpreter is the `FourValuedInterpreter` class, which -recursively walks the AST, consuming resources from a context (a Counter of -available atoms) and returning the resulting logical value. - ---- - -## `plllu_runner.py` - -A command-line runner for pLLLU files. - -This script provides an entry point for executing `.plllu` files. It -integrates the pLLLU lexer, parser, and interpreter to execute the logic -defined in a given pLLLU source file and print the result. - ---- - -## `pre_submit_check.py` - -_No module-level docstring found._ - ---- - -## `protocol_compiler.py` - -This script now serves as the entry point for the hierarchical protocol compilation. -It discovers all protocol modules (subdirectories within `protocols/`) and compiles -each one into its own `AGENTS.md` file. It then generates a root `AGENTS.md` -that links to all the compiled modules, creating a unified, navigable system. - ---- - -## `protocol_updater.py` - -A command-line tool for programmatically updating protocol source files. - -This script provides the mechanism for the agent to perform self-correction -by modifying its own governing protocols based on structured, actionable -lessons. It is a key component of the Protocol-Driven Self-Correction (PDSC) -workflow. - -The tool operates on the .protocol.json files located in the `protocols/` -directory, performing targeted updates based on command-line arguments. - ---- - -## `refactor.py` - -A tool for performing automated symbol renaming in Python code. - -This script provides a command-line interface to find a specific symbol -(a function or a class) in a given Python file and rename it, along with all of -its textual references throughout the entire repository. This provides a safe -and automated way to perform a common refactoring task, reducing the risk of -manual errors. - -The tool operates in three main stages: -1. **Definition Finding:** It uses Python's Abstract Syntax Tree (AST) module - to parse the source file and precisely locate the definition of the target - symbol. This ensures that the tool is targeting the correct code construct. -2. **Reference Finding:** It performs a text-based search across the specified - search path (defaulting to the entire repository) to find all files that - mention the symbol's old name. -3. **Plan Generation:** Instead of modifying files directly, it generates a - refactoring "plan." This plan is a sequence of `replace_with_git_merge_diff` - commands, one for each file that needs to be changed. The path to this - generated plan file is printed to standard output. - -This plan-based approach allows the agent's master controller to execute the -refactoring in a controlled, verifiable, and atomic way, consistent with its -standard operational procedures. - ---- - -## `reliable_ls.py` - -A tool for reliably listing files and directories. - -This script provides a consistent, sorted, and recursive listing of files and -directories, excluding the `.git` directory. It is intended to be a more -reliable alternative to the standard `ls` command for agent use cases. - ---- - -## `reorientation_manager.py` - -Re-orientation Manager - -This script is the core of the automated re-orientation process. It is -designed to be triggered by the build system whenever the agent's core -protocols (`AGENTS.md`) are re-compiled. - -The manager performs the following key functions: -1. **Diff Analysis:** It compares the old version of AGENTS.md with the new - version to identify new protocols, tools, or other key concepts that have - been introduced. -2. **Temporal Orientation (Shallow Research):** For each new concept, it - invokes the `temporal_orienter.py` tool to fetch a high-level summary from - an external knowledge base like DBpedia. This ensures the agent has a - baseline understanding of new terms. -3. **Knowledge Storage:** The summaries from the temporal orientation are - stored in a structured JSON file (`knowledge_core/temporal_orientations.json`), - creating a persistent, queryable knowledge artifact. -4. **Deep Research Trigger:** It analyzes the nature of the changes. If a - change is deemed significant (e.g., the addition of a new core - architectural protocol), it programmatically triggers a formal L4 Deep - Research Cycle by creating a `deep_research_required.json` file. - -This automated workflow ensures that the agent never operates with an outdated -understanding of its own protocols. It closes the loop between protocol -modification and the agent's self-awareness, making the system more robust, -adaptive, and reliable. - ---- - -## `research.py` - -This module contains the logic for executing research tasks based on a set of -constraints. It acts as a dispatcher, calling the appropriate tool (e.g., -read_file, google_search) based on the specified target and scope. - ---- - -## `research_planner.py` - -This module is responsible for generating a formal, FSM-compliant research plan -for a given topic. The output is a string that can be executed by the agent's -master controller. - ---- - -## `self_correction_orchestrator.py` - -Orchestrates the Protocol-Driven Self-Correction (PDSC) workflow. - -This script is the engine of the automated feedback loop. It reads structured, -actionable lessons from `knowledge_core/lessons.jsonl` and uses the -`protocol_updater.py` tool to apply them to the source protocol files. - ---- - -## `self_improvement_cli.py` - -Analyzes agent activity logs to identify opportunities for self-improvement. - -This script is a command-line tool that serves as a key part of the agent's -meta-cognitive loop. It parses the structured activity log -(`logs/activity.log.jsonl`) to identify patterns that may indicate -inefficiencies or errors in the agent's workflow. - -The primary analysis currently implemented is: -- **Planning Efficiency Analysis:** It scans the logs for tasks that required - multiple `set_plan` actions. A high number of plan revisions for a single - task can suggest that the initial planning phase was insufficient, the task - was poorly understood, or the agent struggled to adapt to unforeseen - challenges. - -By flagging these tasks, the script provides a starting point for a deeper -post-mortem analysis, helping the agent (or its developers) to understand the -root causes of the planning churn and to develop strategies for more effective -upfront planning in the future. - -The tool is designed to be extensible, with future analyses (such as error -rate tracking or tool usage anti-patterns) to be added as the system evolves. - ---- - -## `standard_agents_compiler.py` - -A compiler that generates a simplified, standard-compliant `AGENTS.md` file. - -This script acts as an "adapter" to make the repository more accessible to -third-party AI agents that expect a conventional set of instructions. While the -repository's primary `AGENTS.md` is a complex, hierarchical, and -machine-readable artifact for its own specialized agent, the `AGENTS.standard.md` -file produced by this script offers a simple, human-readable summary of the -most common development commands. - -The script works by: -1. **Parsing the Makefile:** It dynamically parses the project's `Makefile`, - which is the single source of truth for high-level commands. It specifically - extracts the exact commands for common targets like `install`, `test`, - `lint`, and `format`. This ensures the generated instructions are never - stale. -2. **Injecting into a Template:** It injects these extracted commands into a - pre-defined, user-friendly Markdown template. -3. **Generating the Artifact:** The final output is written to - `AGENTS.standard.md`, providing a simple, stable, and conventional entry - point for external tools, effectively bridging the gap between the complex - internal protocol system and the broader agent ecosystem. - ---- - -## `state.py` - -Defines the core data structures for managing the agent's state. - -This module provides the `AgentState` and `PlanContext` dataclasses, which are -fundamental to the operation of the Context-Free Development Cycle (CFDC). These -structures allow the `master_control.py` orchestrator to maintain a complete, -snapshot-able representation of the agent's progress through a task. - -- `AgentState`: The primary container for all information related to the current - task, including the plan execution stack, message history, and error states. -- `PlanContext`: A specific structure that holds the state of a single plan - file, including its content and the current execution step. This is the - element that gets pushed onto the `plan_stack` in `AgentState`. - -Together, these classes enable the hierarchical, stack-based planning and -execution that is the hallmark of the CFDC. - ---- - -## `symbol_map_generator.py` - -Generates a code symbol map for the repository to aid in contextual understanding. - -This script creates a `symbols.json` file in the `knowledge_core` directory, -which acts as a high-level index of the codebase. This map contains information -about key programming constructs like classes and functions, including their -name, location (file path and line number), and language. - -The script employs a two-tiered approach for symbol generation: -1. **Universal Ctags (Preferred):** It first checks for the presence of the - `ctags` command-line tool. If available, it uses `ctags` to perform a - comprehensive, multi-language scan of the repository. This is the most - robust and accurate method. -2. **AST Fallback (Python-only):** If `ctags` is not found, the script falls - back to using Python's built-in Abstract Syntax Tree (`ast`) module. This - method parses all `.py` files and extracts symbol information for Python - code. While less comprehensive than `ctags`, it ensures that a baseline - symbol map is always available. - -The resulting `symbols.json` artifact is a critical input for the agent's -orientation and planning phases, allowing it to quickly locate relevant code -and understand the structure of the repository without having to read every file. - ---- - -## `udc_orchestrator.py` - -An orchestrator for executing Unrestricted Development Cycle (UDC) plans. - -This script provides a sandboxed environment for running UDC plans, which are -low-level assembly-like programs that can perform Turing-complete computations. -The orchestrator acts as a virtual machine with a tape-based memory model, -registers, and a set of simple instructions. - -To prevent non-termination and other resource-exhaustion issues, the -orchestrator imposes strict limits on the number of instructions executed, -the amount of memory used, and the total wall-clock time. - - ---- diff --git a/tooling/compiler.py b/tooling/compiler.py new file mode 100644 index 00000000..a539c5c7 --- /dev/null +++ b/tooling/compiler.py @@ -0,0 +1,88 @@ +import json +import os +import glob +from typing import List, Dict, Any +import jsonschema + +# Define the path to the protocol schema +SCHEMA_PATH = os.path.join("protocols", "protocol.schema.json") + +def load_json_file(filepath: str) -> Any: + """Loads a JSON file and returns its content.""" + try: + with open(filepath, 'r') as f: + return json.load(f) + except (json.JSONDecodeError, FileNotFoundError) as e: + print(f"Error reading or parsing {filepath}: {e}") + return None + +def validate_protocol(protocol_data: Dict[str, Any], schema: Dict[str, Any]) -> bool: + """ + Validates a protocol object against the JSON schema using the jsonschema library. + """ + try: + jsonschema.validate(instance=protocol_data, schema=schema) + return True + except jsonschema.exceptions.ValidationError as e: + print(f"Schema validation failed for {protocol_data.get('protocol_id', 'N/A')}: {e.message}") + return False + except Exception as e: + print(f"An unexpected error occurred during validation for {protocol_data.get('protocol_id', 'N/A')}: {e}") + return False + +def find_protocol_files(search_path: str) -> List[str]: + """Finds all '.protocol.json' files in the specified directory.""" + return glob.glob(os.path.join(search_path, '*.protocol.json')) + +def format_protocol_as_markdown(protocol: Dict[str, Any]) -> str: + """Formats a single protocol into a Markdown string.""" + md = [] + md.append(f"## Protocol: {protocol['protocol_id']}") + md.append(f"_{protocol['description']}_") + md.append("\n### Rules") + for rule in protocol.get('rules', []): + md.append(f"- **{rule['rule_id']}**: {rule['description']}") + if 'enforcement' in rule: + md.append(f" - *Enforcement: {rule['enforcement']}*") + if protocol.get('associated_tools'): + md.append("\n### Associated Tools") + for tool in protocol['associated_tools']: + md.append(f"- `{tool}`") + return "\n".join(md) + +def compile_protocols(search_path: str, output_path: str): + """ + Compiles all protocols in a directory into a single AGENTS.md file. + """ + print(f"Starting compilation for protocols in: {search_path}") + schema = load_json_file(SCHEMA_PATH) + if not schema: + print("Could not load protocol schema. Aborting.") + return + + protocol_files = find_protocol_files(search_path) + if not protocol_files: + print(f"No protocol files found in {search_path}.") + # If no protocols, create an empty or placeholder AGENTS.md + with open(output_path, 'w') as f: + f.write("# Agent Protocols\n\n*No protocols defined in this scope.*\n") + return + + all_markdowns = ["# Agent Protocols\n"] + all_markdowns.append("_This document is auto-generated from protocol source files. Do not edit it directly._\n") + + for proto_file in sorted(protocol_files): + protocol_data = load_json_file(proto_file) + if protocol_data and validate_protocol(protocol_data, schema): + print(f" - Compiling {proto_file}") + all_markdowns.append(format_protocol_as_markdown(protocol_data)) + all_markdowns.append("\n---\n") + + with open(output_path, 'w') as f: + f.write("\n".join(all_markdowns)) + print(f"Successfully compiled protocols to: {output_path}") + +if __name__ == '__main__': + # This allows the script to be run directly for testing. + # By default, it compiles the root 'protocols' directory. + compile_protocols('protocols', 'protocols/AGENTS.md') \ No newline at end of file diff --git a/tooling/hierarchical_compiler.py b/tooling/hierarchical_compiler.py new file mode 100644 index 00000000..651e7baa --- /dev/null +++ b/tooling/hierarchical_compiler.py @@ -0,0 +1,64 @@ +import os +from compiler import compile_protocols + +def find_protocol_directories(root_path: str): + """ + Finds all directories named 'protocols' within the repository, + ignoring specified directories like '.git'. + """ + protocol_dirs = [] + ignore_dirs = ['.git', '.github', 'archive', 'knowledge_core', 'tests'] + for root, dirs, _ in os.walk(root_path): + # Modify dirs in-place to prune the search + dirs[:] = [d for d in dirs if d not in ignore_dirs] + if 'protocols' in dirs: + protocol_dirs.append(os.path.join(root, 'protocols')) + return protocol_dirs + +def run_hierarchical_compilation(root_path: str): + """ + Runs the protocol compiler on every 'protocols' directory found. + """ + print("Starting hierarchical protocol compilation...") + + # First, compile the root protocols directory + root_protocol_dir = os.path.join(root_path, 'protocols') + if os.path.isdir(root_protocol_dir): + print("\n--- Compiling Root Protocols ---") + output_file = os.path.join(root_path, 'AGENTS.md') + compile_protocols(root_protocol_dir, output_file) + else: + print("\n--- No Root Protocols Directory Found ---") + + + # Then, find and compile all nested protocol directories + # We search from the root_path to find directories containing a 'protocols' subdir + for dirpath, dirnames, _ in os.walk(root_path): + if 'protocols' in dirnames: + # We are in a directory that has a 'protocols' subdirectory + # e.g., dirpath could be './core' + protocol_src_dir = os.path.join(dirpath, 'protocols') + output_file = os.path.join(dirpath, 'AGENTS.md') + + # We don't want to re-compile the root directory + if os.path.samefile(protocol_src_dir, root_protocol_dir): + continue + + print(f"\n--- Compiling Nested Protocols: {protocol_src_dir} ---") + compile_protocols(protocol_src_dir, output_file) + + +from knowledge_graph_generator import generate_knowledge_graph + +if __name__ == '__main__': + # Run the compilation process starting from the repository root. + repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) + + # First, run the AGENTS.md compilation + run_hierarchical_compilation(repo_root) + print("\n--- Hierarchical Compilation Complete ---") + + # Then, generate the knowledge graph + output_ttl_file = os.path.join(repo_root, 'protocols.ttl') + generate_knowledge_graph(repo_root, output_ttl_file) + print("\n--- Knowledge Graph Generation Complete ---") \ No newline at end of file diff --git a/tooling/knowledge_graph_generator.py b/tooling/knowledge_graph_generator.py new file mode 100644 index 00000000..0a098535 --- /dev/null +++ b/tooling/knowledge_graph_generator.py @@ -0,0 +1,89 @@ +import json +import os +import glob +from rdflib import Graph, Literal, Namespace, RDF, URIRef +from rdflib.namespace import DCTERMS, RDFS + +def find_all_protocol_files(root_path: str) -> list[str]: + """Finds all '.protocol.json' files recursively from the root path.""" + return glob.glob(os.path.join(root_path, '**', '*.protocol.json'), recursive=True) + +def generate_knowledge_graph(root_path: str, output_file: str): + """ + Generates a Turtle RDF knowledge graph from all protocol files. + """ + print("Starting knowledge graph generation...") + + # Define a namespace for our protocol ontology + PROTO = Namespace("http://agent-protocol.com/ontology#") + + # Create a new RDF graph + g = Graph() + g.bind("proto", PROTO) + g.bind("dcterms", DCTERMS) + g.bind("rdfs", RDFS) + + # Define classes and properties in our ontology for clarity + g.add((PROTO.Protocol, RDF.type, RDFS.Class)) + g.add((PROTO.Protocol, RDFS.label, Literal("Protocol"))) + g.add((PROTO.Rule, RDF.type, RDFS.Class)) + g.add((PROTO.Rule, RDFS.label, Literal("Rule"))) + g.add((PROTO.hasRule, RDF.type, RDF.Property)) + g.add((PROTO.governsTool, RDF.type, RDF.Property)) + + protocol_files = find_all_protocol_files(root_path) + + if not protocol_files: + print("No protocol files found. Knowledge graph will be empty.") + g.serialize(destination=output_file, format='turtle') + return + + for proto_file in protocol_files: + try: + with open(proto_file, 'r') as f: + data = json.load(f) + + protocol_id = data.get("protocol_id") + if not protocol_id: + continue + + print(f" - Processing {protocol_id} from {proto_file}") + + # Create a URI for the protocol + protocol_uri = URIRef(f"http://agent-protocol.com/protocols/{protocol_id}") + + # Add basic protocol information + g.add((protocol_uri, RDF.type, PROTO.Protocol)) + g.add((protocol_uri, RDFS.label, Literal(protocol_id))) + g.add((protocol_uri, DCTERMS.description, Literal(data.get("description", "")))) + + # Add rules + for i, rule in enumerate(data.get("rules", [])): + rule_id = rule.get("rule_id") + # Create a URI for the rule, ensuring it's unique + rule_uri = URIRef(f"http://agent-protocol.com/rules/{protocol_id}/{rule_id}") + + g.add((rule_uri, RDF.type, PROTO.Rule)) + g.add((protocol_uri, PROTO.hasRule, rule_uri)) + g.add((rule_uri, RDFS.label, Literal(rule_id))) + g.add((rule_uri, DCTERMS.description, Literal(rule.get("description", "")))) + if "enforcement" in rule: + g.add((rule_uri, PROTO.enforcement, Literal(rule.get("enforcement")))) + + # Add associated tools + for tool in data.get("associated_tools", []): + # We create a simple literal for the tool path for now + g.add((protocol_uri, PROTO.governsTool, Literal(tool))) + + except (json.JSONDecodeError, FileNotFoundError) as e: + print(f"Error processing file {proto_file}: {e}") + continue + + # Serialize the graph to a Turtle file + g.serialize(destination=output_file, format='turtle') + print(f"Successfully generated knowledge graph at: {output_file}") + +if __name__ == '__main__': + repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) + output_ttl_file = os.path.join(repo_root, 'protocols.ttl') + generate_knowledge_graph(repo_root, output_ttl_file) \ No newline at end of file