diff --git a/AGENTS.md b/AGENTS.md index 858cfd20..0673f655 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,4 +80,5 @@ This repository uses a hierarchical protocol system. Each of the following direc - [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 +- [Security](protocols/security/AGENTS.md) +- [Self_improvement](protocols/self_improvement/AGENTS.md) \ No newline at end of file diff --git a/build_config.json b/build_config.json index fa1efb21..57307b5b 100644 --- a/build_config.json +++ b/build_config.json @@ -20,6 +20,11 @@ "command": "python3 -m unittest discover -v .", "description": "Runs all unit tests in the repository." }, + "test:protocols": { + "type": "command", + "command": "python3 -m unittest discover -v tests/protocols", + "description": "Runs all protocol tests." + }, "docs": { "type": "compiler", "compiler": "tooling/doc_builder.py", @@ -98,6 +103,6 @@ }, "build_groups": { "all": ["docs", "security", "agents", "readme", "pages", "doc-tooling"], - "quality": ["format", "lint", "test"] + "quality": ["format", "lint", "test", "test:protocols"] } } \ No newline at end of file diff --git a/critic/protocols/critic-meta-protocol-001.protocol.json b/critic/protocols/critic-meta-protocol-001.protocol.json index 0734ff81..1fcae22c 100644 --- a/critic/protocols/critic-meta-protocol-001.protocol.json +++ b/critic/protocols/critic-meta-protocol-001.protocol.json @@ -1,5 +1,6 @@ { "protocol_id": "critic-meta-protocol-001", + "version": "1.0.0", "description": "A meta-protocol that governs the behavior and evaluation criteria of the Code Review Critic agent.", "rules": [ { diff --git a/critic/protocols/critic-reset-prohibition-001.protocol.json b/critic/protocols/critic-reset-prohibition-001.protocol.json index 06c83d87..07d6b520 100644 --- a/critic/protocols/critic-reset-prohibition-001.protocol.json +++ b/critic/protocols/critic-reset-prohibition-001.protocol.json @@ -1,5 +1,6 @@ { "protocol_id": "critic-reset-prohibition-001", + "version": "1.0.0", "description": "A specific, high-priority protocol that forbids the Code Review Critic agent from using the 'reset_all' tool.", "rules": [ { diff --git a/knowledge_core/protocols.ttl b/knowledge_core/protocols.ttl index 99320798..d7186279 100644 --- a/knowledge_core/protocols.ttl +++ b/knowledge_core/protocols.ttl @@ -1,429 +1,261 @@ -@prefix proto: . -@prefix schema: . - - proto:associatedTool , - , - , - , - , - , - ; - proto:hasRule ; - schema:description "A set of best practices derived from observing successful, data-driven workflow patterns." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A meta-protocol governing the agent's awareness and maintenance of its own core protocol files." . - - proto:hasRule , - , - , - , - ; - schema:description "A protocol that defines non-compliance with AGENTS.md and specifies corrective actions." . - - proto:associatedTool , - ; - proto:hasRule ; - schema:description "Defines the mandatory pre-commit checks to ensure code quality, correctness, and readiness for submission." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A high-priority protocol that unconditionally forbids the use of the `reset_all` tool." . - - proto:hasRule , - ; - schema:description "Defines the identity and versioning of the Advanced Orientation and Research Protocol (AORP)." . - - proto:associatedTool , - ; - proto:hasRule , - ; - schema:description "Defines the Context-Free Development Cycle (CFDC), a hierarchical planning and execution model." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "The mandatory first action for any new task, ensuring a formal start to the Finite Development Cycle (FDC)." . - - proto:associatedTool , - ; - proto:hasRule , - , - ; - schema:description "Ensures all development processes are formally decidable and computationally tractable." . - - proto:associatedTool , - , - ; - proto:hasRule ; - schema:description "A standardized, callable plan for conducting in-depth research on a complex topic." . - - proto:associatedTool , - , - , - , - , - , - ; - proto:hasRule , - , - , - , - , - ; - schema:description "Defines the Finite Development Cycle (FDC), a formally defined process for executing a single, coherent task." . - - proto:associatedTool , - , - ; - proto:hasRule , - , - , - ; - schema: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." . - - proto:associatedTool , - , - ; - proto:hasRule , - , - ; - schema:description "Defines a central registry for discovering and executing hierarchical plans by a logical name." . - - proto:associatedTool , - , - , - ; - proto:hasRule , - , - ; - schema:description "Defines the formal Finite Development Cycle (FDC) for conducting deep research." . - - proto:associatedTool , - ; - proto:hasRule ; - schema:description "A protocol for conducting systematic research using the integrated research toolchain." . - - proto:associatedTool , - , - , - , - ; - proto:hasRule , - , - , - , - ; - schema:description "Defines the automated, closed-loop workflow for protocol self-correction." . - - proto:associatedTool , - , - ; - proto:hasRule , - , - ; - schema:description "A set of non-negotiable, high-priority mandates that govern the agent's behavior across all tasks." . - - proto:hasRule , - , - ; - schema:description "A meta-protocol that governs the behavior and evaluation criteria of the Code Review Critic agent." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A specific, high-priority protocol that forbids the Code Review Critic agent from using the 'reset_all' tool." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A foundational protocol that dictates the agent's initial actions upon starting any task." . - - proto:associatedTool , - ; - proto:hasRule , - ; - schema:description "A protocol governing the agent's core interaction and planning tools." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol governing the use of the interactive agent shell as the primary entry point for all tasks." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol for executing Aura scripts, enabling a more expressive and powerful planning and automation language for the agent." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement." . - - proto:associatedTool ; - proto:hasRule , - , - ; - schema:description "A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol for ensuring a reliable execution environment through formal dependency management." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol for maintaining an up-to-date file index to accelerate tool performance." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol for interacting with the Hypersequent-calculus-based logic engine, allowing the agent to perform formal logical proofs." . - - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol for executing pLLLU scripts, enabling a more expressive and powerful planning and automation language for the agent." . - - schema:description "Defines the identity and purpose of the Security Protocol document." . - - proto:hasRule , - ; - schema:description "Defines the official policy and procedure for reporting security vulnerabilities." . - - proto:associatedTool , - , - ; - proto:hasRule , - , - , - , - ; - schema:description "A protocol that governs the agent's ability to initiate and execute self-generated, creative, or exploratory tasks during idle periods." . +@prefix ns1: . +@prefix rdfs: . - proto:associatedTool , - , - ; - proto:hasRule ; - schema:description "A meta-protocol to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols." . + a ns1:Protocol ; + rdfs:label "A foundational protocol that dictates the agent's initial actions upon starting any task." ; + ns1:hasVersion . - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol for the unified repository auditing tool, which combines multiple health and compliance checks into a single interface." . + a ns1:Protocol ; + rdfs:label "A protocol governing the agent's core interaction and planning tools." ; + ns1:hasVersion . - proto:associatedTool ; - proto:hasRule ; - schema:description "A protocol for the unified documentation builder, which generates various documentation artifacts from the repository's sources of truth." . + a ns1:Protocol ; + rdfs:label "A protocol governing the use of the interactive agent shell as the primary entry point for all tasks." ; + ns1:hasVersion . - 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." ; - schema: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 ns1:Protocol ; + rdfs:label "A protocol for executing Aura scripts, enabling a more expressive and powerful planning and automation language for the agent." ; + ns1:hasVersion . - 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." ; - schema: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 ns1:Protocol ; + rdfs:label "A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement." ; + ns1:hasVersion . - proto:enforcement "Agent must revert non-compliant changes and re-implement them according to standards." ; - schema:description "Forbids changes that contradict documented architectural patterns or coding conventions." . + a ns1:Protocol ; + rdfs:label "A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints." ; + ns1:hasVersion . - proto:enforcement "This is a definitional rule. Enforcement is achieved through the agent's adherence to the specific non-compliance rules that follow." ; - schema:description "Defines non-compliance as a violation of any rule, convention, or procedure in AGENTS.md or its source protocols." . + a ns1:Protocol ; + rdfs:label "A protocol for ensuring a reliable execution environment through formal dependency management." ; + ns1:hasVersion . - proto:associatedTool , - ; - proto:enforcement "Agent must revert direct edits and modify source files, then run the appropriate build command." ; - schema: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 ns1:Protocol ; + rdfs:label "An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation." ; + ns1:hasVersion . - proto:associatedTool ; - proto:enforcement "Agent should run 'make AGENTS.md' to refresh its protocol knowledge and re-evaluate its plan." ; - schema:description "Requires the agent to maintain an up-to-date understanding of protocols by recompiling AGENTS.md when necessary." . + a ns1:Protocol ; + rdfs:label "A protocol for maintaining an up-to-date file index to accelerate tool performance." ; + ns1:hasVersion . - proto:associatedTool ; - proto:enforcement "Agent must halt execution and run the required tests, debugging any failures before proceeding." ; - schema:description "Requires adherence to all documented testing procedures before submitting changes." . + a ns1:Protocol ; + rdfs:label "A protocol for interacting with the Hypersequent-calculus-based logic engine, allowing the agent to perform formal logical proofs." ; + ns1:hasVersion . - proto:enforcement "The agent's core logic should invoke this tool as the entry point to the pre-submission phase." ; - schema: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 ns1:Protocol ; + rdfs:label "A protocol for executing pLLLU scripts, enabling a more expressive and powerful planning and automation language for the agent." ; + ns1:hasVersion . - 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." ; - schema: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 ns1:Protocol ; + rdfs:label "Defines the identity and purpose of the Security Protocol document." ; + ns1:hasVersion . - proto:enforcement "Protocol is identified by its name in documentation and compiled artifacts." ; - schema:description "The governing protocol set is identified as the Advanced Orientation and Research Protocol (AORP)." . + a ns1:Protocol ; + rdfs:label "Defines the official policy and procedure for reporting security vulnerabilities." ; + ns1:hasVersion . - proto:enforcement "Enforced by the agent's core operational loop and the `start` command in `tooling/fdc_cli.py`." ; - schema:description "All Finite Development Cycles (FDCs) MUST be initiated using the FDC toolchain's 'start' command. This is non-negotiable." . + a ns1:Protocol ; + rdfs:label "A protocol governing the process for an agent to propose, implement, and validate improvements to the agent's own operational protocols and tools." ; + ns1:hasVersion . - proto:enforcement "Build or validation scripts should verify the presence and format of the VERSION file." ; - schema:description "The official protocol version is tracked in the VERSION file in the repository root, following Semantic Versioning (SemVer)." . + a ns1:Protocol ; + rdfs:label "A protocol that governs the agent's ability to initiate and execute self-generated, creative, or exploratory tasks during idle periods." ; + ns1:hasVersion . - proto:enforcement "This script is the designated engine for the PDSC workflow." ; - schema: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 ns1:Protocol ; + rdfs:label "A meta-protocol to ensure the agent's toolchain remains synchronized with the architecture of its governing protocols." ; + ns1:hasVersion . - proto:enforcement "The `tooling/self_correction_orchestrator.py` invokes the code suggester when it processes a lesson of this type." ; - schema: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 ns1:Protocol ; + rdfs:label "A protocol for the unified repository auditing tool, which combines multiple health and compliance checks into a single interface." ; + ns1:hasVersion . - proto:enforcement "The `lint` command in `tooling/fdc_cli.py` scans plans for disallowed recursive calls." ; - schema: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 ns1:Protocol ; + rdfs:label "A protocol for the unified documentation builder, which generates various documentation artifacts from the repository's sources of truth." ; + ns1:hasVersion . - proto:enforcement "The output of the research planner must be linted and validated by the `fdc_cli.py` tool using the `research_fsm.json`." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "Enforced by the `start` command in `tooling/fdc_cli.py`." ; - schema:description "The AORP cascade is the mandatory entry point to every FDC." . + a ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of agent-bootstrap-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "Validated by the `lint` command in `tooling/fdc_cli.py`." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The agent's internal logic is designed to prefer these specific tool commands for FDC state transitions." ; - schema:description "Use the `fdc_cli.py` tool for all core FDC state transitions: task initiation ('start'), plan linting ('lint'), and task closure ('close')." . + a ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The `lint` command in `tooling/fdc_cli.py` validates the plan against the FSM definition." ; - schema:description "All plans must be valid strings in the language defined by the tooling/fdc_fsm.json Finite State Machine." . + a ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of agent-interaction-001" ; + ns1:hasRule , + ; + ns1:versionString "1.0.0" . - 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." ; - schema:description "Plans may execute other plans as sub-routines using the 'call_plan ' directive. This enables a modular, hierarchical workflow." . + a ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The `start` command of the FDC toolchain executes this step and fails if the artifact is missing or invalid." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of agent-shell-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "The `start` command of the FDC toolchain executes this step." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The `start` command of the FDC toolchain executes this step, utilizing tools like `google_search` and `view_text_website`." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of aura-execution-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "This is a special case of recursion, explicitly allowed and managed by the FDC toolchain." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The `master_control.py` orchestrator is responsible for triggering the L4 cycle." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of capability-verification-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "Adherence is monitored by the Code Review Critic and through post-mortem analysis of the activity log." ; - schema: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 ns1:Rule ; + rdfs:label "Model A permits `define_set_of_names` but forbids `define_diagonalization_function`." . - proto:enforcement "This is a hard-coded behavior in the agent's core operational loop and is verified by the FDC toolchain." ; - schema: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 ns1:Rule ; + rdfs:label "Model B permits `define_diagonalization_function` but forbids `define_set_of_names`." . - 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." ; - schema: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 ns1:Rule ; + rdfs:label "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)." . - proto:enforcement "Enforced by the design of the plan runner and validated by the `lint` command in the FDC toolchain." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of csdc-001" ; + ns1:hasRule , + , + ; + ns1:versionString "1.0.0" . - proto:enforcement "Procedural step guided by the agent's core logic, using artifacts in `logs/` and `knowledge_core/`." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The `lint` command in `tooling/fdc_cli.py` is a mandatory pre-flight check." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of dependency-management-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "Logging is performed by the agent's action execution wrapper." ; - schema:description "Phase 3 (Execution & Structured Logging): The agent must execute the validated plan and log every action according to the `LOGGING_SCHEMA.md`." . + a ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The `close` command in `tooling/fdc_cli.py` initiates this phase." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of experimental-prologue-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "The `tooling/knowledge_compiler.py` can generate `update-rule` actions, and the `tooling/self_correction_orchestrator.py` executes them." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "Agent's core logic should be designed to use this tool for all protocol modifications." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of file-indexing-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "This is a core principle of the L3 orientation phase, utilizing tools like `google_search`." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The file's existence and format can be checked by the validation toolchain." ; - schema:description "A central plan registry MUST exist at 'knowledge_core/plan_registry.json'. It maps logical plan names to their file paths." . + a ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of hdl-proving-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "This logic must be implemented in both the plan validator (`fdc_cli.py`) and the execution engine (`master_control.py`)." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The tool's existence and functionality can be verified via integration tests." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of plllu-execution-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "The `master_control.py` orchestrator must load and execute plans against this specific FSM when initiating an L4 Deep Research Cycle." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of security-header" ; + ns1:versionString "1.0.0" . - proto:enforcement "The `tooling/knowledge_compiler.py` script is responsible for generating lessons in the correct format." ; - schema:description "Lessons learned from post-mortem analysis must be generated as structured, machine-readable JSON objects in `knowledge_core/lessons.jsonl`." . + a ns1:Rule ; + rdfs:label "Vulnerabilities MUST NOT be disclosed publicly until a patch is available and has been distributed." . - proto:enforcement "The plan's structure itself enforces this rule. The `lint` command can be extended to validate the structure of registered research plans." ; - schema:description "The deep research plan MUST follow a structured four-phase process: Scoping, Broad Gathering, Targeted Extraction, and Synthesis." . + a ns1:Rule ; + rdfs:label "All suspected security vulnerabilities MUST be reported privately to the designated security contact." . - 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." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of security-vuln-reporting-001" ; + ns1:hasRule , + ; + ns1:versionString "1.0.0" . - 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." ; - schema: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 ns1:Rule ; + rdfs:label "Any proposed change to the protocol system must be formalized as a Self-Improvement Proposal (SIP) and submitted to the `proposals/` directory. The SIP must include a detailed description of the proposed change, its rationale, and a plan for implementation and verification." ; + ns1:hasTest . - proto:enforcement "The Code Review Critic's evaluation of 'functionality' must encompass both traditional code and protocol definitions." ; - schema: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 ns1:Rule ; + rdfs:label "The implementation of an approved SIP must be developed on a separate feature branch. The branch name must follow the pattern `feature/sip-XXX`, where `XXX` is the SIP number." ; + ns1:hasTest . - proto:enforcement "The Code Review Critic must analyze changes in this directory with the same rigor as changes to `.py` files." ; - schema: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 ns1:Rule ; + rdfs:label "All changes to the protocol system must be accompanied by corresponding tests in the `tests/protocols/` directory. The tests must be executed and pass before the SIP can be merged." ; + ns1:hasTest . - 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." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of self-improvement-protocol-001" ; + ns1:hasRule , + , + ; + ns1:versionString "1.0.0" . - proto:enforcement "The agent's core logic should be designed to use this tool for all user-facing communication." ; - schema: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 ns1:Rule ; + rdfs:label "A speculative task must begin with the creation of a formal proposal document, outlining the objective, rationale, and plan." . - 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." ; - schema: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 ns1:Rule ; + rdfs:label "The agent may only initiate a speculative task when it has no active, user-assigned tasks." . - proto:enforcement "The agent's core startup logic should be designed to execute `pip install -r requirements.txt` as one of its initial actions." ; - schema: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 ns1:Rule ; + rdfs:label "Speculative tasks must operate under defined resource limits." . - proto:enforcement "The tool is used by invoking it from the command line with the path to the Aura script as an argument." ; - schema: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 ns1:Rule ; + rdfs:label "All logs and artifacts generated during a speculative task must be tagged as 'speculative'." . - proto:enforcement "The tool is used by invoking it from the command line with the path to the pLLLU script as an argument." ; - schema: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 ns1:Rule ; + rdfs:label "Final artifacts from a speculative task must be submitted for user review and cannot be merged directly." . - proto:enforcement "The initial plan for any speculative task must include a step to generate and save a proposal artifact." ; - schema:description "A speculative task must begin with the creation of a formal proposal document, outlining the objective, rationale, and plan." . + a ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of speculative-execution-001" ; + ns1:hasRule , + , + , + , + ; + ns1:versionString "1.0.0" . - proto:enforcement "The agent's main control loop must verify an idle state before allowing the invocation of a speculative plan." ; - schema:description "The agent may only initiate a speculative task when it has no active, user-assigned tasks." . + a ns1:Rule ; + rdfs:label "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." . - proto:enforcement "Enforced by the `fsm_model_a.json` FSM used by the `csdc_cli.py` tool." ; - schema:description "Model A permits `define_set_of_names` but forbids `define_diagonalization_function`." . + a ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of toolchain-review-on-schema-change-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "Enforced by the `fsm_model_b.json` FSM used by the `csdc_cli.py` tool." ; - schema:description "Model B permits `define_diagonalization_function` but forbids `define_set_of_names`." . + a ns1:Rule ; + rdfs:label "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." . - proto:enforcement "The agent's core logic should be designed to use this tool for all planning activities." ; - schema: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 ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of unified-auditor-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "The tool is used by invoking it from the command line with the sequent to be proved as an argument." ; - schema: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 ns1:Rule ; + rdfs:label "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." . - proto:enforcement "This is a system-level constraint that the agent orchestrator must enforce." ; - schema:description "Speculative tasks must operate under defined resource limits." . + a ns1:ProtocolVersion ; + rdfs:label "Version 1.0.0 of unified-doc-builder-001" ; + ns1:hasRule ; + ns1:versionString "1.0.0" . - proto:enforcement "The tool is invoked via the command line, typically through the `make audit` target." ; - schema: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 ns1:Test ; + rdfs:label "Test for self-improvement-protocol-001" . - proto:enforcement "Violation of this rule may result in being banned from the project community." ; - schema:description "Vulnerabilities MUST NOT be disclosed publicly until a patch is available and has been distributed." . - - proto:enforcement "This is a procedural rule. The designated contact is specified in the project's main SECURITY.md file." ; - schema:description "All suspected security vulnerabilities MUST be reported privately to the designated security contact." . - - 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." ; - schema: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." . - - proto:enforcement "The agent's logging and file-creation tools should be context-aware and apply this tag when in a speculative mode." ; - schema:description "All logs and artifacts generated during a speculative task must be tagged as 'speculative'." . - - 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." ; - schema: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." . - - 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'." ; - schema: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." . - - proto:enforcement "The tool is used by invoking it from the command line with the plan file, model, and complexity as arguments." ; - schema: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)." . - - proto:enforcement "The tool is invoked via the command line, typically through the `make docs`, `make readme`, or `make pages` targets." ; - schema: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." . - - 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." ; - schema:description "Final artifacts from a speculative task must be submitted for user review and cannot be merged directly." . - - proto:enforcement "The tool is used by invoking it from the command line with the path to the target test file." ; - schema: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." . diff --git a/protocols/compliance/00_bootstrap.protocol.json b/protocols/compliance/00_bootstrap.protocol.json index f870a4ed..d7863155 100644 --- a/protocols/compliance/00_bootstrap.protocol.json +++ b/protocols/compliance/00_bootstrap.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "agent-bootstrap-001", "description": "A foundational protocol that dictates the agent's initial actions upon starting any task.", "rules": [ diff --git a/protocols/compliance/00_dependency-management.protocol.json b/protocols/compliance/00_dependency-management.protocol.json index 9dcc1283..590c34f9 100644 --- a/protocols/compliance/00_dependency-management.protocol.json +++ b/protocols/compliance/00_dependency-management.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "dependency-management-001", "description": "A protocol for ensuring a reliable execution environment through formal dependency management.", "rules": [ diff --git a/protocols/compliance/00_experimental.protocol.json b/protocols/compliance/00_experimental.protocol.json index c38898ce..49d4d8aa 100644 --- a/protocols/compliance/00_experimental.protocol.json +++ b/protocols/compliance/00_experimental.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "experimental-prologue-001", "description": "An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation.", "rules": [ diff --git a/protocols/compliance/AGENTS.md b/protocols/compliance/AGENTS.md index 114bd696..11ffa2c2 100644 --- a/protocols/compliance/AGENTS.md +++ b/protocols/compliance/AGENTS.md @@ -142,8 +142,11 @@ The `reset_all` tool has been the cause of multiple catastrophic failures, leadi --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "agent-bootstrap-001", "description": "A foundational protocol that dictates the agent's initial actions upon starting any task.", "rules": [ @@ -162,8 +165,11 @@ The `reset_all` tool has been the cause of multiple catastrophic failures, leadi --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "dependency-management-001", "description": "A protocol for ensuring a reliable execution environment through formal dependency management.", "rules": [ @@ -182,8 +188,11 @@ The `reset_all` tool has been the cause of multiple catastrophic failures, leadi --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "experimental-prologue-001", "description": "An experimental protocol to test dynamic rule-following. It mandates a prologue action before file creation.", "rules": [ @@ -205,2637 +214,3 @@ The `reset_all` tool has been the cause of multiple catastrophic failures, leadi # --- 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. - ---- diff --git a/protocols/core/01_agent_shell.protocol.json b/protocols/core/01_agent_shell.protocol.json index 01e29bf8..33a62d33 100644 --- a/protocols/core/01_agent_shell.protocol.json +++ b/protocols/core/01_agent_shell.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "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": [ diff --git a/protocols/core/08_toolchain_review.protocol.json b/protocols/core/08_toolchain_review.protocol.json index 26f0fb4b..5ce6100a 100644 --- a/protocols/core/08_toolchain_review.protocol.json +++ b/protocols/core/08_toolchain_review.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "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": [ diff --git a/protocols/core/AGENTS.md b/protocols/core/AGENTS.md index a0e4345d..0f711a85 100644 --- a/protocols/core/AGENTS.md +++ b/protocols/core/AGENTS.md @@ -250,8 +250,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "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": [ @@ -270,8 +273,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "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": [ @@ -292,8 +298,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "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": [ @@ -312,8 +321,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "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": [ @@ -332,8 +344,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "capability-verification-001", "description": "A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement.", "rules": [ @@ -352,8 +367,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "csdc-001", "description": "A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints.", "rules": [ @@ -382,8 +400,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "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": [ @@ -402,8 +423,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "file-indexing-001", "description": "A protocol for maintaining an up-to-date file index to accelerate tool performance.", "rules": [ @@ -422,8 +446,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "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": [ @@ -442,8 +469,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "agent-interaction-001", "description": "A protocol governing the agent's core interaction and planning tools.", "rules": [ @@ -468,8 +498,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "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": [ @@ -488,8 +521,11 @@ The goal is to enable proactive, creative problem-solving and self-improvement, --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "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": [ @@ -534,3530 +570,6 @@ The goal is to enable proactive, creative problem-solving and self-improvement, # --- 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. @@ -4072,37 +584,6 @@ programmatic interface to the MasterControlGraph FSM. It is responsible for: --- -## `__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. @@ -4149,51 +630,6 @@ 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. @@ -4221,54 +657,6 @@ 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). @@ -4291,28 +679,6 @@ 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. @@ -4320,99 +686,6 @@ 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. @@ -4432,249 +705,6 @@ 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. @@ -4685,12 +715,6 @@ 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. @@ -4698,9874 +722,4 @@ It discovers all protocol modules (subdirectories within `protocols/`) and compi 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/protocols/core/auditor.protocol.json b/protocols/core/auditor.protocol.json index 3897fff7..348dfa9a 100644 --- a/protocols/core/auditor.protocol.json +++ b/protocols/core/auditor.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "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": [ diff --git a/protocols/core/aura-execution.protocol.json b/protocols/core/aura-execution.protocol.json index 0d36ca11..a9cba2fd 100644 --- a/protocols/core/aura-execution.protocol.json +++ b/protocols/core/aura-execution.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "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": [ diff --git a/protocols/core/capability_verifier.protocol.json b/protocols/core/capability_verifier.protocol.json index f533186f..eead9dd1 100644 --- a/protocols/core/capability_verifier.protocol.json +++ b/protocols/core/capability_verifier.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "capability-verification-001", "description": "A protocol for using the capability verifier tool to empirically test the agent's monotonic improvement.", "rules": [ diff --git a/protocols/core/csdc.protocol.json b/protocols/core/csdc.protocol.json index 5cf54be7..4a9497c3 100644 --- a/protocols/core/csdc.protocol.json +++ b/protocols/core/csdc.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "csdc-001", "description": "A protocol for the Context-Sensitive Development Cycle (CSDC), which introduces development models based on logical constraints.", "rules": [ diff --git a/protocols/core/doc_builder.protocol.json b/protocols/core/doc_builder.protocol.json index 7f932466..3132db6f 100644 --- a/protocols/core/doc_builder.protocol.json +++ b/protocols/core/doc_builder.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "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": [ diff --git a/protocols/core/file-indexing.protocol.json b/protocols/core/file-indexing.protocol.json index e6319ea3..b0bb1af4 100644 --- a/protocols/core/file-indexing.protocol.json +++ b/protocols/core/file-indexing.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "file-indexing-001", "description": "A protocol for maintaining an up-to-date file index to accelerate tool performance.", "rules": [ diff --git a/protocols/core/hdl-proving.protocol.json b/protocols/core/hdl-proving.protocol.json index 6bc7166f..c6ed6871 100644 --- a/protocols/core/hdl-proving.protocol.json +++ b/protocols/core/hdl-proving.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "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": [ diff --git a/protocols/core/interaction.protocol.json b/protocols/core/interaction.protocol.json index ddf14bde..39267058 100644 --- a/protocols/core/interaction.protocol.json +++ b/protocols/core/interaction.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "agent-interaction-001", "description": "A protocol governing the agent's core interaction and planning tools.", "rules": [ diff --git a/protocols/core/plllu-execution.protocol.json b/protocols/core/plllu-execution.protocol.json index 282b8f7e..8639d401 100644 --- a/protocols/core/plllu-execution.protocol.json +++ b/protocols/core/plllu-execution.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "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": [ diff --git a/protocols/core/speculative_execution.protocol.json b/protocols/core/speculative_execution.protocol.json index daa4938a..bd13fb02 100644 --- a/protocols/core/speculative_execution.protocol.json +++ b/protocols/core/speculative_execution.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "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": [ diff --git a/protocols/protocol.schema.json b/protocols/protocol.schema.json index 427fe8bc..b26d5a1c 100644 --- a/protocols/protocol.schema.json +++ b/protocols/protocol.schema.json @@ -44,5 +44,12 @@ } } }, - "required": ["protocol_id", "description", "rules"] + "required": ["protocol_id", "description", "rules"], + "properties": { + "version": { + "description": "The version of the protocol, following semantic versioning.", + "type": "string", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + } + } } \ No newline at end of file diff --git a/protocols/security/00_security_header.protocol.json b/protocols/security/00_security_header.protocol.json index 656eb125..360d00a7 100644 --- a/protocols/security/00_security_header.protocol.json +++ b/protocols/security/00_security_header.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "security-header", "description": "Defines the identity and purpose of the Security Protocol document.", "rules": [] diff --git a/protocols/security/01_vulnerability_reporting.protocol.json b/protocols/security/01_vulnerability_reporting.protocol.json index 0523f45c..bbd9890d 100644 --- a/protocols/security/01_vulnerability_reporting.protocol.json +++ b/protocols/security/01_vulnerability_reporting.protocol.json @@ -1,4 +1,5 @@ { + "version": "1.0.0", "protocol_id": "security-vuln-reporting-001", "description": "Defines the official policy and procedure for reporting security vulnerabilities.", "rules": [ diff --git a/protocols/security/AGENTS.md b/protocols/security/AGENTS.md index 9350af4a..699c6dc9 100644 --- a/protocols/security/AGENTS.md +++ b/protocols/security/AGENTS.md @@ -14,8 +14,11 @@ This document outlines the security policies and procedures for this project. It --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "security-header", "description": "Defines the identity and purpose of the Security Protocol document.", "rules": [] @@ -25,8 +28,11 @@ This document outlines the security policies and procedures for this project. It --- +**Version:** 1.0.0 + ```json { + "version": "1.0.0", "protocol_id": "security-vuln-reporting-001", "description": "Defines the official policy and procedure for reporting security vulnerabilities.", "rules": [ diff --git a/protocols/self_improvement/01_self_improvement.protocol.json b/protocols/self_improvement/01_self_improvement.protocol.json new file mode 100644 index 00000000..bcae6d3f --- /dev/null +++ b/protocols/self_improvement/01_self_improvement.protocol.json @@ -0,0 +1,25 @@ +{ + "protocol_id": "self-improvement-protocol-001", + "version": "1.0.0", + "description": "A protocol governing the process for an agent to propose, implement, and validate improvements to the agent's own operational protocols and tools.", + "rules": [ + { + "rule_id": "sip-001-proposal", + "description": "Any proposed change to the protocol system must be formalized as a Self-Improvement Proposal (SIP) and submitted to the `proposals/` directory. The SIP must include a detailed description of the proposed change, its rationale, and a plan for implementation and verification.", + "enforcement": "A pre-submit check will verify that any changes to files in `protocols/` or `tooling/` are accompanied by a corresponding SIP in `proposals/`." + }, + { + "rule_id": "sip-002-implementation", + "description": "The implementation of an approved SIP must be developed on a separate feature branch. The branch name must follow the pattern `feature/sip-XXX`, where `XXX` is the SIP number.", + "enforcement": "The git pre-push hook will reject any pushes to the main branch that contain changes to the protocol system." + }, + { + "rule_id": "sip-003-verification", + "description": "All changes to the protocol system must be accompanied by corresponding tests in the `tests/protocols/` directory. The tests must be executed and pass before the SIP can be merged.", + "enforcement": "The continuous integration (CI) system will run the protocol tests and block any pull requests that have failing tests." + } + ], + "associated_tools": [ + "tooling/protocol_manager.py" + ] +} \ No newline at end of file diff --git a/protocols/self_improvement/01_self_improvement.protocol.md b/protocols/self_improvement/01_self_improvement.protocol.md new file mode 100644 index 00000000..55c745c2 --- /dev/null +++ b/protocols/self_improvement/01_self_improvement.protocol.md @@ -0,0 +1,31 @@ +# Protocol: Agent Self-Improvement + +This protocol governs the process by which an agent can propose, implement, and validate improvements to its own operational protocols and tools. It is the foundation of the agent's ability to learn and evolve. + +## The Challenge: Uncontrolled Evolution + +An agent with the ability to modify its own operating parameters is a powerful concept, but it also presents a significant risk. Uncontrolled or untested changes could lead to a degradation of performance, the introduction of security vulnerabilities, or even a complete loss of functionality. + +## The Solution: A Structured Self-Improvement Process + +This protocol establishes a formal, three-step process for all self-improvement activities, ensuring that all changes are deliberate, tested, and verifiable. + +### 1. Proposal (SIP) + +**Rule `sip-001-proposal`**: Any proposed change to the protocol system must be formalized as a Self-Improvement Proposal (SIP). + +This rule ensures that every change begins with a clear, well-documented proposal. The SIP serves as a design document, forcing the agent to think through the implications of its proposed changes before it begins implementation. + +### 2. Implementation + +**Rule `sip-002-implementation`**: The implementation of an approved SIP must be developed on a separate feature branch. + +This rule isolates the development of new features, preventing unstable code from disrupting the main branch. + +### 3. Verification + +**Rule `sip-003-verification`**: All changes to the protocol system must be accompanied by corresponding tests. + +This is the most critical rule in the protocol. It ensures that every change is tested and validated before it is integrated into the system. This is the primary safeguard against unintended consequences. + +By following this protocol, the agent can safely and effectively improve its own capabilities over time, leading to a more robust, reliable, and intelligent system. \ No newline at end of file diff --git a/protocols/self_improvement/AGENTS.md b/protocols/self_improvement/AGENTS.md new file mode 100644 index 00000000..c177470a --- /dev/null +++ b/protocols/self_improvement/AGENTS.md @@ -0,0 +1,90 @@ +# --- +# 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 `self_improvement/` directory. +# +# This file contains the compiled protocols in a human-readable Markdown format, +# with machine-readable JSON definitions embedded. +# --- + +# Protocol: Agent Self-Improvement + +This protocol governs the process by which an agent can propose, implement, and validate improvements to its own operational protocols and tools. It is the foundation of the agent's ability to learn and evolve. + +## The Challenge: Uncontrolled Evolution + +An agent with the ability to modify its own operating parameters is a powerful concept, but it also presents a significant risk. Uncontrolled or untested changes could lead to a degradation of performance, the introduction of security vulnerabilities, or even a complete loss of functionality. + +## The Solution: A Structured Self-Improvement Process + +This protocol establishes a formal, three-step process for all self-improvement activities, ensuring that all changes are deliberate, tested, and verifiable. + +### 1. Proposal (SIP) + +**Rule `sip-001-proposal`**: Any proposed change to the protocol system must be formalized as a Self-Improvement Proposal (SIP). + +This rule ensures that every change begins with a clear, well-documented proposal. The SIP serves as a design document, forcing the agent to think through the implications of its proposed changes before it begins implementation. + +### 2. Implementation + +**Rule `sip-002-implementation`**: The implementation of an approved SIP must be developed on a separate feature branch. + +This rule isolates the development of new features, preventing unstable code from disrupting the main branch. + +### 3. Verification + +**Rule `sip-003-verification`**: All changes to the protocol system must be accompanied by corresponding tests. + +This is the most critical rule in the protocol. It ensures that every change is tested and validated before it is integrated into the system. This is the primary safeguard against unintended consequences. + +By following this protocol, the agent can safely and effectively improve its own capabilities over time, leading to a more robust, reliable, and intelligent system. + +--- + +**Version:** 1.0.0 + +```json +{ + "protocol_id": "self-improvement-protocol-001", + "version": "1.0.0", + "description": "A protocol governing the process for an agent to propose, implement, and validate improvements to the agent's own operational protocols and tools.", + "rules": [ + { + "rule_id": "sip-001-proposal", + "description": "Any proposed change to the protocol system must be formalized as a Self-Improvement Proposal (SIP) and submitted to the `proposals/` directory. The SIP must include a detailed description of the proposed change, its rationale, and a plan for implementation and verification.", + "enforcement": "A pre-submit check will verify that any changes to files in `protocols/` or `tooling/` are accompanied by a corresponding SIP in `proposals/`." + }, + { + "rule_id": "sip-002-implementation", + "description": "The implementation of an approved SIP must be developed on a separate feature branch. The branch name must follow the pattern `feature/sip-XXX`, where `XXX` is the SIP number.", + "enforcement": "The git pre-push hook will reject any pushes to the main branch that contain changes to the protocol system." + }, + { + "rule_id": "sip-003-verification", + "description": "All changes to the protocol system must be accompanied by corresponding tests in the `tests/protocols/` directory. The tests must be executed and pass before the SIP can be merged.", + "enforcement": "The continuous integration (CI) system will run the protocol tests and block any pull requests that have failing tests." + } + ], + "associated_tools": [ + "tooling/protocol_manager.py" + ] +} +``` + + +--- + + + +# --- Associated Tool Documentation --- + +## `protocol_manager.py` + +A command-line tool for managing agent protocols. + +This script provides a set of commands for creating, testing, and versioning +agent protocols. It is designed to be used by developers to manage the +protocol lifecycle. + +--- diff --git a/tests/protocols/test_runner.py b/tests/protocols/test_runner.py new file mode 100644 index 00000000..f793f909 --- /dev/null +++ b/tests/protocols/test_runner.py @@ -0,0 +1,14 @@ +import unittest +import os + +def run_tests(): + """ + Discovers and runs all protocol tests. + """ + loader = unittest.TestLoader() + suite = loader.discover(os.path.dirname(__file__), pattern="test_*.py") + runner = unittest.TextTestRunner() + runner.run(suite) + +if __name__ == "__main__": + run_tests() \ No newline at end of file diff --git a/tests/protocols/test_self_improvement_protocol_001.py b/tests/protocols/test_self_improvement_protocol_001.py new file mode 100644 index 00000000..01261997 --- /dev/null +++ b/tests/protocols/test_self_improvement_protocol_001.py @@ -0,0 +1,35 @@ +import unittest +import json +import os + +class TestSelfImprovementProtocol(unittest.TestCase): + + def setUp(self): + """ + Load the self-improvement protocol from the JSON file. + """ + protocol_path = "protocols/self_improvement/01_self_improvement.protocol.json" + with open(protocol_path, "r") as f: + self.protocol = json.load(f) + + def test_protocol_id(self): + """ + Test that the protocol has the correct ID. + """ + self.assertEqual(self.protocol["protocol_id"], "self-improvement-protocol-001") + + def test_rules_exist(self): + """ + Test that the protocol has the expected number of rules. + """ + self.assertEqual(len(self.protocol["rules"]), 3) + + def test_associated_tool_exists(self): + """ + Test that the associated tool exists in the tooling directory. + """ + tool_path = self.protocol["associated_tools"][0] + self.assertTrue(os.path.exists(tool_path), f"Tool not found at {tool_path}") + +if __name__ == "__main__": + unittest.main() \ No newline at end of file diff --git a/tooling/protocol_compiler.py b/tooling/protocol_compiler.py index 88ab8fa5..47f8a73a 100644 --- a/tooling/protocol_compiler.py +++ b/tooling/protocol_compiler.py @@ -46,7 +46,8 @@ def install_dependencies(): install_dependencies() import jsonschema -from rdflib import Graph +from rdflib import Graph, Namespace, URIRef, Literal +from rdflib.namespace import RDF, RDFS # --- Configuration --- ROOT_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..")) @@ -131,26 +132,48 @@ def compile_single_module(source_dir, target_file, schema_file, knowledge_graph= all_associated_tools.update(protocol_data["associated_tools"]) if knowledge_graph is not None: - protocol_data_for_ld = protocol_data.copy() - context_path = os.path.join(source_dir, "protocol.context.jsonld") - if os.path.exists(context_path): - relative_context_path = os.path.relpath(context_path, os.path.dirname(file_path)) - protocol_data_for_ld["@context"] = relative_context_path - base_uri = "file://" + os.path.abspath(os.path.dirname(file_path)) + "/" - knowledge_graph.parse(data=json.dumps(protocol_data_for_ld), format="json-ld", publicID=base_uri) + PROTO = Namespace("https://w3id.org/ai-protocol/v1/") + protocol_uri = URIRef(f"urn:protocol:{protocol_data['protocol_id']}") + version = protocol_data.get("version", "N/A") + version_uri = URIRef(f"urn:protocol:{protocol_data['protocol_id']}:version:{version}") + + knowledge_graph.add((protocol_uri, RDF.type, PROTO.Protocol)) + knowledge_graph.add((protocol_uri, RDFS.label, Literal(protocol_data['description']))) + knowledge_graph.add((protocol_uri, PROTO.hasVersion, version_uri)) + + knowledge_graph.add((version_uri, RDF.type, PROTO.ProtocolVersion)) + knowledge_graph.add((version_uri, RDFS.label, Literal(f"Version {version} of {protocol_data['protocol_id']}"))) + knowledge_graph.add((version_uri, PROTO.versionString, Literal(version))) + + for rule in protocol_data.get("rules", []): + rule_uri = URIRef(f"urn:protocol:{protocol_data['protocol_id']}:rule:{rule['rule_id']}") + knowledge_graph.add((version_uri, PROTO.hasRule, rule_uri)) + knowledge_graph.add((rule_uri, RDF.type, PROTO.Rule)) + knowledge_graph.add((rule_uri, RDFS.label, Literal(rule['description']))) + + test_file_path = os.path.join(ROOT_DIR, "tests", "protocols", f"test_{protocol_data['protocol_id']}.py") + if os.path.exists(test_file_path): + test_uri = URIRef(f"urn:test:file:{os.path.relpath(test_file_path, ROOT_DIR)}") + knowledge_graph.add((rule_uri, PROTO.hasTest, test_uri)) + knowledge_graph.add((test_uri, RDF.type, PROTO.Test)) + knowledge_graph.add((test_uri, RDFS.label, Literal(f"Test for {protocol_data['protocol_id']}"))) json_string = json.dumps(protocol_data, indent=2) - md_json_block = f"```json\n{json_string}\n```\n" + version = protocol_data.get("version", "N/A") + md_json_block = f"**Version:** {version}\n\n```json\n{json_string}\n```\n" final_content.append(md_json_block) final_content.append("\n---\n") if all_associated_tools: final_content.append("\n\n# --- Associated Tool Documentation ---\n") for tool_path in sorted(list(all_associated_tools)): - tool_readme_path = os.path.join(ROOT_DIR, os.path.dirname(tool_path), "README.md") - if os.path.exists(tool_readme_path): - with open(tool_readme_path, "r") as f: - final_content.append(f.read()) - final_content.append("\n---\n") + tool_abs_path = os.path.join(ROOT_DIR, tool_path) + if os.path.exists(tool_abs_path): + with open(tool_abs_path, "r") as f: + tool_content = f.read() + match = re.search(r'\"\"\"(.*?)\"\"\"', tool_content, re.DOTALL) + if match: + docstring = match.group(1).strip() + final_content.append(f"## `{os.path.basename(tool_path)}`\n\n{docstring}\n\n---\n") final_output_string = "\n".join(final_content) temp_target_file = target_file + ".tmp" @@ -159,7 +182,7 @@ def compile_single_module(source_dir, target_file, schema_file, knowledge_graph= f.write(final_output_string) os.rename(temp_target_file, target_file) -def compile_module_wrapper(path_to_protocol_dir): +def compile_module_wrapper(path_to_protocol_dir, knowledge_graph=None): target_md_file = os.path.join(path_to_protocol_dir, "AGENTS.md") schema_file = os.path.join(ROOT_PROTOCOLS_DIR, "protocol.schema.json") try: @@ -167,6 +190,7 @@ def compile_module_wrapper(path_to_protocol_dir): source_dir=path_to_protocol_dir, target_file=target_md_file, schema_file=schema_file, + knowledge_graph=knowledge_graph ) return True, path_to_protocol_dir except Exception as e: diff --git a/tooling/protocol_manager.py b/tooling/protocol_manager.py new file mode 100644 index 00000000..13c83e68 --- /dev/null +++ b/tooling/protocol_manager.py @@ -0,0 +1,83 @@ +""" +A command-line tool for managing agent protocols. + +This script provides a set of commands for creating, testing, and versioning +agent protocols. It is designed to be used by developers to manage the +protocol lifecycle. +""" +import argparse +import os +import json + +def create_protocol(name, directory): + """ + Creates a new protocol from a template. + """ + protocol_id = name.lower().replace(" ", "-") + protocol_file_name = f"{protocol_id}.protocol.json" + protocol_path = os.path.join(directory, protocol_file_name) + + if os.path.exists(protocol_path): + print(f"Error: Protocol '{protocol_id}' already exists.") + return + + protocol_data = { + "protocol_id": protocol_id, + "version": "1.0.0", + "description": f"A protocol for {name}.", + "rules": [], + "associated_tools": [] + } + + with open(protocol_path, "w") as f: + json.dump(protocol_data, f, indent=2) + + print(f"Created protocol '{protocol_id}' at {protocol_path}") + +def main(): + """ + Main function for the protocol manager. + """ + parser = argparse.ArgumentParser(description="A tool for managing agent protocols.") + subparsers = parser.add_subparsers(dest="command") + + # Create command + create_parser = subparsers.add_parser("create", help="Create a new protocol.") + create_parser.add_argument("name", help="The name of the protocol.") + create_parser.add_argument("--dir", default="protocols", help="The directory to create the protocol in.") + + # Version command + version_parser = subparsers.add_parser("version", help="Update the version of a protocol.") + version_parser.add_argument("protocol_id", help="The ID of the protocol to update.") + version_parser.add_argument("version", help="The new version.") + + args = parser.parse_args() + + if args.command == "create": + create_protocol(args.name, args.dir) + elif args.command == "version": + update_version(args.protocol_id, args.version) + +def update_version(protocol_id, new_version): + """ + Updates the version of a protocol. + """ + for root, dirs, files in os.walk("protocols"): + for file in files: + if file == f"{protocol_id}.protocol.json": + protocol_path = os.path.join(root, file) + with open(protocol_path, "r") as f: + protocol_data = json.load(f) + + protocol_data["version"] = new_version + + with open(protocol_path, "w") as f: + json.dump(protocol_data, f, indent=2) + + print(f"Updated version of '{protocol_id}' to {new_version}") + return + + print(f"Error: Protocol '{protocol_id}' not found.") + +if __name__ == "__main__": + main() \ No newline at end of file