Quickstart (v1.2.0)

This guide will walk you through running your first cycle with the QonQrete system using one of three methods: CLI, VS Code extension, or JetBrains plugins.

CLI

To use the command‑line interface, install the qonqrete package and run:

# Deploy runtime (first time only)
qonqrete deploy

# Configure AI (first time only)
qonqrete config set-ai

# Create your task file
qonqrete tasq create tasq.md
# Edit tasq.md with your requirements

# Run!
qonqrete tasq run

# View results in qage_001/, qage_002/, etc.

VS Code

# 1. Open your project
code /path/to/my-project

# 2. Deploy runtime (first time only)
# Command: QonQrete: Deploy to Workspace

# 3. Configure AI (first time only)
# Command: QonQrete: Set AI Configuration

# 4. Create your task
# Command: QonQrete: Create tasq.md
# Edit tasq.md with your requirements

# 5. Run!
# Command: QonQrete: Run Tasq (Ctrl+Alt+Q)

# 6. View results in qage_001/, qage_002/, etc.

JetBrains / IntelliJ IDEs

# 1. Open your project in IntelliJ/WebStorm/etc.

# 2. Deploy runtime (first time only)
# Action: QonQrete: Deploy to Workspace

# 3. Configure AI (first time only)
# Action: QonQrete: Set AI Configuration

# 4. Create your task
# Action: QonQrete: Create tasq.md
# Edit tasq.md with your requirements

# 5. Run!
# Action: QonQrete: Run Tasq (Ctrl+Alt+Q)

# 6. View results in Tool Window → Qage Browser

Next steps

Refer to the rest of the documentation for a deeper dive into architecture, configuration, advanced commands, and best practices.

QonQrete - Secure AI Construction Loop System

QonQrete is a Secure AI Construction Loop System, using a Multi-Agent Pipeline Orchestrator in a Sandbox environment with YAML Configuration. In short: it spawns 3 AI agents in a sandbox/container and makes them work together on tasks. It can run with a hard requirement for user approval between steps, or in a fully autonomous mode where it keeps running until the user decides to stop it.

QonQrete is a multi-agent orchestration system designed for secure, observable, and human-in-the-loop software construction. It operates on the principle of a secure build environment (Qage), managed by a host-level orchestrator (Qrane).

This architecture ensures that AI-generated code and processes cannot affect the host system, providing a robust framework for autonomous and semi-autonomous development.

Major Improvements: The Dual-Core Memory System with Local Qontextor

This release enhances the Dual-Core Memory System by making the qontextor agent capable of running in a fully local mode. It now performs deterministic analysis of Python code using a sophisticated stack of local tools to generate structural and semantic context at high speed with zero token cost.

The Local Qontextor Stack

The local qontextor now uses a multi-layered approach to understand your code without sending it to an AI:

Layer	Technology	Purpose
1. Structure	Python AST	Extracts the fundamental structure of the code, including function and class names and their signatures.
2. High-Level Purpose	Docstrings	Parses docstrings to get a high-confidence understanding of what a function or class does.
3. Inferred Purpose	Verb Heuristics	When docstrings are missing, it infers the purpose of a function based on its name (e.g., `get_user` implies retrieval).
4. Type Inference	Jedi	Performs static analysis to understand types and relationships between different parts of the code.
5. Call Graph	PyCG	Generates a call graph to understand the dependencies and execution flow between functions and modules.

Fast vs. Complex Local Mode

The local qontextor can be configured in worqspace/config.yaml:

local_mode: 'fast': Uses the first four layers of the stack (AST, Docstrings, Heuristics, Jedi) for a very fast analysis.
local_mode: 'complex': Adds a fifth layer, using a local sentence-transformers model to create deep semantic embeddings of the code’s purpose. This allows for more advanced queries and a deeper understanding of the code, at the cost of a slightly slower analysis.

The Scenario: A medium-sized project (50 files, ~10,000 lines of code).

Raw Size: ~100,000 Tokens.

Metric	Old Approach (Send Full Code)	New Approach (Dual-Core)	Improvement
Context Sent	100,000 Tokens (Full Repo)	~4,000 Tokens (Skeletons)	~96% Reduction
Indexing Cost	High (AI-based)	Zero (Local analysis)	Infinitely Cheaper
Cost per Run	~$0.25 (GPT-4o)	~$0.01 (GPT-4o)	25x Cheaper
Speed	Slow (Huge prompt processing)	Fast (Tiny prompt)	~3x Faster
Memory	Persistent	Persistent & Infinite Context	Upgraded

Summary: You are paying 4% of the cost for 100% of the intelligence, with zero cost for indexing.

Version

Version: v1.0.4-stable (See VERSION file for the canonical version).

What’s New in v1.0.4

QontractGuard: Enforces QONTRACT invariants and rule sets — predictable, anti-drift runs
UserGate Mode: Per-cyQle human steering at every CheQpoint
File-Based Audit Trail: Complete artifact layout (tasq.d, briq.d, reqap.d, struqture, meta.yaml)
Inverted Briq Sensitivity (0–16): Higher number = more briqs. Default: 5
Batched Briq Generation: Blueprint → Fabrication for 50–250+ briqs without truncation
Non-Interactive Save (-n): Auto-save finished qonstructions to worqspace/qonstructions/
Bulletproof Language Detection: 400+ language keywords for all AI providers
100% WoNQ Matrix Pass Rate: 90 validation runs confirming production readiness

Note on TUI Mode and Agent Testing:

The Text-based User Interface (TUI) mode is currently under active development and may still have bugs. While the agent setup is dynamic, extensive testing is still required.

We welcome community contributions! If you encounter any issues or have suggestions, please report them. Your feedback is invaluable in helping us improve the system.

Core Principles

Isolation by Design: All agent execution occurs within the Qage, a Docker container that acts as a secure sandbox. The Qrane, running on the host, manages the workflow.
Configuration-Driven: The agent models and cycle limits are defined declaratively in worqspace/config.yaml.
File-Based Communication: Agents communicate by reading and writing markdown files to a shared worqspace/ volume, creating a transparent and auditable “chat history”.
Human-in-the-Loop Control: By default, a non-negotiable CheQpoint pauses the system after each cyQle. The user, acting as the gateQeeper, must review the results and provide explicit instructions to [Q]ontinue, [T]weaQ, or [X]Quit. This behavior can be configured to be autonomous by default.

Architecture Overview

qrane/: Contains the Python-based Qrane orchestrator and its command-line interface.
worqer/: Contains the individual AI agent scripts (instruQtor, construQtor, inspeQtor). It also includes specialized agents like qompressor for creating low-token context, qontextor for mapping the codebase, and calqulator for cost estimation.
worqspace/: The shared data plane. It contains all configuration, the initial tasQ, and all generated plans (briQ), summaries (exeQ), and reviews (reQap).

The Workflow CyQle

A cyQle consists of three main phases, orchestrated by the Qrane:

Plan (instruQtor): A qwen-max agent reads the high-level tasQ and creates a series of markdown briQ files, which contain a detailed, high-level plan for the executor agent.
Execute (construQtor): A qwen-max agent is invoked for each briQ. It reads the high-level plan and uses its own powerful agency and tools to generate all necessary files and code in the qodeyard/ directory.
Review (inspeQtor): A qwen-max agent reviews the code generated by the construQtor, assesses its quality, and produces a final reQap (review) with an assessment and suggestions for the next cycle.
CheQpoint (gateQeeper): The Qrane pauses the system and displays the reQap, waiting for the user’s command to proceed.

System Requirements

The Qrane orchestrator runs directly on the host, while the Qrew of AI agents runs inside a sandboxed container.

1. Docker

Docker is the default, essential runtime for the secure Qage environment.

macOS: Install Docker Desktop for Mac.
Linux:
- Debian/Ubuntu: sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io
- Fedora/CentOS: sudo dnf install dnf-plugins-core && sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo && sudo dnf install docker-ce docker-ce-cli containerd.io
Windows: Install Docker Desktop for Windows.

Note for Docker Desktop (macOS & Windows) Users: You MUST grant Docker permission to access the project directory. Go to Settings > Resources > File Sharing and add the path to your qonqrete project folder. This allows the worqspace volume to be mounted correctly.

2. Microsandbox (Optional)

As a lightweight alternative to Docker, you can use msb.

Installation: Follow the instructions at the official Microsandbox repository.
You can set msb as the default runtime in worqspace/pipeline_config.yaml.

Getting Started

For a full guide on setting up the environment and running your first cyQle, please see QUICKSTART.md.

API Key Configuration: Before running, you must export the API keys for the AI providers you intend to use. The system will automatically check for the necessary keys based on your worqspace/config.yaml.

export OPENAI_API_KEY='your-key'
export GOOGLE_API_KEY='your-key' (or GEMINI_API_KEY)
export ANTHROPIC_API_KEY='your-key'
export DEEPSEEK_API_KEY='your-key'

First, initialize the system. This builds the secure container environment.

# For Docker (default)
./qonqrete.sh init

# If you use Microsandbox
./qonqrete.sh init --msb

To run the system with the Text-based User Interface (TUI) and set an operational mode:

./qonqrete.sh run --tui --mode security

To run in autonomous mode with a specific task granularity:

./qonqrete.sh run --auto --briq-sensitivity 2

To force user-gated mode (overriding a config file set to auto):

./qonqrete.sh run --user

You can override the configured runtime using flags:

# Force run with Microsandbox
./qonqrete.sh run --msb

# Force run with Docker
./qonqrete.sh run --docker

To clean up the workspace and remove all previous run data:

# Force run with Microsandbox
./qonqrete.sh run --msb

# Force run with Docker
./qonqrete.sh run --docker

To clean up the workspace and remove all previous run data:

./qonqrete.sh clean

License

QonQrete is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This ensures that any modifications or derivative works deployed as a service must also be released as open source under the same license. See the LICENSE file for full text.

QonQrete Documentation

Version: v1.0.4-stable (See VERSION file for the canonical version).

This document provides a comprehensive overview of the QonQrete Secure AI Construction Loop System.

Architecture
Execution Flows
Agent & Orchestrator Logic
Configuration
Getting Started
Terminology

Architecture

This section contains Mermaid diagrams illustrating the complete architecture of the QonQrete system v1.0.4.

High-Level System Overview

flowchart TB
    subgraph HOST["🖥️ Host System"]
        User([👤 User])
        Shell[./qonqrete.sh]
        EnvFile[.env<br/>API Keys]
        Version[VERSION<br/>v1.0.4]
    end

    subgraph CONTAINER["🐳 Container Runtime"]
        subgraph QRANE["🏗️ Qrane Orchestrator"]
            Loader[loader.py<br/>Config Parser]
            TUI[tui.py<br/>Display Filter]
            PathMgr[paths.py<br/>Path Manager]
            MainLoop[qrane.py<br/>Main Loop]
        end

        subgraph AGENTS["🤖 Agent Pipeline"]
            direction TB
            
            subgraph LOCAL["⚡ Local Agents (Zero Cost)"]
                Qompressor[🦴 Qompressor<br/>Skeletonizer]
                Qontextor[🔍 Qontextor<br/>AST + Jedi + PyCG]
                CalQulator[🧮 CalQulator<br/>Cost Estimator]
                LoQal[✅ LoQal Verifier<br/>Syntax + Imports]
                QontractGuard[🛡️ QontractGuard<br/>Invariant Enforcer]
            end

            subgraph AI["🧠 AI Agents"]
                InstruQtor[📋 InstruQtor<br/>Briq Planner]
                ConstruQtor[🔨 ConstruQtor<br/>Code Generator]
                InspeQtor[🔎 InspeQtor<br/>Batched Reviewer]
            end

            subgraph CACHE["💾 Cache Layer"]
                Qontrabender[🌀 Qontrabender<br/>Hybrid Cache]
            end
        end

        subgraph LIBAI["🔌 AI Provider Abstraction"]
            LibAI[lib_ai.py]
            OpenAI[(OpenAI<br/>gpt-4.1-*)]
            Gemini[(Gemini<br/>2.5-flash/pro)]
            Anthropic[(Anthropic<br/>claude-*)]
            DeepSeek[(DeepSeek<br/>V3.2)]
            Qwen[(Qwen<br/>qwen3-coder)]
        end
    end

    subgraph WORQSPACE["📁 Worqspace Volume"]
        Config[config.yaml]
        PipeConfig[pipeline_config.yaml]
        TasQ[tasq.md]
        
        subgraph QAGE["📦 qage_timestamp/"]
            TasqD[tasq.d/]
            BriqD[briq.d/]
            BloqD[bloq.d/]
            QontextD[qontext.d/]
            Qodeyard[qodeyard/]
            ExeqD[exeq.d/]
            ReqapD[reqap.d/]
            StruqtureD[struqture/<br/>Logs]
            MetaYaml[meta.yaml]
        end
    end

    User --> Shell
    Shell --> EnvFile
    Shell --> Version
    Shell --> CONTAINER
    
    MainLoop --> Loader
    MainLoop --> TUI
    MainLoop --> PathMgr
    
    Loader --> Config
    Loader --> PipeConfig
    
    MainLoop --> Qompressor
    MainLoop --> Qontextor
    MainLoop --> CalQulator
    MainLoop --> InstruQtor
    MainLoop --> ConstruQtor
    MainLoop --> InspeQtor
    MainLoop --> Qontrabender
    
    ConstruQtor --> LoQal
    
    InstruQtor --> LibAI
    ConstruQtor --> LibAI
    InspeQtor --> LibAI
    
    LibAI --> OpenAI
    LibAI --> Gemini
    LibAI --> Anthropic
    LibAI --> DeepSeek
    LibAI --> Qwen
    
    TasQ --> InstruQtor
    InstruQtor --> BriqD
    
    Qodeyard --> Qompressor
    Qompressor --> BloqD
    
    Qodeyard --> Qontextor
    Qontextor --> QontextD
    
    BriqD --> CalQulator
    BloqD --> CalQulator
    
    BriqD --> ConstruQtor
    BloqD --> ConstruQtor
    ConstruQtor --> Qodeyard
    ConstruQtor --> ExeqD
    
    Qodeyard --> InspeQtor
    ExeqD --> InspeQtor
    InspeQtor --> ReqapD
    
    Qontrabender --> BloqD
    
    classDef host fill:#2d2d2d,stroke:#888,color:#fff
    classDef container fill:#1a3a1a,stroke:#4a4,color:#fff
    classDef local fill:#1a1a3a,stroke:#44a,color:#fff
    classDef ai fill:#3a1a1a,stroke:#a44,color:#fff
    classDef cache fill:#3a3a1a,stroke:#aa4,color:#fff
    classDef volume fill:#2a1a2a,stroke:#a4a,color:#fff
    classDef provider fill:#1a2a2a,stroke:#4aa,color:#fff
    
    class User,Shell,EnvFile,Version host
    class Qompressor,Qontextor,CalQulator,LoQal,QontractGuard local
    class InstruQtor,ConstruQtor,InspeQtor ai
    class Qontrabender cache
    class Config,PipeConfig,TasQ,TasqD,BriqD,BloqD,QontextD,Qodeyard,ExeqD,ReqapD,StruqtureD,MetaYaml volume
    class OpenAI,Gemini,Anthropic,DeepSeek,Qwen provider

Detailed Pipeline Flow

flowchart LR
    subgraph CYCLE["🔄 CyQle N"]
        direction TB
        
        Start([Start CyQle]) --> Qompressor
        
        subgraph PREP["1️⃣ Preparation Phase"]
            Qompressor[🦴 Qompressor<br/>Generate Skeletons]
            Qontextor[🔍 Qontextor<br/>Build Symbol Map]
            Qompressor --> Qontextor
        end
        
        subgraph PLAN["2️⃣ Planning Phase"]
            InstruQtor[📋 InstruQtor<br/>Decompose TasQ → BriQs]
            CalQulator[🧮 CalQulator<br/>Estimate Costs]
            Qontextor --> InstruQtor
            InstruQtor --> CalQulator
        end
        
        subgraph BUILD["3️⃣ Build Phase (Interleaved)"]
            direction TB
            ConstruQtor[🔨 ConstruQtor<br/>Generate Code]
            LoQal[✅ LoQal<br/>Verify Syntax]
            Retry{Retry?}
            
            CalQulator --> ConstruQtor
            ConstruQtor --> LoQal
            LoQal -->|FAIL| Retry
            Retry -->|Yes| ConstruQtor
            Retry -->|No| NextBriq
            LoQal -->|PASS| NextBriq[Next BriQ]
            NextBriq -->|More BriQs| ConstruQtor
        end
        
        subgraph REVIEW["4️⃣ Review Phase (Batched)"]
            InspeQtor[🔎 InspeQtor<br/>Batch Review All BriQs]
            MetaReview[📊 Meta-Review<br/>Consolidate Results]
            NextBriq -->|All Done| InspeQtor
            InspeQtor --> MetaReview
        end
        
        subgraph CACHE["5️⃣ Cache Phase"]
            Qontrabender[🌀 Qontrabender<br/>Save to Qache]
            MetaReview --> Qontrabender
        end
        
        subgraph CHECKPOINT["6️⃣ CheQpoint"]
            CheQpoint{User Decision}
            Qontrabender --> CheQpoint
            CheQpoint -->|Continue| NextCycle([CyQle N+1])
            CheQpoint -->|TweaQ| TweaQ[Modify TasQ]
            CheQpoint -->|Quit| Done([Exit])
            TweaQ --> NextCycle
        end
    end
    
    style PREP fill:#1a1a3a,stroke:#44a
    style PLAN fill:#2a1a2a,stroke:#a4a
    style BUILD fill:#3a1a1a,stroke:#a44
    style REVIEW fill:#1a3a1a,stroke:#4a4
    style CACHE fill:#3a3a1a,stroke:#aa4
    style CHECKPOINT fill:#2a2a2a,stroke:#888

ConstruQtor Build Loop (Interleaved Mode)

flowchart TB
    subgraph CONSTRUQTOR["🔨 ConstruQtor v0.8.8 - Per-BriQ Processing"]
        Start([Start]) --> LoadBriqs[Load BriQ Files]
        LoadBriqs --> ForEach{For Each BriQ}
        
        ForEach --> Attempt[Attempt 1/3]
        
        subgraph ATTEMPT["Build Attempt"]
            Attempt --> Context[Gather Context<br/>bloq.d + qontext.d]
            Context --> Prompt[Build AI Prompt]
            Prompt --> AICall[🧠 AI Generate Code]
            AICall --> Parse[Parse Response<br/>Extract Files]
            Parse --> Write[Write to qodeyard/]
        end
        
        subgraph VERIFY["LoQal Verification"]
            Write --> Syntax[Python compile]
            Syntax -->|Error| SyntaxFail[❌ Syntax Error]
            Syntax -->|OK| Imports[Check Imports]
            Imports -->|Warning| ImportWarn[⚠️ Import Warning]
            Imports -->|OK| Pass[✅ Passed]
        end
        
        SyntaxFail --> RetryCheck{Attempts < 3?}
        RetryCheck -->|Yes| Attempt
        RetryCheck -->|No| MarkFail[Mark FAILURE]
        
        ImportWarn --> WriteExeq
        Pass --> WriteExeq[Write exeQ Summary]
        MarkFail --> WriteExeq
        
        WriteExeq --> ForEach
        ForEach -->|Done| Complete([All BriQs Complete])
    end
    
    style ATTEMPT fill:#3a1a1a,stroke:#a44
    style VERIFY fill:#1a3a1a,stroke:#4a4

InspeQtor Batched Review Flow

flowchart TB
    subgraph INSPEQTOR["🔎 InspeQtor v0.8.8 - Two-Stage Batched Review"]
        Start([Start]) --> Gather[Gather All ExeQs<br/>from exeq.d/cyqleN/]
        
        subgraph STAGE1["Stage 1: Batched Per-BriQ Reviews"]
            Gather --> CalcBatches[Calculate Batches<br/>max 12 briqs, 60K tokens]
            CalcBatches --> ForBatch{For Each Batch}
            
            ForBatch --> BuildPrompt[Build Batch Prompt<br/>All BriQs + Code]
            BuildPrompt --> AIReview[🧠 AI Batch Review]
            AIReview --> ParseResults[Parse Results<br/>Extract Per-BriQ Status]
            ParseResults --> WriteReqaps[Write Individual<br/>reqap.md Files]
            WriteReqaps --> ForBatch
        end
        
        subgraph STAGE2["Stage 2: Meta-Review"]
            ForBatch -->|All Batches Done| GatherReqaps[Gather All ReQaps]
            GatherReqaps --> MetaPrompt[Build Meta Prompt]
            MetaPrompt --> MetaAI[🧠 AI Consolidate]
            MetaAI --> FinalReqap[Write Final ReQap<br/>Cycle Summary]
        end
        
        subgraph LOQAL["LoQal Verification"]
            FinalReqap --> LoQalCheck[Run Full Verification<br/>All qodeyard/ Files]
            LoQalCheck --> Report[Append to ReQap]
        end
        
        Report --> Done([Complete])
    end
    
    style STAGE1 fill:#1a3a1a,stroke:#4a4
    style STAGE2 fill:#3a3a1a,stroke:#aa4
    style LOQAL fill:#1a1a3a,stroke:#44a

Directory Structure

flowchart TB
    subgraph DIRS["📁 QonQrete Directory Structure"]
        direction TB
        
        subgraph ROOT["qonqrete/"]
            qonqrete_sh[qonqrete.sh<br/>Entry Point]
            VERSION[VERSION<br/>0.8.8]
            env[.env<br/>API Keys]
            Dockerfile[Dockerfile]
        end
        
        subgraph QRANE["qrane/"]
            qrane_py[qrane.py<br/>Orchestrator]
            loader[loader.py<br/>Config]
            paths[paths.py<br/>Paths]
            tui[tui.py<br/>Display]
            lib_funq[lib_funqtions.py<br/>Pricing]
        end
        
        subgraph WORQER["worqer/"]
            lib_ai[lib_ai.py<br/>AI Abstraction]
            instruqtor[instruqtor.py]
            construqtor[construqtor.py]
            inspeqtor[inspeqtor.py]
            qompressor[qompressor.py]
            qontextor[qontextor.py]
            qontrabender[qontrabender.py]
            calqulator[calqulator.py]
            loqal_verifier[loqal_verifier.py]
        end
        
        subgraph WORQSPACE["worqspace/"]
            config[config.yaml]
            pipeline[pipeline_config.yaml]
            tasq[tasq.md]
            sqrapyard[sqrapyard/<br/>Persistent Storage]
            
            subgraph QAGE["qage_YYYYMMDD_HHMMSS/"]
                briq_d[briq.d/<br/>Planned Steps]
                bloq_d[bloq.d/<br/>Skeletons]
                qontext_d[qontext.d/<br/>Symbol Maps]
                qodeyard_g[qodeyard/<br/>Generated Code]
                exeq_d[exeq.d/<br/>Build Summaries]
                reqap_d[reqap.d/<br/>Reviews]
                struqture[struqture/<br/>Logs]
            end
        end
        
        subgraph DOC["doc/"]
            docs[DOCUMENTATION.md<br/>RELEASE-NOTES.md<br/>QUICKSTART.md<br/>etc.]
        end
    end
    
    qonqrete_sh --> qrane_py
    qrane_py --> loader
    qrane_py --> paths
    qrane_py --> tui
    loader --> config
    loader --> pipeline
    
    qrane_py --> instruqtor
    qrane_py --> construqtor
    qrane_py --> inspeqtor
    
    instruqtor --> lib_ai
    construqtor --> lib_ai
    construqtor --> loqal_verifier
    inspeqtor --> lib_ai
    
    instruqtor --> briq_d
    qompressor --> bloq_d
    qontextor --> qontext_d
    construqtor --> qodeyard_g
    construqtor --> exeq_d
    inspeqtor --> reqap_d
    
    style ROOT fill:#2d2d2d,stroke:#888
    style QRANE fill:#1a3a1a,stroke:#4a4
    style WORQER fill:#3a1a1a,stroke:#a44
    style WORQSPACE fill:#2a1a2a,stroke:#a4a
    style QAGE fill:#3a3a1a,stroke:#aa4
    style DOC fill:#1a1a3a,stroke:#44a

Cost Flow Visualization

flowchart LR
    subgraph COSTS["💰 Token Cost Flow (v0.8.8)"]
        
        subgraph FREE["🆓 Zero Cost"]
            Qompressor[Qompressor<br/>Local Python]
            Qontextor[Qontextor<br/>AST + Jedi]
            CalQulator[CalQulator<br/>Local Math]
            LoQal[LoQal Verifier<br/>compile + imports]
            Qontrabender[Qontrabender<br/>Local Cache]
        end
        
        subgraph CHEAP["💵 Low Cost"]
            InstruQtor[InstruQtor<br/>gpt-4.1-nano<br/>$0.10/1M in]
            InspeQtorBatch[InspeQtor Batched<br/>gpt-4.1-mini<br/>$0.40/1M in]
        end
        
        subgraph MAIN["💰 Main Cost"]
            ConstruQtor[ConstruQtor<br/>gemini-2.5-flash<br/>$0.30/1M in]
        end
        
        subgraph TOTAL["📊 7 CyQle Estimate"]
            Est[InstruQtor: ~$0.01<br/>ConstruQtor: ~$1.50<br/>InspeQtor: ~$0.30<br/>───────────<br/>TOTAL: ~$2.00]
        end
    end
    
    FREE --> CHEAP
    CHEAP --> MAIN
    MAIN --> TOTAL
    
    style FREE fill:#1a3a1a,stroke:#4a4
    style CHEAP fill:#3a3a1a,stroke:#aa4
    style MAIN fill:#3a1a1a,stroke:#a44
    style TOTAL fill:#1a1a3a,stroke:#44a

Execution Flows

This section traces the end-to-end execution flows of the QonQrete system, from user command to the completion of a cycle.

1. Initialization Flow (`./qonqrete.sh init`)

User Input: User executes ./qonqrete.sh init. An optional --msb or --docker flag can be provided.
qonqrete.sh: The script parses the init command.
Runtime Detection: It checks for the --msb or --docker flags. If none are provided, it checks pipeline_config.yaml for a microsandbox: true setting. If not found, it defaults to Docker.
Container Build:
- If the runtime is docker, it executes docker build -t qonqrete-qage -f Dockerfile ..
- If the runtime is msb, it executes msb build . -t qonqrete-qage (or mbx).
Result: A container image named qonqrete-qage is created in the local registry of the selected runtime, ready for execution.

2. Main Execution Flow (`./qonqrete.sh run`)

User Input: User executes ./qonqrete.sh run. Optional flags like --auto, --user, and --tui can be included.
qonqrete.sh:
- Parses the run command and any additional flags.
- Reads the VERSION file and exports it as QONQ_VERSION.
- Creates a unique timestamped run directory (qage_<timestamp>) inside worqspace/.
- Sqrapyard Initialization: It checks the persistent worqspace/sqrapyard directory. If it contains files, they are copied into the new qage_<timestamp>/qodeyard. If sqrapyard/tasq.md exists, it’s copied to become the initial tasq for the first cycle.
- Copies configuration files into the new run directory.
- Constructs the docker run or msb run command, mounting the qage_<timestamp> directory and passing the necessary environment variables.
qrane.py (Inside the Container):
- The orchestrator starts.
- API Key Validation: It reads config.yaml to identify all unique AI providers being used for the current run. It then checks that the corresponding environment variables (e.g., OPENAI_API_KEY, DEEPSEEK_API_KEY) are set. If a required key for a configured provider is missing, it exits with a clear error message.
- It determines the UI mode (TUI/headless) and enters the main cyQle loop.
The cyQle Loop:
- The Qrane dynamically loads the agent pipeline from pipeline_config.yaml.
- It executes each agent in sequence.
The CheQpoint:
- qrane.py reads the final reQap.md of the cycle. . It pauses and prompts the user for input ([Q]ontinue, [T]weaQ, [X]Quit), unless in autonomous mode. The default behavior (autonomous vs. user-gated) is controlled by the cheqpoint option in config.yaml, and can be overridden by the --auto or --user flags.
Loop Continuation:
- If approved, the reQap.md is promoted to become the task for the next cycle.
- The cycle counter increments, and the loop repeats.
Exit: If the user quits, the loop breaks, the container exits, and the script finishes.

3. Cleanup Flow (`./qonqrete.sh clean`)

User Input: User executes ./qonqrete.sh clean.
qonqrete.sh:
- Searches for qage_* directories in worqspace/.
- Prompts the user for confirmation.
- If confirmed, it executes rm -rf worqspace/qage_*.
Result: The worqspace is cleared of all previous run data.

Agent & Orchestrator Logic

This section details the operational logic for the QonQrete system.

Orchestrator Logic (`qrane/qrane.py`)

The Qrane is the heart of the system.

Dynamic Pipeline Loading: On startup, the Qrane reads the worqspace/pipeline_config.yaml file. It iterates through the agents list defined in this file to build the execution pipeline for the cycle.
Generic Execution: For each agent in the pipeline, the orchestrator constructs the appropriate command-line arguments based on the script, input, and output fields in the config.
Centralized Paths: It utilizes the PathManager class to resolve all file and directory paths.

Default Agent Logic

The following describes the logic of the three default agents that constitute the standard QonQrete pipeline.

Core Abstraction: `worqer/lib_ai.py`

All agents utilize this central library to interact with AI models. It uses a hybrid approach:

Official Python Libraries: Used for OpenAI, Google Gemini, and Anthropic. These libraries read their respective API keys (OPENAI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY) directly from the environment.
Custom Provider: A custom, OpenAI-compatible provider located in sqeleton/deepseek_provider.py is used for DeepSeek. This method is more reliable and uses the DEEPSEEK_API_KEY from the environment.
CLI Wrapper: A wrapper around the @qwen-code/qwen-code CLI tool is used for Qwen models.

This provides a consistent and modular interface for all AI interactions.

1. `instruQtor` (The Planner)

Purpose: To decompose a high-level task (tasQ.md) into a series of small, actionable steps (briQ.md files).
Logic: It reads the task, constructs a detailed prompt for the AI, invokes the AI via lib_ai.py, and then parses the markdown response into individual briQ.md files.
Sensitivity: The level of detail in the breakdown can be controlled with the QONQ_SENSITIVITY environment variable, which corresponds to 10 predefined levels (0-9).
Context-Aware: It reads the contents of the qodeyard to provide the AI with the current state of the codebase.

2. `construQtor` (The Executor)

Purpose: To execute the steps from the briQ.md files and generate code.
Logic: It iterates through the briQ files sequentially. For each, it builds a prompt that includes the step’s instructions and the current state of the qodeyard directory. It then calls the AI to execute the step and writes the generated code to the qodeyard.

3. `inspeQtor` (The Reviewer)

Purpose: To review the construQtor’s work and provide feedback for the next cycle.
Logic: It gathers all generated code from the qodeyard, constructs a prompt instructing the AI to act as a senior code reviewer, and saves the AI’s assessment and suggestions to a reQap.md file.

Specialized Agents

The following agents can be added to the pipeline in pipeline_config.yaml to provide additional functionality.

1. `qompressor` (The Skeletonizer)

Purpose: To create a low-token, high-context representation of the codebase.
Logic: It mirrors the qodeyard directory into a new bloq.d directory. During the mirroring process, it strips the implementation bodies from source code files, keeping only the architectural elements like class/function signatures, imports, and docstrings. This “skeleton” provides the AI with the overall structure of the code at a fraction of the token cost.
Cost: Zero token cost. It’s a local pre-processing step.

2. `qontextor` (The Symbol Mapper)

Purpose: To generate a detailed, machine-readable map of the codebase’s symbols and their relationships.
Dual-Mode Logic:
- Local Mode (provider: local): This is the default mode. qontextor performs a deterministic analysis of Python files using a sophisticated stack of local tools. It extracts classes, functions, signatures, and purposes with high accuracy and speed, incurring zero token cost.
  - Python AST: Extracts the fundamental structure of the code.
  - Docstrings & Verb Heuristics: Determines the purpose of functions and classes.
  - Jedi: Provides type inference and cross-file understanding.
  - PyCG: Generates a call graph for dependency analysis.
  - Fast vs. Complex Mode: Can be configured in worqspace/config.yaml to run in a 'fast' (AST, Jedi, Heuristics) or 'complex' (adds deep semantic analysis with sentence-transformers) mode.
- AI Mode (provider: [ai_provider]): In this legacy mode, it uses the “skeletonized” output from the qompressor to analyze each file. It then uses an AI call to generate a YAML file for each source file, detailing its symbols (classes, functions, etc.), their signatures, their purpose, and their dependencies.
Cost: Incurs AI token costs only when an AI provider is specified. It’s best used for initial scans or when major architectural changes occur.

3. `calqulator` (The Cost Estimator)

Purpose: To provide a token and cost estimate for the upcoming construqtor cycle.
Logic: It analyzes the briQ.md files for the current cycle. Its calculation includes:
1. A base cost for the “skeletonized” project context from bloq.d.
2. The cost of the instructions in each briQ.md file.
3. A “deep read” cost for any specific files that are explicitly referenced within a briQ.
Output: It annotates each briQ.md file with its estimated token count and cost, and prints a detailed report to the console.
Cost: Zero token cost. It performs local calculations.

Configuration

The behavior of the QonQrete system can be configured in the worqspace/ directory.

config.yaml:
- cheqpoint: A boolean that sets the default execution mode. true (the default) enables user-gated cheqpoints. false makes the system autonomous by default. This can be overridden by the --user and --auto command-line flags.
- auto_cycle_limit: The maximum number of cyQles to run in autonomous mode. 0 means infinite.
- agents: The AI models to be used by each agent. You can also set the provider to local for agents that do not use AI.
pipeline_config.yaml:
- microsandbox: Set to true to make Microsandbox (msb) the default container runtime.
- agents: Defines the sequence of agents in the pipeline.

Getting Started

To get started with QonQrete, please see the QUICKSTART.md guide.

Terminology

For a complete list of the terminology used in the QonQrete system, please see the TERMINOLOGY.md file.

QonQrete Functional Tests

This document outlines a comprehensive suite of functional tests designed to validate the entire QonQrete application. These tests cover the command-line interface, core orchestration logic, agent behaviors, configuration options, and edge cases.

1. Environment and Setup Tests

1.1. `qonqrete.sh` CLI

2. Core Orchestration (`Qrane`) Tests

2.1. Run Modes

Manual Mode (Default):
- Run a task. Verify the system pauses at the “CheQpoint” after each cycle.
- At the CheQpoint, press ‘q’. Verify the system continues to the next cycle.
- At the CheQpoint, press ‘x’. Verify the system quits gracefully.
- At the CheQpoint, press ‘t’. Verify $EDITOR opens with the reqap.md file. After closing the editor, verify the prompt is shown again.
Autonomous Mode (--auto):
- Run with --auto. Verify the system runs through cycles without user interaction.
- In config.yaml, set auto_cycle_limit: 2. Run in auto mode. Verify the system stops after cycle 2 with a “Max cyQle limit hit” message.
- Set auto_cycle_limit: 0. Verify it runs until the task is complete or it fails.

2.2. Cheqpoint Configuration (`config.yaml`)

cheqpoint: true (Default):
- Set cheqpoint: true in config.yaml. Run ./qonqrete.sh run. Verify it runs in user-gated mode.
- With cheqpoint: true, run ./qonqrete.sh run --auto. Verify it correctly overrides the config and runs in autonomous mode.
cheqpoint: false:
- Set cheqpoint: false in config.yaml. Run ./qonqrete.sh run. Verify it runs in autonomous mode by default.
- With cheqpoint: false, run ./qonqrete.sh run --user. Verify it correctly overrides the config and runs in user-gated mode.

2.3. Cycle and File Management

I/O Flow: After a successful cycle 1, verify that cyqle1_reqap.md is correctly used to generate cyqle2_tasq.md.
Header Promotion: Check the content of cyqle2_tasq.md. It must contain a header with the “Assessment” status from the previous cycle.
Agent Failure: Introduce an error in an agent script (e.g., sys.exit(1) in construqtor.py). Run the system. Verify the cycle fails and the orchestration stops with an error message.
Logging: For a successful run, inspect struqture/. Verify a log file exists for each agent for each cycle (e.g., cyqle1_instruqtor.log).

3. Agent Configuration and Behavior

3.1. Dynamic Pipeline (`pipeline_config.yaml`)

Remove Agent:
- Comment out the inspeqtor agent from the config. Run one cycle. Verify the system stops after construqtor and waits at the CheQpoint (it may complain about a missing reqap file, this is expected).
Reorder Agents (Failure Test):
- Swap the construqtor and instruqtor blocks in the config. Run the system. Verify it fails immediately because construqtor cannot find its required briq.d/ input. This confirms the order is respected.

3.2. Agent Settings (`config.yaml`)

4. TUI Mode Tests (`--tui`)

5. Edge Cases and Error Handling

6. Multi-Platform Testing

7. Provider & Model Matrix Tests

These tests validate that QonQrete can switch between multiple AI providers and their most common models without crashing, misrouting prompts, or corrupting artifacts.

7.1 Provider / Model Catalog (Reference)

Use these as the canonical test set (adjust model IDs if your adapter uses different names):

OpenAI
- Primary: gpt-4o
- Secondary: gpt-4o-mini
Google / Gemini
- Primary: gemini-2.5-flash
- Secondary: gemini-2.5-pro
DeepSeek
- Primary: deepseek-chat
- Secondary: deepseek-coder
Claude
- Primary: claude-sonnet-4-5
- Secondary: claude-haiku-4-5
- Tertiary: claude-opus-4-5
Qwen
- Primary: qwen-max
- Secondary: qwen-turbo
- Tertiary: qwen-coder

All tests below assume the three agents are:

instruqtor
construqtor
inspeqtor

7.2 Single-Provider / All-Agents Smoke Tests

For each checkbox, set all three agents in config.yaml to the given provider and model, then run a short tasq with:

For each run, verify:

CyQle completes without Python errors or provider API errors.
struqture/ contains logs for all 3 agents for the cyQle.
briq.d/, exeq.d/, and reqap.d/ contain the expected artifacts.

7.3 Per-Agent Provider Rotation (One Agent at a Time)

Goal: prove each individual agent can be swapped through all providers/models while the others stay stable.

For these tests, keep two agents fixed on a known-good combo (e.g. openai / gpt-4o) and rotate the third.

7.3.1 instruqtor Provider/Model Sweep

Verify:

briq.d/ is always produced and non-empty.
No provider/model mismatch errors (e.g., unknown model, bad request).

7.3.2 construqtor Provider/Model Sweep

Verify:

exeq.d/cyqle{N}_summary.md is produced.
No provider/model errors and no missing briq input errors.

7.3.3 inspeqtor Provider/Model Sweep

Verify:

reqap.d/cyqle{N}_reqap.md is produced and well-formed.
No provider/model errors.
Fix instruqtor and construqtor to openai / gpt-4o.
Sweep inspeqtor through all (provider, model) combos.

Verify:

reqap.d/cyqle{N}_reqap.md is produced and well-formed.
No provider/model errors.

7.4 Mixed-Provider Matrix (Cross-Provider Triples)

This section aims to stress “mixed” setups where different agents talk to different providers.

Use the primary models only for this section:

OpenAI: gpt-4o
Gemini: gemini-2.5-flash
DeepSeek: deepseek-chat
Claude: claude-sonnet-4-5

7.4.1 Key Cross-Provider Scenarios

For each test, set providers/models as specified, then run ./qonqrete.sh run --auto:

instruqtor: OpenAI / gpt-4o construqtor: DeepSeek / deepseek-chat inspeqtor: OpenAI / gpt-4o
instruqtor: DeepSeek / deepseek-chat construqtor: OpenAI / gpt-4o inspeqtor: DeepSeek / deepseek-chat
instruqtor: DeepSeek / deepseek-chat construqtor: OpenAI / gpt-4o inspeqtor: Claude / claude-sonnet-4-5
instruqtor: OpenAI / gpt-4o construqtor: DeepSeek / deepseek-chat inspeqtor: Claude / claude-sonnet-4-5
instruqtor: Claude / claude-sonnet-4-5 construqtor: Gemini / gemini-2.5-flash inspeqtor: OpenAI / gpt-4o
instruqtor: Gemini / gemini-2.5-flash construqtor: DeepSeek / deepseek-chat inspeqtor: Claude / claude-sonnet-4-5

Verify for each:

No provider-specific tracebacks in logs.
All expected artifacts (briq.d/, exeq.d/, reqap.d/) are present.
struqture/ logs show correct provider/model per agent.

7.4.2 Full Provider Triple Matrix (Optional Exhaustive Sweep)

Optional but ideal for automation:

Programmatically iterate over all triples (P_instruqtor, P_construqtor, P_inspeqtor) in {openai, gemini, deepseek, claude}^3, using primary models, and run a short cyQle.

Record for each:

Whether the run completed successfully.
Any provider/model-specific errors.
Whether all three artifact directories were populated.

7.5 Model Variant Swaps Within a Provider

For each provider, validate swapping between its primary and secondary model with all agents set to the same provider.

Example for OpenAI:

All agents → openai / gpt-4o
All agents → openai / gpt-4o-mini
Mixed models: instruqtor: gpt-4o-mini, construqtor: gpt-4o, inspeqtor: gpt-4o-mini

Repeat equivalent tests for:

Gemini (flash vs pro)
DeepSeek (chat vs coder)
Claude (sonnet vs haiku)

Verify:

No “unknown model” or schema errors.
Prompt/response handling still works (no parsing crashes).

8. Mode & Briq Sensitivity Matrix Tests

These tests validate how QonQrete behaves across all combinations of:

Operational Modes (agent character / style)
- program
- enterprise
- performance
- security
- innovative
- balanced
Briq Sensitivity (task granularity)
- Integer 0–9
- 0 = Atomic (max splitting, many briqs)
- 5 = Balanced
- 9 = Monolithic (minimal splitting, ideally 1 briq)

Use the same complex tasq.md for all tests so differences come only from mode and briq settings.

8.1 Reference: Baseline Behavior

Baseline: Balanced / briq 5
- Set mode: balanced and briq_sensitivity: 5 in config.yaml.
- Run ./qonqrete.sh run --auto.
- Record:
  - Number of briqs in briq.d/.
  - Overall style of generated code/docs.
- This run is the reference for comparing all other combinations.

8.2 Single-Dimension Sweeps

8.2.1 Mode Sweep with Fixed Briq Sensitivity

Fix briq_sensitivity: 5 (balanced splitting).
For each mode value, run a full cyQle and record behavioral differences.
mode: program (10 briqs)
mode: enterprise (8 briqs)
mode: performance (9 briqs)
mode: security (10 briqs)
mode: innovative (10 briqs)
mode: balanced (8 briqs)

For each run, verify:

No runtime errors.
Style matches expectations (e.g. enterprise = more docs/logging; security = stricter checks; performance = optimizations, etc.).
Briq count remains roughly similar (only style changes, not splitting).

8.2.2 Briq Sensitivity Sweep with Fixed Mode

For each run, verify:

System completes without errors.
Number of files in briq.d/ decreases monotonically (or at least trends downward) as sensitivity increases.
At 0, you get many briqs; at 9, you get very few (ideally 1).

8.3 Full Mode × Briq Sensitivity Matrix

For this section, keep:

Same complex tasq.md
Same providers/models as a known-good baseline (e.g. all agents on openai / gpt-4o).

For each combination below:

Set mode and briq_sensitivity in config.yaml.
Run ./qonqrete.sh run --auto.
Record:
- Number of briqs in briq.d/
- Any notable style changes
- Any errors/exceptions

8.3.1 `mode: program`

8.3.2 `mode: enterprise`

8.3.3 `mode: performance`

8.3.4 `mode: security`

8.3.5 `mode: innovative`

8.3.6 `mode: balanced`

8.4 CLI Override Tests (`--mode` and `--briq-sensitivity`)

These verify that CLI flags override config.yaml correctly and interact well with the matrix.

Start with mode: balanced, briq_sensitivity: 5 in config.yaml.
Run:
- ./qonqrete.sh run --mode security --briq-sensitivity 0 (50 briqs)
- ./qonqrete.sh run --mode enterprise -b 9 (1 briq)
- ./qonqrete.sh run --mode performance -b 3 (20 briqs)
For each of the above, verify:
- No conflict between CLI flags and config.yaml.
- qrane.py logs the effective mode and briq sensitivity.

8.5 Edge & Regression Scenarios

9. WoNQ Matrix v1.0.0 Validation

9.1 Overview

The WoNQ Matrix is QonQrete’s comprehensive validation framework that tests every combination of sensitivity levels (0-9) and cycle counts (1-9) to ensure production readiness.

Test Date: December 29, 2025 Version: v1.0.0-stable Total Configurations: 90 (10 sensitivities × 9 cycles)

9.2 Results Summary

╔═══════════════════════════════════════════════════════════════╗
║                 WoNQ MATRIX RESULTS                           ║
╠═══════════════════════════════════════════════════════════════╣
║ Total Runs:           90 (100% coverage)                      ║
║ Clean Completions:    90 (100% success)                       ║
║ Champion Score:       658 (sensitivity=3, cycle=7)            ║
║ Global Average:       554                                     ║
║ Scores ≥600:          35.6%                                   ║
╚═══════════════════════════════════════════════════════════════╝

9.3 Key Findings

Sweet Spot Identified: Sensitivity 2-4 with 5-7 cycles produces the best results
Champion Configuration: sens=3, cycle=7 consistently hits peak performance (658/666)
Death Valleys Discovered:
- Cycle 8 shows consistent underperformance across all sensitivities
- Sensitivity ≥7 shows diminishing returns due to insufficient task decomposition

9.4 Full Matrix Heatmap

         Cycles →
         1    2    3    4    5    6    7    8    9
    ┌────────────────────────────────────────────────
  0 │ 380  420  455  490  510  540  520  450  480
  1 │ 395  435  470  505  530  560  545  470  495
  2 │ 410  450  490  525  555  590  580  500  520
S 3 │ 420  465  505  540  575  620  658  520  545  ← CHAMPION
e 4 │ 415  455  495  530  560  595  610  505  530
n 5 │ 400  440  480  515  545  575  590  490  515
s 6 │ 385  420  460  495  525  555  565  475  500
↓ 7 │ 365  400  440  470  500  530  545  460  485
  8 │ 340  375  410  445  475  505  520  445  465
  9 │ 310  340  375  410  440  470  490  420  445

9.5 Validated Features

Bulletproof Language Detection: 400+ language keywords working across all providers
Enforced Briq Sensitivity: All sensitivity levels produce correct briq ranges
Provider Compatibility:
- OpenAI GPT-4/GPT-4o: ✅ BULLETPROOF
- Google Gemini: ✅ BULLETPROOF
- Anthropic Claude: ✅ BULLETPROOF
- DeepSeek Coder: ✅ BULLETPROOF
- Qwen/Qwen2.5-Coder: ✅ BULLETPROOF

9.6 Cost Analysis

Configuration	Estimated Cost per Run
Simple project (sens=7, 4 cycles)	~$0.50
Medium project (sens=5, 6 cycles)	~$2.00
Complex project (sens=3, 7 cycles)	~$4.00

9.7 Recommended Defaults

Based on WoNQ Matrix results:

# config.yaml - Production defaults
briq_sensitivity: 7  # 3-5 briqs per cycle
auto_cycle_limit: 4  # Enough iterations for polish

For complex multi-service projects:

briq_sensitivity: 5  # 8-12 briqs per cycle
auto_cycle_limit: 6  # More iterations for comprehensive coverage

9.8 Test Artifacts

All 90 runs archived with:

Complete qodeyard/ output
All cycle logs in struqture/
Scoring breakdown per run
Provider API logs

QonQrete Documentation

Version: v1.0.4-stable (See VERSION file for the canonical version).

This document provides a comprehensive overview of the QonQrete Secure AI Construction Loop System.

Architecture
Execution Flows
Agent & Orchestrator Logic
Configuration
Getting Started
Terminology

Architecture

This section contains Mermaid diagrams illustrating the complete architecture of the QonQrete system v1.0.4.

High-Level System Overview

flowchart TB
    subgraph HOST["🖥️ Host System"]
        User([👤 User])
        Shell[./qonqrete.sh]
        EnvFile[.env<br/>API Keys]
        Version[VERSION<br/>v1.0.4]
    end

    subgraph CONTAINER["🐳 Container Runtime"]
        subgraph QRANE["🏗️ Qrane Orchestrator"]
            Loader[loader.py<br/>Config Parser]
            TUI[tui.py<br/>Display Filter]
            PathMgr[paths.py<br/>Path Manager]
            MainLoop[qrane.py<br/>Main Loop]
        end

        subgraph AGENTS["🤖 Agent Pipeline"]
            direction TB
            
            subgraph LOCAL["⚡ Local Agents (Zero Cost)"]
                Qompressor[🦴 Qompressor<br/>Skeletonizer]
                Qontextor[🔍 Qontextor<br/>AST + Jedi + PyCG]
                CalQulator[🧮 CalQulator<br/>Cost Estimator]
                LoQal[✅ LoQal Verifier<br/>Syntax + Imports]
                QontractGuard[🛡️ QontractGuard<br/>Invariant Enforcer]
            end

            subgraph AI["🧠 AI Agents"]
                InstruQtor[📋 InstruQtor<br/>Briq Planner]
                ConstruQtor[🔨 ConstruQtor<br/>Code Generator]
                InspeQtor[🔎 InspeQtor<br/>Batched Reviewer]
            end

            subgraph CACHE["💾 Cache Layer"]
                Qontrabender[🌀 Qontrabender<br/>Hybrid Cache]
            end
        end

        subgraph LIBAI["🔌 AI Provider Abstraction"]
            LibAI[lib_ai.py]
            OpenAI[(OpenAI<br/>gpt-4.1-*)]
            Gemini[(Gemini<br/>2.5-flash/pro)]
            Anthropic[(Anthropic<br/>claude-*)]
            DeepSeek[(DeepSeek<br/>V3.2)]
            Qwen[(Qwen<br/>qwen3-coder)]
        end
    end

    subgraph WORQSPACE["📁 Worqspace Volume"]
        Config[config.yaml]
        PipeConfig[pipeline_config.yaml]
        TasQ[tasq.md]
        
        subgraph QAGE["📦 qage_timestamp/"]
            BriqD[briq.d/]
            BloqD[bloq.d/]
            QontextD[qontext.d/]
            Qodeyard[qodeyard/]
            ExeqD[exeq.d/]
            ReqapD[reqap.d/]
            StruqtureD[struqture/<br/>Logs]
        end
    end

    User --> Shell
    Shell --> EnvFile
    Shell --> Version
    Shell --> CONTAINER
    
    MainLoop --> Loader
    MainLoop --> TUI
    MainLoop --> PathMgr
    
    Loader --> Config
    Loader --> PipeConfig
    
    MainLoop --> Qompressor
    MainLoop --> Qontextor
    MainLoop --> CalQulator
    MainLoop --> InstruQtor
    MainLoop --> ConstruQtor
    MainLoop --> InspeQtor
    MainLoop --> Qontrabender
    
    ConstruQtor --> LoQal
    
    InstruQtor --> LibAI
    ConstruQtor --> LibAI
    InspeQtor --> LibAI
    
    LibAI --> OpenAI
    LibAI --> Gemini
    LibAI --> Anthropic
    LibAI --> DeepSeek
    LibAI --> Qwen
    
    TasQ --> InstruQtor
    InstruQtor --> BriqD
    
    Qodeyard --> Qompressor
    Qompressor --> BloqD
    
    Qodeyard --> Qontextor
    Qontextor --> QontextD
    
    BriqD --> CalQulator
    BloqD --> CalQulator
    
    BriqD --> ConstruQtor
    BloqD --> ConstruQtor
    ConstruQtor --> Qodeyard
    ConstruQtor --> ExeqD
    
    Qodeyard --> InspeQtor
    ExeqD --> InspeQtor
    InspeQtor --> ReqapD
    
    Qontrabender --> BloqD
    
    classDef host fill:#2d2d2d,stroke:#888,color:#fff
    classDef container fill:#1a3a1a,stroke:#4a4,color:#fff
    classDef local fill:#1a1a3a,stroke:#44a,color:#fff
    classDef ai fill:#3a1a1a,stroke:#a44,color:#fff
    classDef cache fill:#3a3a1a,stroke:#aa4,color:#fff
    classDef volume fill:#2a1a2a,stroke:#a4a,color:#fff
    classDef provider fill:#1a2a2a,stroke:#4aa,color:#fff
    
    class User,Shell,EnvFile,Version host
    class Qompressor,Qontextor,CalQulator,LoQal,QontractGuard local
    class InstruQtor,ConstruQtor,InspeQtor ai
    class Qontrabender cache
    class Config,PipeConfig,TasQ,BriqD,BloqD,QontextD,Qodeyard,ExeqD,ReqapD,StruqtureD volume
    class OpenAI,Gemini,Anthropic,DeepSeek,Qwen provider

Detailed Pipeline Flow

flowchart LR
    subgraph CYCLE["🔄 CyQle N"]
        direction TB
        
        Start([Start CyQle]) --> Qompressor
        
        subgraph PREP["1️⃣ Preparation Phase"]
            Qompressor[🦴 Qompressor<br/>Generate Skeletons]
            Qontextor[🔍 Qontextor<br/>Build Symbol Map]
            Qompressor --> Qontextor
        end
        
        subgraph PLAN["2️⃣ Planning Phase"]
            InstruQtor[📋 InstruQtor<br/>Decompose TasQ → BriQs]
            CalQulator[🧮 CalQulator<br/>Estimate Costs]
            Qontextor --> InstruQtor
            InstruQtor --> CalQulator
        end
        
        subgraph BUILD["3️⃣ Build Phase (Interleaved)"]
            direction TB
            ConstruQtor[🔨 ConstruQtor<br/>Generate Code]
            LoQal[✅ LoQal<br/>Verify Syntax]
            Retry{Retry?}
            
            CalQulator --> ConstruQtor
            ConstruQtor --> LoQal
            LoQal -->|FAIL| Retry
            Retry -->|Yes| ConstruQtor
            Retry -->|No| NextBriq
            LoQal -->|PASS| NextBriq[Next BriQ]
            NextBriq -->|More BriQs| ConstruQtor
        end
        
        subgraph REVIEW["4️⃣ Review Phase (Batched)"]
            InspeQtor[🔎 InspeQtor<br/>Batch Review All BriQs]
            MetaReview[📊 Meta-Review<br/>Consolidate Results]
            NextBriq -->|All Done| InspeQtor
            InspeQtor --> MetaReview
        end
        
        subgraph CACHE["5️⃣ Cache Phase"]
            Qontrabender[🌀 Qontrabender<br/>Save to Qache]
            MetaReview --> Qontrabender
        end
        
        subgraph CHECKPOINT["6️⃣ CheQpoint"]
            CheQpoint{User Decision}
            Qontrabender --> CheQpoint
            CheQpoint -->|Continue| NextCycle([CyQle N+1])
            CheQpoint -->|TweaQ| TweaQ[Modify TasQ]
            CheQpoint -->|Quit| Done([Exit])
            TweaQ --> NextCycle
        end
    end
    
    style PREP fill:#1a1a3a,stroke:#44a
    style PLAN fill:#2a1a2a,stroke:#a4a
    style BUILD fill:#3a1a1a,stroke:#a44
    style REVIEW fill:#1a3a1a,stroke:#4a4
    style CACHE fill:#3a3a1a,stroke:#aa4
    style CHECKPOINT fill:#2a2a2a,stroke:#888

ConstruQtor Build Loop (Interleaved Mode)

flowchart TB
    subgraph CONSTRUQTOR["🔨 ConstruQtor v1.0.4 - Per-BriQ Processing"]
        Start([Start]) --> LoadBriqs[Load BriQ Files]
        LoadBriqs --> ForEach{For Each BriQ}
        
        ForEach --> Attempt[Attempt 1/3]
        
        subgraph ATTEMPT["Build Attempt"]
            Attempt --> Context[Gather Context<br/>bloq.d + qontext.d]
            Context --> Prompt[Build AI Prompt]
            Prompt --> AICall[🧠 AI Generate Code]
            AICall --> Parse[Parse Response<br/>Extract Files]
            Parse --> Write[Write to qodeyard/]
        end
        
        subgraph VERIFY["LoQal Verification"]
            Write --> Syntax[Python compile]
            Syntax -->|Error| SyntaxFail[❌ Syntax Error]
            Syntax -->|OK| Imports[Check Imports]
            Imports -->|Warning| ImportWarn[⚠️ Import Warning]
            Imports -->|OK| Pass[✅ Passed]
        end
        
        SyntaxFail --> RetryCheck{Attempts < 3?}
        RetryCheck -->|Yes| Attempt
        RetryCheck -->|No| MarkFail[Mark FAILURE]
        
        ImportWarn --> WriteExeq
        Pass --> WriteExeq[Write exeQ Summary]
        MarkFail --> WriteExeq
        
        WriteExeq --> ForEach
        ForEach -->|Done| Complete([All BriQs Complete])
    end
    
    style ATTEMPT fill:#3a1a1a,stroke:#a44
    style VERIFY fill:#1a3a1a,stroke:#4a4

InspeQtor Batched Review Flow

flowchart TB
    subgraph INSPEQTOR["🔎 InspeQtor v1.0.4 - Two-Stage Batched Review"]
        Start([Start]) --> Gather[Gather All ExeQs<br/>from exeq.d/cyqleN/]
        
        subgraph STAGE1["Stage 1: Batched Per-BriQ Reviews"]
            Gather --> CalcBatches[Calculate Batches<br/>max 12 briqs, 60K tokens]
            CalcBatches --> ForBatch{For Each Batch}
            
            ForBatch --> BuildPrompt[Build Batch Prompt<br/>All BriQs + Code]
            BuildPrompt --> AIReview[🧠 AI Batch Review]
            AIReview --> ParseResults[Parse Results<br/>Extract Per-BriQ Status]
            ParseResults --> WriteReqaps[Write Individual<br/>reqap.md Files]
            WriteReqaps --> ForBatch
        end
        
        subgraph STAGE2["Stage 2: Meta-Review"]
            ForBatch -->|All Batches Done| GatherReqaps[Gather All ReQaps]
            GatherReqaps --> MetaPrompt[Build Meta Prompt]
            MetaPrompt --> MetaAI[🧠 AI Consolidate]
            MetaAI --> FinalReqap[Write Final ReQap<br/>Cycle Summary]
        end
        
        subgraph LOQAL["LoQal Verification"]
            FinalReqap --> LoQalCheck[Run Full Verification<br/>All qodeyard/ Files]
            LoQalCheck --> Report[Append to ReQap]
        end
        
        Report --> Done([Complete])
    end
    
    style STAGE1 fill:#1a3a1a,stroke:#4a4
    style STAGE2 fill:#3a3a1a,stroke:#aa4
    style LOQAL fill:#1a1a3a,stroke:#44a

Directory Structure

flowchart TB
    subgraph DIRS["📁 QonQrete Directory Structure"]
        direction TB
        
        subgraph ROOT["qonqrete/"]
            qonqrete_sh[qonqrete.sh<br/>Entry Point]
            VERSION[VERSION<br/>0.8.8]
            env[.env<br/>API Keys]
            Dockerfile[Dockerfile]
        end
        
        subgraph QRANE["qrane/"]
            qrane_py[qrane.py<br/>Orchestrator]
            loader[loader.py<br/>Config]
            paths[paths.py<br/>Paths]
            tui[tui.py<br/>Display]
            lib_funq[lib_funqtions.py<br/>Pricing]
        end
        
        subgraph WORQER["worqer/"]
            lib_ai[lib_ai.py<br/>AI Abstraction]
            instruqtor[instruqtor.py]
            construqtor[construqtor.py]
            inspeqtor[inspeqtor.py]
            qompressor[qompressor.py]
            qontextor[qontextor.py]
            qontrabender[qontrabender.py]
            calqulator[calqulator.py]
            loqal_verifier[loqal_verifier.py]
        end
        
        subgraph WORQSPACE["worqspace/"]
            config[config.yaml]
            pipeline[pipeline_config.yaml]
            tasq[tasq.md]
            sqrapyard[sqrapyard/<br/>Persistent Storage]
            
            subgraph QAGE["qage_YYYYMMDD_HHMMSS/"]
                briq_d[briq.d/<br/>Planned Steps]
                bloq_d[bloq.d/<br/>Skeletons]
                qontext_d[qontext.d/<br/>Symbol Maps]
                qodeyard_g[qodeyard/<br/>Generated Code]
                exeq_d[exeq.d/<br/>Build Summaries]
                reqap_d[reqap.d/<br/>Reviews]
                struqture[struqture/<br/>Logs]
            end
        end
        
        subgraph DOC["doc/"]
            docs[DOCUMENTATION.md<br/>RELEASE-NOTES.md<br/>QUICKSTART.md<br/>etc.]
        end
    end
    
    qonqrete_sh --> qrane_py
    qrane_py --> loader
    qrane_py --> paths
    qrane_py --> tui
    loader --> config
    loader --> pipeline
    
    qrane_py --> instruqtor
    qrane_py --> construqtor
    qrane_py --> inspeqtor
    
    instruqtor --> lib_ai
    construqtor --> lib_ai
    construqtor --> loqal_verifier
    inspeqtor --> lib_ai
    
    instruqtor --> briq_d
    qompressor --> bloq_d
    qontextor --> qontext_d
    construqtor --> qodeyard_g
    construqtor --> exeq_d
    inspeqtor --> reqap_d
    
    style ROOT fill:#2d2d2d,stroke:#888
    style QRANE fill:#1a3a1a,stroke:#4a4
    style WORQER fill:#3a1a1a,stroke:#a44
    style WORQSPACE fill:#2a1a2a,stroke:#a4a
    style QAGE fill:#3a3a1a,stroke:#aa4
    style DOC fill:#1a1a3a,stroke:#44a

Cost Flow Visualization

flowchart LR
    subgraph COSTS["💰 Token Cost Flow (v1.0.4)"]
        
        subgraph FREE["🆓 Zero Cost"]
            Qompressor[Qompressor<br/>Local Python]
            Qontextor[Qontextor<br/>AST + Jedi]
            CalQulator[CalQulator<br/>Local Math]
            LoQal[LoQal Verifier<br/>compile + imports]
            Qontrabender[Qontrabender<br/>Local Cache]
        end
        
        subgraph CHEAP["💵 Low Cost"]
            InstruQtor[InstruQtor<br/>gpt-4.1-nano<br/>$0.10/1M in]
            InspeQtorBatch[InspeQtor Batched<br/>gpt-4.1-mini<br/>$0.40/1M in]
        end
        
        subgraph MAIN["💰 Main Cost"]
            ConstruQtor[ConstruQtor<br/>gemini-2.5-flash<br/>$0.30/1M in]
        end
        
        subgraph TOTAL["📊 7 CyQle Estimate"]
            Est[InstruQtor: ~$0.01<br/>ConstruQtor: ~$1.50<br/>InspeQtor: ~$0.30<br/>───────────<br/>TOTAL: ~$2.00]
        end
    end
    
    FREE --> CHEAP
    CHEAP --> MAIN
    MAIN --> TOTAL
    
    style FREE fill:#1a3a1a,stroke:#4a4
    style CHEAP fill:#3a3a1a,stroke:#aa4
    style MAIN fill:#3a1a1a,stroke:#a44
    style TOTAL fill:#1a1a3a,stroke:#44a

Execution Flows

This section traces the end-to-end execution flows of the QonQrete system, from user command to the completion of a cycle.

1. Initialization Flow (`./qonqrete.sh init`)

User Input: User executes ./qonqrete.sh init. An optional --msb or --docker flag can be provided.
qonqrete.sh: The script parses the init command.
Runtime Detection: It checks for the --msb or --docker flags. If none are provided, it checks pipeline_config.yaml for a microsandbox: true setting. If not found, it defaults to Docker.
Container Build:
- If the runtime is docker, it executes docker build -t qonqrete-qage -f Dockerfile ..
- If the runtime is msb, it executes msb build . -t qonqrete-qage (or mbx).
Result: A container image named qonqrete-qage is created in the local registry of the selected runtime, ready for execution.

2. Main Execution Flow (`./qonqrete.sh run`)

User Input: User executes ./qonqrete.sh run. Optional flags like --auto, --user, and --tui can be included.
qonqrete.sh:
- Parses the run command and any additional flags.
- Reads the VERSION file and exports it as QONQ_VERSION.
- Creates a unique timestamped run directory (qage_<timestamp>) inside worqspace/.
- Sqrapyard Initialization: It checks the persistent worqspace/sqrapyard directory. If it contains files, they are copied into the new qage_<timestamp>/qodeyard. If sqrapyard/tasq.md exists, it’s copied to become the initial tasq for the first cycle.
- Copies configuration files into the new run directory.
- Constructs the docker run or msb run command, mounting the qage_<timestamp> directory and passing the necessary environment variables.
qrane.py (Inside the Container):
- The orchestrator starts.
- API Key Validation: It reads config.yaml to identify all unique AI providers being used for the current run. It then checks that the corresponding environment variables (e.g., OPENAI_API_KEY, DEEPSEEK_API_KEY) are set. If a required key for a configured provider is missing, it exits with a clear error message.
- It determines the UI mode (TUI/headless) and enters the main cyQle loop.
The cyQle Loop:
- The Qrane dynamically loads the agent pipeline from pipeline_config.yaml.
- It executes each agent in sequence.
The CheQpoint:
- qrane.py reads the final reQap.md of the cycle. . It pauses and prompts the user for input ([Q]ontinue, [T]weaQ, [X]Quit), unless in autonomous mode. The default behavior (autonomous vs. user-gated) is controlled by the cheqpoint option in config.yaml, and can be overridden by the --auto or --user flags.
Loop Continuation:
- If approved, the reQap.md is promoted to become the task for the next cycle.
- The cycle counter increments, and the loop repeats.
Exit: If the user quits, the loop breaks, the container exits, and the script finishes.

3. Cleanup Flow (`./qonqrete.sh clean`)

User Input: User executes ./qonqrete.sh clean.
qonqrete.sh:
- Searches for qage_* directories in worqspace/.
- Prompts the user for confirmation.
- If confirmed, it executes rm -rf worqspace/qage_*.
Result: The worqspace is cleared of all previous run data.

Agent & Orchestrator Logic

This section details the operational logic for the QonQrete system.

Orchestrator Logic (`qrane/qrane.py`)

The Qrane is the heart of the system.

Dynamic Pipeline Loading: On startup, the Qrane reads the worqspace/pipeline_config.yaml file. It iterates through the agents list defined in this file to build the execution pipeline for the cycle.
Generic Execution: For each agent in the pipeline, the orchestrator constructs the appropriate command-line arguments based on the script, input, and output fields in the config.
Centralized Paths: It utilizes the PathManager class to resolve all file and directory paths.

Default Agent Logic

The following describes the logic of the three default agents that constitute the standard QonQrete pipeline.

Core Abstraction: `worqer/lib_ai.py`

All agents utilize this central library to interact with AI models. It uses a hybrid approach:

Official Python Libraries: Used for OpenAI, Google Gemini, and Anthropic. These libraries read their respective API keys (OPENAI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY) directly from the environment.
Custom Provider: A custom, OpenAI-compatible provider located in sqeleton/deepseek_provider.py is used for DeepSeek. This method is more reliable and uses the DEEPSEEK_API_KEY from the environment.
CLI Wrapper: A wrapper around the @qwen-code/qwen-code CLI tool is used for Qwen models.

This provides a consistent and modular interface for all AI interactions.

0. `tasqLeveler` (The Enhancer) - NEW in v0.9.0

Purpose: To automatically enhance tasq.md with golden path tests, dependency graphs, and mock infrastructure.
Runs Once: Only executes on Cycle 1, before InstruQtor.
Enhancements Added:
- 📦 Dependency Graph: Explicit module import hierarchy to prevent circular imports
- 🎯 Golden Path Tests: Code snippets that MUST work after each module is implemented
- 🧪 Mock Infrastructure: Mock servers/services for testing integrations
- 📋 Success Criteria: Global definition of what SUCCESS means
- ⏱️ Phase Priority: Guidance on what to focus on if running low on cycles
- 🔗 Base Classes: Abstract base classes for similar modules
Impact: +15-20% improvement in output quality by giving the AI explicit success criteria.
Backup: Original tasq is preserved as tasq_original.md.

1. `instruQtor` (The Planner)

Purpose: To decompose a high-level task (tasQ.md) into a series of small, actionable steps (briQ.md files).
Logic: It reads the task, constructs a detailed prompt for the AI, invokes the AI via lib_ai.py, and then parses the markdown response into individual briQ.md files.
Sensitivity: The level of detail in the breakdown can be controlled with the QONQ_SENSITIVITY environment variable, which corresponds to 10 predefined levels (0-9).
Context-Aware: It reads the contents of the qodeyard to provide the AI with the current state of the codebase.
Universal File Rule (v0.9.0+): InstruQtor enforces a simple rule that applies to ALL cycles:
- If a file EXISTS in qodeyard → create briqs to MODIFY/EXTEND it (never recreate)
- If a file DOESN’T EXIST → create briqs to CREATE it (new modules welcome)
This prevents the rebuild-from-scratch bug while maintaining full creative freedom.

2. `construQtor` (The Executor)

Purpose: To execute the steps from the briQ.md files and generate code.
Logic: It iterates through the briQ files sequentially. For each, it builds a prompt that includes the step’s instructions and the current state of the qodeyard directory. It then calls the AI to execute the step and writes the generated code to the qodeyard.

3. `inspeQtor` (The Reviewer)

Purpose: To review the construQtor’s work and provide feedback for the next cycle.
Logic: It gathers all generated code from the qodeyard, constructs a prompt instructing the AI to act as a senior code reviewer, and saves the AI’s assessment and suggestions to a reQap.md file.

Specialized Agents

The following agents can be added to the pipeline in pipeline_config.yaml to provide additional functionality.

1. `qompressor` (The Skeletonizer)

Purpose: To create a low-token, high-context representation of the codebase.
Logic: It mirrors the qodeyard directory into a new bloq.d directory. During the mirroring process, it strips the implementation bodies from source code files, keeping only the architectural elements like class/function signatures, imports, and docstrings. This “skeleton” provides the AI with the overall structure of the code at a fraction of the token cost.
Cost: Zero token cost. It’s a local pre-processing step.

2. `qontextor` (The Symbol Mapper)

Purpose: To generate a detailed, machine-readable map of the codebase’s symbols and their relationships.
Dual-Mode Logic:
- Local Mode (provider: local): This is the default mode. qontextor performs a deterministic analysis of Python files using a sophisticated stack of local tools. It extracts classes, functions, signatures, and purposes with high accuracy and speed, incurring zero token cost.
  - Python AST: Extracts the fundamental structure of the code.
  - Docstrings & Verb Heuristics: Determines the purpose of functions and classes.
  - Jedi: Provides type inference and cross-file understanding.
  - PyCG: Generates a call graph for dependency analysis.
  - Fast vs. Complex Mode: Can be configured in worqspace/config.yaml to run in a 'fast' (AST, Jedi, Heuristics) or 'complex' (adds deep semantic analysis with sentence-transformers) mode.
- AI Mode (provider: [ai_provider]): In this legacy mode, it uses the “skeletonized” output from the qompressor to analyze each file. It then uses an AI call to generate a YAML file for each source file, detailing its symbols (classes, functions, etc.), their signatures, their purpose, and their dependencies.
Cost: Incurs AI token costs only when an AI provider is specified. It’s best used for initial scans or when major architectural changes occur.

3. `calqulator` (The Cost Estimator)

Purpose: To provide a token and cost estimate for the upcoming construqtor cycle.
Logic: It analyzes the briQ.md files for the current cycle. Its calculation includes:
1. A base cost for the “skeletonized” project context from bloq.d.
2. The cost of the instructions in each briQ.md file.
3. A “deep read” cost for any specific files that are explicitly referenced within a briQ.
Output: It annotates each briQ.md file with its estimated token count and cost, and prints a detailed report to the console.
Cost: Zero token cost. It performs local calculations.

Configuration

The behavior of the QonQrete system can be configured in the worqspace/ directory.

config.yaml:
- cheqpoint: A boolean that sets the default execution mode. true (the default) enables user-gated cheqpoints. false makes the system autonomous by default. This can be overridden by the --user and --auto command-line flags.
- auto_cycle_limit: The maximum number of cyQles to run in autonomous mode. 0 means infinite.
- agents: The AI models to be used by each agent. You can also set the provider to local for agents that do not use AI.
pipeline_config.yaml:
- microsandbox: Set to true to make Microsandbox (msb) the default container runtime.
- agents: Defines the sequence of agents in the pipeline.

Getting Started

To get started with QonQrete, please see the QUICKSTART.md guide.

Terminology

For a complete list of the terminology used in the QonQrete system, please see the TERMINOLOGY.md file.

MINDSTACK_ARCH: QonQrete Brain Stack Architecture

This document provides a high-level architectural overview of the QonQrete brain stack, focusing on how skeletons, contexts, memories, and “briqs” (though briqs’ specific usage is still to be fully defined) are utilized by the orchestration layer and AI agents. The diagram below illustrates the flow and relationships between these components.

Architectural Diagram

graph TD
    subgraph "External World"
        USER[User Interaction] -- QONQ_WORKSPACE --> WQ(Worqspace Root)
        CODEBASE(Raw Codebase/Files) -- initial --> QY(qodeyard/)
    end

    subgraph "QonQrete Core Orchestration"
        Q(Qrane Orchestrator)
        PM[PathManager]
        LI[lib_ai]
    end

    subgraph "Knowledge / Memory Layers"
        BD[bloq.d (Structural Memory - Skeletons)]
        QD[qontext.d (Semantic Memory - Contexts)]
        RD[reqap.d/ (Operational Memory/Feedback)]
        TD[tasq.d/ (Current Task/Directive)]
        ED[exeq.d/ (Execution Summaries)]
        BRD[briq.d/ (Reusable Components?)]
    end

    subgraph "QonQrete Agents (worqer/)"
        QOM[Qompressor Agent]
        QON[Qontextor Agent]
        INST[Instruqtor Agent]
        CALQ[Calqulator Agent]
        CONST[Construqtor Agent]
        INSP[Inspeqtor Agent]
        GPT[LLM Provider - OpenAI/Gemini/DeepSeek/Qwen]
    end

    subgraph "External AI Providers"
        DS[DeepSeek Provider]
        OA[OpenAI Provider]
        GM[Gemini Provider]
        ANT[Anthropic Provider]
        QW[Qwen Provider]
    end


    QY -- processed by --> QOM
    QOM -- generates --> BD

    QY -- processed by (optionally compressed via QOM) --> QON
    QON -- queries --> GPT
    QON -- generates --> QD

    Q -- orchestrates agents --> INST
    Q -- orchestrates agents --> CALQ
    Q -- orchestrates agents --> CONST
    Q -- orchestrates agents --> INSP
    Q -- orchestrates agents --> QOM
    Q -- orchestrates agents --> QON

    INST -- task from --> TD
    CALQ -- uses --> BD & QD
    CONST -- uses --> BD & QD
    INSP -- assesses --> RD

    Q --- PM
    PM -- manages paths for --> QY, BD, QD, RD, TD, ED, BRD

    QOM -- structural input --> Q
    QON -- semantic input --> Q

    Q --- LI
    LI -- builds prompt for --> GPT
    LI -- integrates --> QD, BD, QONQ_PREVIOUS_LOG(Env Var), TD

    GPT -- via --> DS, OA, GM, ANT, QW

    INST, CALQ, CONST, INSP, QOM, QON -- generate output --> RD
    RD -- promotes to --> TD
    INST, CALQ, CONST, INSP, QOM, QON -- logs --> ED

    Q --- USER
    USER -- manual review/edit --> RD
    RD -- informs --> Q (via cheqpoint)

    click QY "https://github.com/qonqrete/qonqrete/tree/main/qodeyard" "Go to qodeyard folder"
    click BD "https://github.com/qonqrete/qonqrete/tree/main/bloq.d" "Go to bloq.d folder"
    click QD "https://github.com/qonqrete/qonqrete/tree/main/qontext.d" "Go to qontext.d folder"
    click RD "https://github.com/qonqrete/qonqrete/tree/main/reqap.d" "Go to reqap.d folder"
    click TD "https://github.com/qonqrete/qonqrete/tree/main/tasq.d" "Go to tasq.d folder"
    click ED "https://github.com/qonqrete/qonqrete/tree/main/exeq.d" "Go to exeq.d folder"
    click BRD "https://github.com/qonqrete/qonqrete/tree/main/briq.d" "Go to briq.d folder"

Explanation of Components

QonQrete Core Orchestration

Qrane Orchestrator (qrane.py): The central control unit. It manages the entire workflow, sequencing agent execution, handling “cheqpoints,” and interfacing with the user.
PathManager (qrane/paths.py): Provides a centralized way to manage all file paths within the worqspace, ensuring consistency and discoverability of knowledge artifacts.
lib_ai (worqer/lib_ai.py): The AI abstraction layer. It handles communication with various LLM providers, constructs rich prompts by integrating different context layers, and manages streaming responses.

Knowledge / Memory Layers

These are file-system based directories within the worqspace/ that store the system’s knowledge:

qodeyard/: The raw, unadulterated codebase or initial input files provided by the user. It’s the source of truth for all processing.
bloq.d/ (Structural Memory / Skeletons): Contains “qompressed” (skeletonized) code, representing the architectural structure of the codebase without implementation details. Generated by Qompressor.
qontext.d/ (Semantic Memory / Contexts): Stores AI-generated YAML summaries and structured semantic information about files (e.g., symbol definitions, purposes, dependencies). Generated by Qontextor.
reqap.d/ (Operational Memory / Feedback): Holds “reQap” files, which are assessments and outputs from previous agent runs. Used for feedback loops and human intervention.
tasq.d/ (Current Task / Directive): Contains the tasq.md files that specify the current objective and instructions for the agents in a given cycle. Typically derived from promoted reQaps.
exeq.d/ (Execution Summaries): Stores logs and summaries of agent executions, providing a historical record.
briq.d/ (Reusable Components): A placeholder for reusable code “briqs” or modules. Its exact usage and lifecycle are currently less defined but likely involves construqtor or other agents for generation and calqulator or inspeqtor for consumption.

QonQrete Agents (`worqer/`)

These are specialized Python scripts that perform specific tasks:

Qompressor Agent (qompressor.py): Responsible for code skeletonization, generating bloq.d from qodeyard.
Qontextor Agent (qontextor.py): Responsible for semantic indexing, generating qontext.d from qodeyard (potentially using bloq.d and LLMs).
Instruqtor Agent: Likely responsible for interpreting tasq.md and breaking it down into actionable steps for other agents.
Calqulator Agent: Implied to perform calculations or estimations, possibly using bloq.d and qontext.d.
Construqtor Agent: Implied to construct or generate code/configurations based on instructions, using the knowledge layers.
Inspeqtor Agent: Implied to inspect or review generated code/outputs, producing reQaps.

External AI Providers

This section represents the various Large Language Model APIs that lib_ai can interface with, including DeepSeek, OpenAI, Gemini, and Anthropic.

Workflow Summary

Initialization: The Qrane Orchestrator starts, reads config.yaml, and if qodeyard/ is present, it initiates a “warmup.”
Warmup: Qompressor processes qodeyard/ to create bloq.d (skeletons). Qontextor then processes qodeyard/ (leveraging bloq.d and LLMs via lib_ai) to create qontext.d (semantic contexts).
Cyclical Execution: In each cycle, Qrane retrieves the current tasq.md directive. It then orchestrates a sequence of agents (e.g., Instruqtor, Calqulator, Construqtor, Inspeqtor) based on pipeline_config.yaml.
Agent Interaction with LLMs: When an agent needs to use an LLM, it calls lib_ai.run_ai_completion. lib_ai constructs a rich prompt by combining the agent’s base prompt with relevant information from tasq.d, bloq.d, qontext.d, and the QONQ_PREVIOUS_LOG (operational memory). This prompt is sent to the configured LLM provider.
Feedback Loop: Agent outputs and assessments are captured in reqap.d. At cheqpoints, Qrane either autonomously promotes the reQap to form the next tasq.md or allows user intervention to review and edit it, closing the feedback loop.
Continuous Improvement: Qontextor also performs update scans, ensuring that the semantic context in qontext.d remains current with changes in qodeyard.

This architecture ensures that AI agents are provided with a structured, layered, and token-optimized understanding of the project, enabling them to operate more efficiently and effectively.

Qontrabender - The Cache Bender 🌀 (v0.8.0)

Local sovereignty over remote RAM - Policy-driven Variable Fidelity

Qontrabender is QonQrete’s sophisticated hybrid caching agent that manages context assembly with intelligent content classification. All behavior is controlled via caching_policy.yaml.

Key Features

Policy-Driven Configuration: All behavior controlled via caching_policy.yaml
Multiple Operational Modes: 6 pre-configured modes for different use cases
Variable Fidelity: Mixes MEAT (full code) + BONES (skeletons) intelligently
Schema Validation: Bad YAML can’t brick your flow
Improved Volatile Detection: Multiple signals (cycle, diff, git, mtime)
Fidelity Rules Engine: Configurable per-file treatment rules

The “Compositor” Pattern

┌─────────────────────────────────────────────────────────────────────────┐
│                    THE DATA LAKE (Local)                                │
│                                                                         │
│   qodeyard/ (MEAT)           bloq.d/ (BONES)        qontext.d/ (SOUL)   │
│   ├── api.py (FULL)          ├── api.py (SKEL)      ├── api.q.yaml      │
│   ├── models.py (FULL)       ├── models.py (SKEL)   ├── models.q.yaml   │
│   └── legacy_lib.py (FULL)   └── legacy_lib.py(SKEL)└── legacy.q.yaml   │
│                                                                         │
│             │                        │                      │           │
│             └───────────┬────────────┴──────────────────────┘           │
│                         ▼                                               │
│              ┌───────────────────────┐                                  │
│              │    QONTRABENDER       │                                  │
│              │   "The Compositor"    │                                  │
│              ├───────────────────────┤                                  │
│              │  caching_policy.yaml  │ ← Policy-driven behavior         │
│              │                       │                                  │
│              │ 1. Validate Schema    │ ← Prevent bad config             │
│              │ 2. Load Mode Config   │ ← 6 operational modes            │
│              │ 3. Detect Volatile    │ ← Multi-signal detection         │
│              │ 4. Evaluate Rules     │ ← Fidelity rules engine          │
│              │ 5. Assemble & Hash    │ ← Content-addressed caching      │
│              └──────────┬────────────┘                                  │
│                         ▼                                               │
│                   qache.d/ (The Ledger)                                 │
│                   ├── manifest.json         (local truth)               │
│                   ├── ledger.db             (hash→cache_id)             │
│                   ├── .active_cache_id      (for lib_ai.py)             │
│                   ├── sync.log              (audit trail)               │
│                   ├── decisions.log         (debug_repro mode)          │
│                   └── payloads/v*.txt       (version history)           │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                             │
                             │ (Optional: cyber_* modes)
                             ▼
                    [ Remote Cache API ]

Operational Modes

Select mode in config.yaml:

agents:
  qontrabender:
    policy_file: "./caching_policy.yaml"
    mode: "local_smart"  # ← Select your mode

Mode	Description	Remote Cache	Use Case
`local_fast`	Ultra-fast, skeleton only	❌	Quick iterations
`local_smart`	Variable fidelity, balanced	❌	Default - recommended
`cyber_bedrock`	Stable bedrock in remote cache	✅	Long-running projects
`cyber_aggressive`	Aggressive caching	✅	Big refactors
`paranoid_mincloud`	Skeletons only to cloud	✅	Security-conscious
`debug_repro`	Maximum audit logging	❌	Debugging issues

Mode Details

`local_fast`

No remote cache
Mostly skeleton + tiny hotset
Minimal disk I/O
Best for rapid iteration

`local_smart` (Recommended)

No remote cache dependency
Variable fidelity based on core score
Strong reproducibility
Best balance of context and efficiency

`cyber_bedrock`

Remote cache for stable files
Full code for high-utility files
TTL keepalive management
Low churn, good reuse

`cyber_aggressive`

More files in remote cache
Higher token budgets
More cache rebuilds
For “big refactor week”

`paranoid_mincloud`

Minimal cloud exposure
Only docs/schemas + skeletons uploaded
Secrets redaction enabled
For security-conscious environments

`debug_repro`

Maximum audit logging
Writes full payload artifacts
Detailed decision logs
For debugging and reproducibility

Configuration

config.yaml

agents:
  qontrabender:
    provider: local
    model: qontrabender
    policy_file: "./caching_policy.yaml"
    mode: local_smart

caching_policy.yaml Structure

version: 1

defaults:
  qache_dir: "qache.d"
  
  volatile_detection:
    use_changed_files_manifest: true
    changed_files_pattern: "exeq.d/*_changed.md"
    use_git_diff_if_available: true
    git_diff_base: "HEAD"
    use_mtime_fallback: true
    mtime_minutes: 15
    use_briq_targets: true
    briq_pattern: "briq.d/*.md"
  
  budgets:
    cached_max_chars: 1800000
    cached_target_chars: 1200000
    hotset_max_chars: 350000
    hotset_target_chars: 220000
  
  classification:
    signals:
      dependency_rank_weight: 0.50
      symbol_count_weight: 0.20
      inbound_refs_weight: 0.20
      doc_presence_weight: 0.10
    thresholds:
      core_score_min: 0.65
      massive_chars_min: 220000
  
  paths:
    exclude_globs:
      - "**/.git/**"
      - "**/node_modules/**"
      - "**/__pycache__/**"
  
  logging:
    verbose_decisions: false

modes:
  local_smart:
    description: "Default - variable fidelity, local only"
    remote_cache:
      enabled: false
    fidelity:
      rules:
        - name: "stable_core_full"
          when:
            tier: "stable"
            core_score_gte: 0.65
            file_chars_lte: 200000
          use: "full"
        - name: "massive_skeleton"
          when:
            file_chars_gte: 220000
          use: "skeleton"
        - name: "default"
          when: {}
          use: "skeleton"

qontext_schema:
  file_path_key: "file_path"
  symbols_key: "symbols"
  deps_key: "dependencies"

Fidelity Rules Engine

Rules are evaluated in order. First matching rule wins.

Rule Structure

fidelity:
  rules:
    - name: "rule_name"
      when:
        tier: "stable"           # stable | volatile
        volatile: false          # true | false
        core_score_gte: 0.65     # >= comparison
        core_score_lte: 0.90     # <= comparison
        file_chars_gte: 100000   # >= comparison
        file_chars_lte: 500000   # <= comparison
        dependency_count_gte: 5  # >= comparison
      use: "full"                # full | skeleton | diff | omit

Comparison Operators

Suffix	Meaning
`_gte`	Greater than or equal
`_lte`	Less than or equal
`_gt`	Greater than
`_lt`	Less than
(none)	Exact match

Volatile Detection

Files detected as “volatile” are excluded from cache and sent fresh via stdin.

Detection Signals (in priority order)

Changed Files Manifest: Files in exeq.d/*_changed.md
Briq Targets: Files targeted by current briq
Git Diff: git diff --name-only HEAD
Mtime Fallback: Files modified within mtime_minutes

volatile_detection:
  use_changed_files_manifest: true
  changed_files_pattern: "exeq.d/*_changed.md"
  use_git_diff_if_available: true
  git_diff_base: "HEAD"
  use_mtime_fallback: true
  mtime_minutes: 15
  use_briq_targets: true
  briq_pattern: "briq.d/*.md"

Core Score Calculation

Files are scored based on configurable weights:

classification:
  signals:
    dependency_rank_weight: 0.50   # How many deps this file has
    symbol_count_weight: 0.20      # Number of symbols defined
    inbound_refs_weight: 0.20      # How many files reference this
    doc_presence_weight: 0.10      # Has docstrings/comments

Score = (dep × 0.50) + (sym × 0.20) + (ref × 0.20) + (doc × 0.10)

Files with core_score >= 0.65 are typically considered “core logic”.

CLI Usage

# Check if sync needed (default mode from config)
python worqer/qontrabender.py

# Use specific mode
python worqer/qontrabender.py --mode cyber_bedrock

# Show current status
python worqer/qontrabender.py --status

# Analyze file fidelity decisions
python worqer/qontrabender.py --analyze

# Validate policy file
python worqer/qontrabender.py --validate

# List available modes
python worqer/qontrabender.py --modes

# Prepare payload for sync
python worqer/qontrabender.py --sync

# Mark as synced with cache ID
python worqer/qontrabender.py --mark-synced caches/xxxxx

# Get active cache ID (for scripts)
python worqer/qontrabender.py --get-cache-id

Example Output

—analyze

═══════════════════════════════════════════════════════════════════════════
  QONTRABENDER FILE ANALYSIS (Mode: local_smart)
═══════════════════════════════════════════════════════════════════════════

  🥩 FULL FIDELITY (8 files):
    models.py                               score=0.85 deps=12  ~4,500 tok
    api.py                                  score=0.78 deps=9   ~3,200 tok
    auth.py                                 score=0.71 deps=7   ~2,100 tok
    utils.py                                score=0.65 deps=5   ~1,800 tok

  🦴 SKELETON FIDELITY (3 files):
    legacy_vendor_lib.py                    Massive file (120,000 chars)
    generated_proto.py                      Massive file (85,000 chars)

  ⚡ VOLATILE (2 files - excluded):
    main.py                                 In changed files manifest
    test_api.py                             Modified within last 15 minutes
═══════════════════════════════════════════════════════════════════════════

—status

═══════════════════════════════════════════════════════════════════════════
  QONTRABENDER STATUS: my-project (v0.8.0)
═══════════════════════════════════════════════════════════════════════════
  Policy Version     : 1
  Active Mode        : local_smart
  Mode Description   : Best default. Variable fidelity locally...
  Remote Cache       : DISABLED
  Version            : 5
  Available Modes    : local_fast, local_smart, cyber_bedrock, ...

  FIDELITY STATS:
    🥩 Full files      : 8
    🦴 Skeleton files  : 3
    ⚡ Volatile files  : 2
    📊 Total tokens   : 45,000

  ACTIVE CACHE:
    ID      : caches/abc123
    Version : v5
    Tokens  : 45,000
    Mode    : local_smart
    Expires : 2025-01-15T16:32:00
═══════════════════════════════════════════════════════════════════════════

Schema Validation

Qontrabender validates your policy file on load:

python worqer/qontrabender.py --validate

Validation Checks

Required fields present (version, defaults, modes)
Correct types (int, str, bool, dict, list)
Valid fidelity values (full, skeleton, diff, omit)
Valid truncation strategies (head, tail, middle)
Valid render formats (xml, markdown)
At least one mode defined

Error Example

  Validating: ./caching_policy.yaml

  Warnings:
    ⚠️  Mode 'custom_mode' is missing 'description'

  ❌ Policy file has errors:
    - 'version' must be an integer, got str
    - Mode 'broken'.fidelity.rules[2].use must be one of: ['full', 'skeleton', ...]

Integration with ConstruQtor

Read active cache ID for API calls:

from qontrabender import Qontrabender
from pathlib import Path

qb = Qontrabender(Path.cwd())
cache_id = qb.get_active_cache_id()

if cache_id:
    # Use in Gemini API call
    config['cachedContent'] = cache_id

Or via file:

CACHE_ID=$(cat qache.d/.active_cache_id)

File Locations

worqspace/
├── caching_policy.yaml    # Policy configuration
├── config.yaml            # Mode selection
├── qodeyard/              # MEAT - full code
├── bloq.d/                # BONES - skeletons
├── qontext.d/             # SOUL - semantic intelligence
└── qache.d/               # The Ledger (at qage root)
    ├── manifest.json
    ├── ledger.db
    ├── .active_cache_id
    ├── sync.log
    ├── decisions.log      # (debug_repro mode)
    └── payloads/
        └── payload_v*.txt

Why Variable Fidelity Matters

Scenario	Skeleton Only	Variable Fidelity
Refactor using internal logic	❌ Hallucinations	✅ Full implementation visible
Large vendor libs	❌ Token budget blown	✅ Skeleton saves tokens
Active edits	❌ Stale cache	✅ Volatile detection excludes
Core utilities	❌ Missing context	✅ High score = full fidelity

“Don’t serve the AI a dinner of only bones” 🥩🦴

QonQrete Release Notes

[v1.0.4-stable] - 2026-02-24

🛡️ QONTRACT Lockdown: Predictability by Design

This release is about repeatable runs: tightened, predictable, anti-drift enforced.

Feature	Description
QontractGuard	Enforces QONTRACT invariants + rule sets (contracts > vibes)
InspeQtor + QontractGuard loop	Keeps cyQles convergent, reduces drift
UserGate mode	Per-cyQle steering (edit ReQap, adjust direction, continue)
File-based audit trail	All decisions and outputs stay inspectable on disk

📁 Run Artifacts

tasq.d/ · briq.d/ · qodeyard/ · bloq.d/ · qontext.d/ · exeq.d/ · reqap.d/ · struqture/ · meta.yaml

🔐 Keep Code Out of Cloud AI

Feed agents only qontext.d/, bloq.d/, tasq*, and qontract* artifacts instead of your full repo. Audit trail stays local.

[v1.0.3-stable] - 2026-02-06

🧱 Batched Briq Generation (Blueprint → Fabrication)

High-sensitivity builds (>= 8) now use a two-phase pipeline:

Blueprint (JSON): titles/objectives list — lightweight, never truncated
Fabrication (Batched): full briq content in configurable batch sizes

instruqtor:
  batch_mode: true
  batch_size: 5

Reliably generates 50–250+ briqs for enterprise-scale task decomposition.

[v1.0.2-stable] - 2026-01-20

🔥 Inverted Briq Sensitivity Scale (0–16)

Higher number = more briqs. Range extended to 16 for enterprise mega-tasQs.

Level	Name	Briqs	Use Case
0	Monolithic	1	single-file scripts
5	Balanced	10–15	← recommended
10–16	Enterprise	50–250	mega-tasQs

🤖 Non-Interactive Save (`-n`)

./qonqrete.sh run -a -b 6 -c 3 -n myproject — auto-saves to worqspace/qonstructions/.

🌀 Gemini-Only Qontrabender

Qontrabender skipped when ConstruQtor provider isn’t Gemini.

[v1.0.1-stable] - 2026-01-02

🧯 Hotfix: HuggingFace Cache Permissions

Fixed Qontextor local_mode: complex failures in hardened Docker:

Pre-cached all-MiniLM-L6-v2 to /opt/hf_cache
Force-set HF_HOME, SENTENCE_TRANSFORMERS_HOME, TRANSFORMERS_CACHE
Graceful fallback to AST-only analysis on PermissionError

Upgrade: ./qonqrete.sh init (rebuild container).

[v1.0.0-stable] - 2025-12-30

🎉 PRODUCTION RELEASE!

After months of intensive development and 90 validation runs across the WoNQ Matrix testing framework, QonQrete v1.0.0-stable is ready for prime time!

🔥 Bulletproof Language Detection

The Problem: When using OpenAI as the AI provider, code blocks like ```py would create files named “py” instead of being skipped.

The Fix: The language_keywords set expanded from 23 entries to 400+ entries, covering:

Category	Count
Python variants	25+
JavaScript/TypeScript	40+
Infrastructure-as-Code	30+
All GitHub Linguist IDs	300+
Generic markers	20+

Provider Compatibility:

Provider	Status
OpenAI GPT-4/GPT-4o	✅ NOW BULLETPROOF
Google Gemini	✅ BULLETPROOF
Anthropic Claude	✅ BULLETPROOF
DeepSeek Coder	✅ NOW BULLETPROOF
Qwen/Qwen2.5-Coder	✅ NOW BULLETPROOF

🎯 Enforced Briq Sensitivity

The Problem: Previously, briq_sensitivity was just a “hint” to the AI, resulting in wildly inconsistent outputs.

The Fix: Briq counts are now ENFORCED with hard min/max ranges:

BRIQ_RANGES = {
    9: (1, 1, 1),      # Monolithic: exactly 1 briq
    8: (2, 3, 2),      # Very Broad: 2-3 briqs
    7: (3, 5, 4),      # Broad: 3-5 briqs (RECOMMENDED)
    6: (5, 8, 6),      # Feature-level: 5-8 briqs
    5: (8, 12, 10),    # Component-level: 8-12 briqs
    4: (10, 15, 12),   # Balanced: 10-15 briqs
    3: (15, 20, 18),   # Standard: 15-20 briqs
    2: (20, 30, 25),   # High Granularity: 20-30 briqs
    1: (30, 40, 35),   # Very High: 30-40 briqs
    0: (40, 60, 50),   # Atomic: 40-60 briqs
}

Enforcement Logic:

AI generates briqs with MANDATORY count prompt
System checks if count is within range
If too few → Retry with stronger prompt (up to 2 retries)
If too many → Merge consecutive briqs to meet max

🆕 New CLI Features

# Override cycle count directly
./qonqrete.sh run -c 6

# Combine with sensitivity
./qonqrete.sh run -b 5 -c 6

⚙️ Configuration Changes

Setting	v0.9.9-beta	v1.0.0-stable	Reason
`briq_sensitivity` default	5	7	More consistent results
`auto_cycle_limit` default	0	4	Enough iterations for polish

🧪 WoNQ Matrix Validation

90 validation runs confirming production readiness:

╔═══════════════════════════════════════════════════════════════╗
║                 WoNQ MATRIX RESULTS                           ║
╠═══════════════════════════════════════════════════════════════╣
║ Total Runs:           90 (100% coverage)                      ║
║ Clean Completions:    90 (100% success)                       ║
║ Champion Score:       658 (sensitivity=3, cycle=7)            ║
║ Global Average:       554                                     ║
║ Scores ≥600:          35.6%                                   ║
╚═══════════════════════════════════════════════════════════════╝

📊 Diff Summary

File	Lines Changed	Change Type
`worqer/construqtor.py`	+387	🔥 MAJOR - Language detection overhaul
`worqer/instruqtor.py`	+145	🔥 MAJOR - Enforced briq ranges
`qrane/qrane.py`	+4	Minor - CLI args & defaults

Total: +536 lines of production hardening

[v0.9.9-beta] - 2025-12-27

🎯 Summary

Final stabilization release before v1.0.0. Fixes critical bugs discovered during multi-cycle autonomous builds, cleans up console output, and removes broken dependencies.

🎨 Cleaner Console Output

Your terminal just got a whole lot quieter. Filtered out the noise:

What you’ll see now:

〘aQQ〙『tasQleveler』⸎ [TasqLeveler] ✅ Enhanced tasq: 180 lines
〘aQQ〙『inspeQtor』  ⸎ === InspeQtor v0.9.0 Complete: [SUCCESS] ===

What’s now hidden:

Verbose markdown headers (## 📋 Overview)
Table dividers (|-----|------|)
Individual batch progress
pycg warnings

🐛 Bug Fixes

v0.9.8 (included)

Issue	Root Cause	Fix
Skeleton overwrites code	AI copies bloq.d skeletons back to qodeyard	Detect `(body stripped by Qompressor)` markers, skip write
Exit code 1 after inspeqtor	loqal_verifier runs twice	Remove standalone from pipeline_config.yaml

v0.9.9

Issue	Root Cause	Fix
pycg warnings spam	Package broken on PyPI	Removed from requirements.txt, silent fallback
Verbose console output	TasqLeveler/InspeQtor noise	Added filters for markdown headers, table dividers

🔧 Dependency Cleanup

Removed pycg from requirements. The package is broken on PyPI (module name mismatch: installs as PyCG, but imports pycg).

Good news: You’re not losing functionality! Dependency analysis is handled by Jedi, which was doing the heavy lifting all along.

✅ Verified Features

Feature	Status
Multi-cycle autonomous builds	✅
Universal File Rule	✅
Skeleton protection	✅
Cycle continuity	✅
Clean console output	✅
All local agents working	✅

📝 Files Changed

worqer/construqtor.py - Skeleton detection before write
worqer/qontextor.py - Removed broken pycg, uses jedi only
worqer/inspeqtor.py - Internal LoQal verification (Stage 3)
worqspace/pipeline_config.yaml - Removed standalone loqal_verifier
qrane/qrane.py - Updated VISIBLE_KEYWORDS, BLOCKED_KEYWORDS, CONTENT_FILTER_PATTERNS
requirements.txt - Removed pycg

[v0.9.0-beta] - 2025-12-23

🚀 TasqLeveler Agent - Automatic Tasq Enhancement

The Big Idea: A well-structured tasq.md = dramatically better output quality. So why not let AI enhance your tasq automatically?

TasqLeveler is a new agent that runs ONCE on Cycle 1, BEFORE InstruQtor. It supercharges your tasq.md with:

Enhancement	What It Adds	Impact
📦 Dependency Graph	Explicit “what can import what” structure	Prevents circular imports
🎯 Golden Path Tests	Code that MUST work after each module	Defines success explicitly
🧪 Mock Infrastructure	Mock servers for testing integrations	Test without real services
📋 Success Criteria	Global “what does SUCCESS mean”	Clear pass/fail criteria
⏱️ Phase Priority	What to focus on if running low	Better token allocation
🔗 Base Classes	Abstract bases for similar modules	Consistent interfaces

Example Enhancement:

# BEFORE (basic tasq)
## Phase 6: C2 Integrations
### 6.1 Sliver Client
Create src/c2/sliver_client.py with connection handling.

# AFTER (TasqLeveler enhanced)
## Phase 6: C2 Integrations
### 6.1 Sliver Client
Create src/c2/sliver_client.py with connection handling.

**MUST inherit from BaseC2Client!**

🎯 Golden Path Test:
from src.c2.sliver_client import SliverClient
from src.c2.base_client import BaseC2Client

assert issubclass(SliverClient, BaseC2Client)
client = SliverClient(config={'config_path': 'test.cfg'})
assert hasattr(client, 'connect')
assert hasattr(client, 'get_sessions')

How It Works:

TasqLeveler reads your original tasq.md
Analyzes project structure and requirements
Calls AI to enhance with golden paths, mocks, etc.
Backs up original as tasq_original.md
Writes enhanced version back
InstruQtor then uses the enhanced tasq

Configuration:

# config.yaml
agents:
  tasqleveler:
    provider: openai
    model: gpt-4.1-mini  # Or use instruqtor's config

Pipeline Integration:

# pipeline_config.yaml
agents:
  - name: tasqleveler
    script: tasqleveler.py
    input: "tasq.d/cyqle{N}_tasq.md"
    output: "tasq.d/cyqle{N}_tasq.md"
    cycle_1_only: true  # Only runs on Cycle 1

Impact on Output Quality:

Metric	Without TasqLeveler	With TasqLeveler
Imports resolve	85%	95%
Classes instantiate	80%	95%
Tests pass	60%	80%
Fully functional	65%	75-80%

🔧 Universal File Rule (s00permode)

The Problem: Previous “refinement mode” approach was too restrictive - it artificially limited what cycles 2+ could do, potentially blocking legitimate new file creation.

The Solution: Removed all mode-based logic. Replaced with ONE simple universal rule that applies to ALL cycles:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 UNIVERSAL FILE RULE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 File EXISTS in qodeyard?
   → MODIFY it (fix bugs, improve implementation)
   → EXTEND it (add new functions, classes, features)
   → NEVER recreate it from scratch

📄 File DOESN'T EXIST yet?
   → CREATE it (new modules are welcome!)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Why This is Better:

✅ No artificial “modes” that restrict creativity
✅ Full freedom to create new files on ANY cycle
✅ Prevents rebuild-from-scratch bug (the actual problem)
✅ Simple rule that’s easy for AI to follow
✅ Works naturally for complex multi-cycle builds

What Changed:

Removed is_refinement_cycle logic entirely
Removed mode-based directive switching
Added Universal File Rule to ALL InstruQtor prompts
Added qodeyard file count display for context

Examples of Valid Briqs (any cycle):

✅ "Implement HavocClient RPC methods in src/c2/havoc_client.py" (MODIFY)
✅ "Add geofencing module at src/safety/geofencing.py" (CREATE new)
✅ "Fix syntax error in src/traffic/dga.py" (MODIFY)
✅ "Add unit tests for orchestration" (CREATE new test files)

Examples of Invalid Briqs (any cycle, if file exists):

❌ "Setup project root and create main.py" (main.py EXISTS)
❌ "Create the configuration system" (config.yaml EXISTS)
❌ "Initialize the C2 client base class" (base_client.py EXISTS)

🐛 Original Fix: Prevent Rebuild-from-Scratch Bug

The Bug: When a cycle was marked [FAILURE] or [PARTIAL], InstruQtor would interpret this as “start from scratch” instead of “iterate on existing code”. This caused cycle 3+ to recreate the entire project scaffolding.

Evidence from production build:

CyQle 1: briq000_setup_project_root_and_gitignore  ← Initial build ✅
CyQle 2: briq000_implement_havoc_client_rpc_logic  ← Refinement ✅
CyQle 3: briq000_setup_project_directory_and_core  ← REBUILDING! ❌

Impact: Multi-cycle builds now properly iterate while maintaining full creative freedom.

🧪 Battle-Tested: 7-Cycle Autonomous Build

v0.9.0-beta was validated with a 7-cycle autonomous build:

Metric	Result
Total Cycles	7
Total Briqs	137 (37→25→21→17→11→13→13)
Python Files	80
Total LOC	~15,000
LoQal Pass Rate	160/160 (100%)
Est. Total Cost	~$1.50

[v0.8.8-beta] - 2025-12-23

✅ Confirmed: Batched Reviews Working Perfectly!

Deep analysis of v0.8.7 production run (28 briqs, 7 cyQles) confirmed:

Zero [UNKNOWN] assessments - batch parsing working correctly
All [FAILURE] results are real AI assessments, not parse failures
Retry mechanism working - briq027 failed once (Gemini API error), succeeded on attempt 2
Cost efficiency achieved - 28 briqs reviewed in 3 batches for ~$0.01 total

🔧 LoQal Verifier Display Fix

Problem: “Running local validation…” was showing under construQtor in the event log, but it’s conceptually part of inspeQtor’s LoQal Verification stage.

Fix: Changed display to use [LoQal] prefix for clearer attribution:

# Before (v0.8.7):
〘aQQ〙『construQtor』⸎ - Running local validation...

# After (v0.8.8):
〘aQQ〙『construQtor』⸎      [LoQal] Running validation...
〘aQQ〙『construQtor』⸎      [LoQal] ✅ Passed

Also shows clear status indicators:

[LoQal] ✅ Passed - validation succeeded
[LoQal] ⚠️ Import warnings: N - warnings found
[LoQal] ❌ Syntax errors found: - errors found

🎯 Default Config Updates

Updated config.yaml with production-ready defaults:

agents:
  instruqtor:
    provider: gemini
    model: gemini-2.5-flash-lite    # $0.10/$0.40 - planning
  
  construqtor:
    provider: gemini
    model: gemini-2.5-pro           # $1.25/$10.00 - code generation (UPGRADED)
  
  inspeqtor:
    provider: gemini
    model: gemini-2.5-flash-lite    # $0.10/$0.40 - batched reviews

options:
  briq_sensitivity: 3
  auto_cycle_limit: 7
  mode: program
  cheqpoint: false

📊 Understanding Batch Results

The batch results show real AI assessments, not system errors:

Batch 1/3: 12 briqs → ✅0 ⚠️1 ❌11   # AI found 11 incomplete briqs
Batch 2/3: 12 briqs → ✅0 ⚠️0 ❌12   # AI found 12 incomplete briqs
Batch 3/3: 4 briqs  → ✅3 ⚠️1 ❌0    # 3 complete, 1 partial

This is expected behavior for cycle 1 of a multi-cycle build - the AI is correctly identifying that most code is incomplete. Subsequent cycles will fill in the gaps.

🔧 Changes

construqtor.py: Changed “Running local validation…” to “[LoQal] Running validation…” with status indicators
qrane.py: Added [LoQal] to VISIBLE_KEYWORDS for display filter
config.yaml: Updated construQtor to gemini-2.5-pro, added production defaults
All agents now use Gemini provider for consistency

💰 Expected Costs (7 cyQles × ~20 briqs each)

Agent	Model	Est. Cost
InstruQtor	flash-lite	~$0.10
ConstruQtor	pro	~$3.50
InspeQtor	flash-lite (batched)	~$0.15
TOTAL		~$4.00

Compare to v0.8.5 unbatched with GPT-4.1: $100+ 💸

[v0.8.7-beta] - 2025-12-23

🐛 Bug Fix: Display Filter Was Completely Broken

Problem: ConstruQtor and InspeQtor status messages weren’t showing in the event log at all:

# What v0.8.6 showed (missing everything!):
〘aQQ〙『construQtor』⸎ Per-briq exeQ summaries written to: exeq.d/cyqle1/

# What was missing:
--- ConstruQtor v0.8.7: Processing 1 Briqs (Interleaved) ---
-- Processing Briq: cyqle1_tasq1_briq000_setup_project.md --
     - Wrote [Code] main.py
-- Briq Complete: ... [✅ SUCCESS] (attempts: 1) --

Root Cause: The is_content_line() function was being called BEFORE checking VISIBLE_KEYWORDS, and it was matching patterns in legitimate status lines.

Fix: Complete rewrite of display filter logic:

Check VISIBLE_KEYWORDS FIRST - if found, display immediately (unless blocked)
Only apply content filtering to lines WITHOUT visible keywords
Removed is_content_line() from the visible keyword path entirely
Added more explicit patterns to match all status message formats

✨ Expected Output Now

〘aQQ〙『construQtor』⸎ --- ConstruQtor v0.8.7: Processing 5 Briqs (Interleaved) ---
〘aQQ〙『construQtor』⸎ -- Processing Briq: cyqle1_tasq1_briq000_setup.md --
〘aQQ〙『construQtor』⸎ - Wrote [Code] main.py
〘aQQ〙『construQtor』⸎ - Wrote [Code] config.yaml
〘aQQ〙『construQtor』⸎ -- Briq Complete: ... [✅ SUCCESS] (attempts: 1) --
〘aQQ〙『construQtor』⸎ -- Processing Briq: cyqle1_tasq1_briq001_logging.md --
...
〘aQQ〙『inspeQtor』  ⸎ --- InspeQtor: Reviewing 5 briqs in 1 batches ---
〘aQQ〙『inspeQtor』  ⸎ -- Batch 1/1: 5 briqs --
〘aQQ〙『inspeQtor』  ⸎    Estimated batch cost: $0.00024
〘aQQ〙『inspeQtor』  ⸎    Batch results: ✅5 ⚠️0 ❌0
〘aQQ〙『inspeQtor』  ⸎ --- Reviews complete: 5 briqs, estimated $0.00024 total ---
〘aQQ〙『inspeQtor』  ⸎ === Final Assessment: [SUCCESS] ===

🔧 Changes

qrane/qrane.py: Rewrote should_display() with simpler priority logic
Removed is_content_line() from display path for visible keyword lines
Added explicit VISIBLE_KEYWORDS patterns for ALL status message formats:
- "--- ConstruQtor", "-- Processing Briq:", "- Wrote [Code]", "-- Briq Complete:"
- "--- InspeQtor:", "-- Batch ", "Batch results:", "--- Reviews complete:"
- "[SUCCESS]", "[FAILURE]", "[PARTIAL]", "attempts:"
Reduced BLOCKED_KEYWORDS to only AI review content noise

[v0.8.6-beta] - 2025-12-23

🚀 Major: Batched Reviews (90% Fewer API Calls!)

The Problem: v0.8.5 with per-briq reviews made 77+ API calls per cycle, burning $16+ with GPT-4.1.

The Solution: Batched reviews group multiple briqs into single API calls.

Briqs	Old API Calls	New API Calls	Savings
20	20	~3	85%
50	50	~6	88%
77	77	~8	90%

💰 New Default: Gemini 2.5 Flash-Lite

All agents now default to gemini-2.5-flash-lite ($0.10/$0.40 per 1M tokens):

Agent	Old Model	New Model	Cost Reduction
InstruQtor	gpt-4.1-mini	gemini-2.5-flash-lite	75%
InspeQtor	gpt-4.1	gemini-2.5-flash-lite	95%
ConstruQtor	gemini-2.5-pro	gemini-2.5-flash	unchanged

Why Flash-Lite?

Same price as GPT-4.1-nano ($0.10/$0.40)
Newer model (2.5 series) with better quality
1M token context window (perfect for batched reviews!)
More than smart enough for planning and reviewing

✨ New Configuration Options

agents:
  inspeqtor:
    # BATCHED REVIEW MODE (v0.8.6+)
    batch_mode: true           # Enable batched reviews (default: true)
    batch_token_roof: 60000    # Max input tokens per batch
    batch_max_briqs: 12        # Max briqs per batch

📊 Cost Comparison (77 briqs)

Configuration	Est. Cost/Cycle
v0.8.5 + gpt-4.1	$16.00
v0.8.5 + gpt-4.1-mini	$3.20
v0.8.6 + batched + flash-lite	$0.15

That’s a 99% cost reduction from the default v0.8.5 config!

🔧 Changes

inspeqtor.py: Added batched review system with group_briqs_into_batches(), build_batched_review_prompt(), parse_batched_response()
lib_funqtions.py: Updated pricing table with correct Gemini rates
config.yaml: New defaults for all agents, added batch_mode, batch_token_roof, batch_max_briqs
Display filter: Continues to suppress per-briq noise (from v0.8.5)

📋 Expected Output

inspeQtor  ⸎ --- InspeQtor: Reviewing 77 briqs in 8 batches (cyQle 1) ---
inspeQtor  ⸎ -- Batch 1/8: 12 briqs --
inspeQtor  ⸎    Estimated batch cost: $0.00234
inspeQtor  ⸎    Batch results: ✅10 ⚠️2 ❌0
inspeQtor  ⸎ -- Batch 2/8: 12 briqs --
...
inspeQtor  ⸎ --- Reviews complete: 77 briqs, estimated $0.15 total ---

⚙️ Disabling Batch Mode

If you prefer per-briq reviews (legacy mode):

agents:
  inspeqtor:
    batch_mode: false

[v0.8.5-beta] - 2025-12-23

🚨 TOKEN BURN FIX - CRITICAL

Problem Identified: Running InspeQtor with gpt-4.1 (not mini) on 77 briqs × 2 stages = ~154 AI calls burned ~$25 in a single run.

Root Cause: InspeQtor was configured with gpt-4.1 ($2.00/$8.00 per 1M tokens) instead of gpt-4.1-mini ($0.40/$1.60 per 1M tokens).

Recommendation: For development/testing, use:

agents:
  inspeqtor:
    provider: openai
    model: gpt-4.1-mini  # or gpt-4.1-nano for even cheaper

✨ New Features

1. Cost Estimation Display

InstruQtor and InspeQtor now show estimated costs before AI calls:

instruQtor ⸎ Estimated cost: $0.00234 (1,234 in + ~2,000 out tokens @ gpt-4.1-mini)
inspeQtor  ⸎ --- Per-briq reviews complete: 77 briqs, estimated $3.45 total ---
inspeQtor  ⸎ Estimated cost: $0.00456 (meta-review @ gpt-4.1)

2. Cleaner Display Filter System

Completely overhauled the display filter to suppress noise:

Blocked: Per-briq Assessment: SUCCESS/PARTIAL/FAILURE lines (only Final shown)
Blocked: ## Summary, ## Issues Found, markdown headers
Blocked: Code snippets (except FileNotFoundError:, with pytest, etc.)
Blocked: Table rows from AI reviews
Kept: High-level status (Briq Complete, Processing Briq:, Wrote exeQ)
Kept: === Final Assessment: and === InspeQtor v0.8.5 Complete:

3. LoQal Verifier Renamed to InspeQtor

Display name loQal_verifier now shows as inspeQtor since it’s part of the InspeQtor pipeline.

🔧 Changes

Added lib_funqtions.py pricing for GPT-4.1 series and Claude models
Display filter now has BLOCKED_KEYWORDS list for aggressive noise suppression
total_review_cost tracking across all per-briq reviews
Cost estimation added to InstruQtor briq planning
Cost estimation added to InspeQtor per-briq and meta reviews

📋 Clean Display Example

With v0.8.5, your event log should look like:

construQtor ⸎ -- Processing Briq: cyqle1_tasq1_briq000_setup_project.md --
construQtor ⸎ - Wrote [Code] main.py
construQtor ⸎ - Running local validation...
construQtor ⸎ - Wrote exeQ: cyqle1_tasq1_briq000_setup_project_exeq.md
construQtor ⸎ -- Briq Complete: ... [✅ SUCCESS] (attempts: 1) --
...
inspeQtor  ⸎ --- Per-briq reviews complete: 20 briqs, estimated $0.89 total ---
inspeQtor  ⸎ === Final Assessment: [SUCCESS] ===
inspeQtor  ⸎ === InspeQtor v0.8.5 Complete: [SUCCESS] ===

No more ## Summary, ## Issues Found, per-briq Assessment: spam!

[v0.8.4-beta] - 2025-12-23

🐛 Bug Fixes

1. Fixed Empty/Invalid `init.py` Files Being Written

Problem: AI sometimes outputs empty code blocks resulting in files containing just ``` (markdown fence) instead of valid Python.

Fix: Improved code block regex parser to:

Prevent matching across code blocks (using [^]` pattern)
Skip files with empty content
Skip files where content starts with ```
Skip files with content shorter than 3 characters
Added [SKIP] log messages for transparency

2. Improved Import Resolution in LoQal Verifier

Problem: Import checker was flagging src.utils.logger as missing even when src/utils/logger.py existed.

Fix: Enhanced import resolution to:

Search recursively for the final module name
Check paths with and without the first component
Only flag imports that start with known local prefixes
Added more third-party packages to skip list

3. Fixed Skeleton Signature False Positives (from v0.8.3)

Note: v0.8.3 already included the fix for argparse, logging, sys, Path false positives.

🔧 Changes

ConstruQtor version header updated to v0.8.4
LoQal Verifier version header updated to v0.8.4
Improved logging for skipped files during code block parsing

📋 What to Expect

With v0.8.4, you should see:

     [SKIP] Empty file: src/__init__.py
     [SKIP] Invalid content (markdown fence): src/evasion/__init__.py
     - Wrote [Code] src/utils/logger.py
     - Wrote [Code] src/agent/factory.py

[v0.8.3-beta] - 2025-12-23

✨ New Features & Enhancements

1. Interleaved Pipeline (Build → Validate → Build → Validate)

ConstruQtor now processes each briq with interleaved validation:

FOR EACH briq:
  1. BUILD     - AI generates code
  2. VALIDATE  - Local syntax/import check (NO AI)
  3. REVIEW    - Optional AI quick review
  4. RETRY     - If failed, retry up to 3x
  5. EXEQ      - Write per-briq exeQ summary

2. Per-Briq ExeQ Summaries

ConstruQtor now writes execution summaries to exeq.d/cyqle{N}/:

briq000_exeq.md - Status, files written, validation results
briq001_exeq.md - etc.

Note: ConstruQtor writes exeQ summaries (execution results). InspeQtor writes reQap summaries (review/recap).

3. Smarter LoQal Verifier Skeleton Matching

Fixed false positive warnings for standard library imports and typing constructs:

Filters out: argparse, sys, os, re, json, etc.
Filters out: List, Dict, Any, Optional, Union, etc.
Filters out: Uppercase names (likely classes, not functions)
Filters out: Single-letter names (likely type vars)

4. Improved Qrane Display Keywords

Added new keywords to visible output filter:

exeQ - Per-briq execution summaries
Running local validation - Validation status
Briq Complete - Per-briq completion
SUCCESS, FAILURE, PARTIAL - Status indicators

🔧 Configuration

# Interleaved Pipeline (NEW in v0.8.3)
interleaved:
  enabled: true              # Enable build→review per briq
  local_validation: true     # Syntax/import checks (no AI)
  ai_quick_review: false     # Set true for AI review per briq
  retry_on_review_fail: true # Retry if AI review fails

🐛 Bug Fixes

Fixed NameError: name 'e' is not defined in inspeqtor.py line 785
Fixed LoQal Verifier false positives for stdlib/typing symbols
Fixed terminology: ConstruQtor → exeQ, InspeQtor → reQap

[v0.8.2-beta] - 2025-12-23

✨ LoQal Verifier Integration

Integrated a deterministic local verification agent that runs after ConstruQtor:

What It Checks (NO AI Required)

Syntax Validation: python -m py_compile on all .py files
Import Resolution: Verifies local imports resolve to actual files
Skeleton Signature Matching: Ensures functions exist that are called elsewhere

Self-Healing Feedback Loop

Verification errors are appended to the reqap.md, which is read by InstruQtor in the next cycle:

┌─────────────────────────────────────────────────────────────────────────────────┐
│ CyQle N:  ConstruQtor → LoQal Verifier → InspeQtor → ReQap                     │
│                              ↓                           ↓                      │
│                        [Errors Found]              [Errors Logged]              │
│                              ↓                           ↓                      │
│ CyQle N+1: InstruQtor reads errors → Creates fix briqs → ConstruQtor fixes     │
└─────────────────────────────────────────────────────────────────────────────────┘

🔧 Configuration

# config.yaml
agents:
  loqal_verifier:
    max_attempts: 3          # Retry failed briqs up to 3 times
    stop_on_briq_fail: false # Continue to next briq on failure

📋 Output Format

[LoQal] ═══════════════════════════════════════════════════
[LoQal] Validation Report for: src/utils/logger.py
[LoQal] ───────────────────────────────────────────────────
[LoQal] ✅ Syntax: VALID
[LoQal] ✅ Imports: All resolved
[LoQal] ⚠️ Skeleton: 2 potentially missing signatures
[LoQal] ═══════════════════════════════════════════════════

[v0.8.1-beta] - 2025-12-23

✨ ConstruQtor Per-Briq Retry

Added configurable retry mechanism for individual briq failures:

# config.yaml
agents:
  construqtor:
    max_attempts: 3           # Retry failed briqs up to 3 times
    stop_on_briq_fail: true   # Stop cycle if briq fails after all retries

🔧 Changes

ConstruQtor now tracks attempts per briq
Failed briqs are retried with error context appended to prompt
Status output shows attempt count: [✅ SUCCESS] (attempts: 2)
Configurable stop_on_briq_fail - set false to continue despite failures

📋 Output Example

construQtor ⸎ -- Processing Briq: briq005_implement_dga.md --
construQtor ⸎    Attempt 1/3...
construQtor ⸎    [FAIL] Syntax error in output
construQtor ⸎    Attempt 2/3 (with error context)...
construQtor ⸎    [✅ SUCCESS] (attempts: 2)

[v0.8.0-beta] - 2025-12-22

🌀 Qontrabender - The Cache Bender

A new agent that manages hybrid caching with intelligent content classification:

Variable Fidelity: Mixes MEAT (full code) + BONES (skeletons) based on file importance
Policy-Driven Configuration: All behavior controlled via caching_policy.yaml
Multiple Operational Modes: 6 pre-configured modes for different use cases
Schema Validation: YAML validation prevents bad configuration from breaking the flow
Improved Volatile Detection: Cycle-based, diff-based, git diff, and mtime fallback

📦 Available Modes

Mode	Description	Remote Cache
`local_fast`	Ultra-fast, skeleton only, minimal I/O	❌
`local_smart`	Default - variable fidelity, best balance	❌
`cyber_bedrock`	Remote cache for stable bedrock	✅
`cyber_aggressive`	Aggressive caching, more churn	✅
`paranoid_mincloud`	Minimal cloud exposure, skeletons only	✅
`debug_repro`	Maximum audit logging	❌

🔧 Configuration

# config.yaml
agents:
  qontrabender:
    provider: local
    model: qontrabender
    policy_file: "./caching_policy.yaml"
    mode: local_smart

📋 Fidelity Rules Engine

Configurable rules determine how each file is treated:

fidelity:
  rules:
    - name: "stable_core_full"
      when:
        tier: "stable"
        core_score_gte: 0.65
        file_chars_lte: 200000
      use: "full"
    - name: "massive_skeleton"
      when:
        file_chars_gte: 220000
      use: "skeleton"

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                    THE DATA LAKE (Local)                                │
│                                                                         │
│   qodeyard/ (MEAT)           bloq.d/ (BONES)        qontext.d/ (SOUL)   │
│   ├── api.py (FULL)          ├── api.py (SKEL)      ├── api.q.yaml      │
│   └── lib.py (FULL)          └── lib.py (SKEL)      └── lib.q.yaml      │
│                                                                         │
│             │                        │                      │           │
│             └───────────┬────────────┴──────────────────────┘           │
│                         ▼                                               │
│              ┌───────────────────────┐                                  │
│              │    QONTRABENDER       │                                  │
│              │   "The Compositor"    │                                  │
│              ├───────────────────────┤                                  │
│              │ POLICY ENGINE:        │                                  │
│              │ 1. Read 'Soul'        │ ← qontext.d intelligence         │
│              │ 2. Filter 'Volatile'  │ ← multi-signal detection         │
│              │ 3. Evaluate Rules     │ ← fidelity rules engine          │
│              │ 4. Assemble & Hash    │                                  │
│              └──────────┬────────────┘                                  │
│                         ▼                                               │
│                   qache.d/ (The Ledger)                                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

📊 Triple-Core Memory System

QonQrete now features a Triple-Core Memory System:

Agent	Role	Output
Qompressor	Skeletonizer	`bloq.d/` - AST-stripped code structures
Qontextor	Symbol Mapper	`qontext.d/` - Semantic YAML maps
Qontrabender	Cache Bender	`qache.d/` - Policy-driven cache payloads

See QONTRABENDER.md for full documentation.

[v0.7.0-beta] - 2025-12-21

🚀 Fully Local Qontextor Agent

This release introduces a major upgrade to the qontextor agent, enabling a fully local, deterministic, and highly detailed analysis of the codebase. This new “Local Qontextor Stack” significantly reduces reliance on AI for context generation, leading to massive cost savings, increased speed, and enhanced privacy.

✨ The Local Qontextor Stack

The new local mode is powered by a multi-layered analysis stack:

Python AST: For extracting the fundamental structure of the code (classes, functions, signatures).
Docstrings & Verb Heuristics: To understand the purpose of code, either from existing documentation or by inferring it from function names.
Jedi: For static analysis, providing type inference and cross-file relationship understanding.
PyCG: To generate a comprehensive call graph, mapping out dependencies and execution flow.

🔧 Fast vs. Complex Local Modes

The local qontextor can be fine-tuned for speed or detail:

local_mode: 'fast': Provides a very fast analysis using AST, Jedi, and heuristics.
local_mode: 'complex': Enhances the analysis by using a local sentence-transformers model to create deep semantic embeddings of the code’s purpose.

📋 CLI Helpers

python3 worqer/qontextor.py --query "<search_term>"   # Semantic search
python3 worqer/qontextor.py --verb "<verb_pattern>"   # Find by verb pattern
python3 worqer/qontextor.py --ripple "<symbol_name>"  # Ripple effect analysis

🐛 Bug Fixes

Fixed a NameError in the inspeqtor agent that was causing it to crash during the review phase.
Fixed a NameError in the qontextor agent related to the extract_first_sentence function.
Added a docker system prune command to qonqrete.sh to prevent “No space left on device” errors.

💰 Performance & Cost

Indexing Cost: Reduced to zero when using the local qontextor.
Cost per Run: Up to 25x cheaper due to the massive reduction in tokens sent to AI providers.
Speed: Approximately 3x faster on average due to smaller prompts and local processing.

[v0.6.3-beta] - 2025-12-19

Added

Dynamic Local Agent Loader: Implemented a dynamic local agent loader in qrane/qrane.py, allowing agents configured with provider: local to dynamically load and execute Python scripts from the worqer directory.

Changed

qrane.py: Modified run_orchestration to dynamically determine agent script paths for local providers.
Dockerfile: Added npm install -g @qwen-code/qwen-code@latest to install the Qwen CLI tool.
lib_ai.py: Modified _run_qwen to pass prompts via standard input instead of command-line arguments.

Fixed

QWEN_API_KEY Environment Variable: Ensured qonqrete.sh passes QWEN_API_KEY to the container.
construQtor Briq Processing: Improved handling of briqs.

[v0.6.2-beta] - 2025-12-18

Added

“local” Provider: Implemented a “local” provider for offline agents like calqulator and qompressor.
Qwen Model Testing: Tested qwen-turbo, qwen-coder, and qwen-max models.

Changed

Default Briq Format: The instruqtor now defaults to a more reliable markdown-based format for briqs.

Fixed

AI Reliability: The new markdown format significantly improves reliability with various AI models.

[v0.6.1-beta] - 2025-12-16

Added

Qwen Provider Integration: Integrated the Qwen AI provider into the system.
New Documentation: Added extensive documentation:
- CONTEXT.md: Explains the context mechanism.
- MEMORY.md: Details the local memory mechanism.
- MINDSTACK.md: Suggestions for the AI agent brain stack.
- MINDSTACK_ARCH.md: Architecture of the brain stack.
- QWEN_90K_FIX.md: Verification of Qwen’s performance with large context.
- SKELETON.md: Explains code skeletonization.

Changed

Default Task: Updated worqspace/tasq.md to a more complex task.
Version: Bumped version to 0.6.1.

[v0.6.0-beta] - 2025-12-13

Added

Major Improvements: The Dual-Core Memory System: This release introduces the Qompressor and Qontextor agents, forming a “Dual-Core” memory system that dramatically reduces cost and increases speed.

The Scenario: A medium-sized project (50 files, ~10,000 lines of code).

Raw Size: ~100,000 Tokens.

Metric	Old Approach (Send Full Code)	New Approach (Dual-Core)	Improvement
Context Sent	100,000 Tokens (Full Repo)	~4,000 Tokens (Skeletons)	~96% Reduction
Indexing Cost	N/A (Read raw)	Low (Uses compressed code to index)	Optimized
Cost per Run	~$0.25 (GPT-4o)	~$0.01 (GPT-4o)	25x Cheaper
Speed	Slow (Huge prompt processing)	Fast (Tiny prompt)	~3x Faster
Memory	Persistent	Persistent & Infinite Context	Upgraded

Summary: You are paying 4% of the cost for 100% of the intelligence.

Qompressor (The Skeletonizer): Creates a low-token “skeleton” of the codebase in bloq.d.
Qontextor (The Symbol Mapper): Generates detailed YAML maps of the codebase’s symbols in qontext.d.
CalQulator (The Cost Estimator): Analyzes briQ files to provide token and cost estimates.
FunQtions Library: Added qrane/lib_funqtions.py for common utility functions.

Changed

Version Suffix: Appended -beta to signify pre-release status.
Agent Architecture: Updated pipeline_config.yaml to include new agents.
Configuration: Updated worqspace/config.yaml with sane defaults.

[v0.5.0-beta] - 2025-12-08

Added

Pipeline Optimization: Introduced a streamlined pipeline for multi-agent orchestration.
Multi-Provider Support: Added support for OpenAI, Anthropic, Google Gemini, and DeepSeek.

Changed

Agent Communication: Improved inter-agent communication via YAML-based file passing.
Default Configuration: Updated default models for improved performance.

Fixed

Memory Leaks: Fixed memory issues in long-running sessions.
Container Isolation: Improved Docker container isolation.

[v0.4.6-beta] - 2025-12-05

Changed

Logging Architecture: Re-architected logging system. Raw output captured in struqture/qonsole_<agent>.log, high-level status in struqture/events_<agent>.log.

Fixed

Headless Mode Crash: Fixed “I/O operation on closed file” error in non-TUI mode.
Gatekeeper Assessment Parsing: More robust regex parsing for “Assessment:” status.
construqtor Path Duplication: No longer creates nested qodeyard/qodeyard directories.
construqtor AI Output Parsing: Stricter system prompt with clear output format example.

[v0.4.5-alpha] - 2025-12-03

Added

Sqrapyard Project Seeding: qonqrete.sh now copies from worqspace/sqrapyard to qodeyard on startup.
tasq.md Seeding: If tasq.md exists in sqrapyard, it’s used as the initial task.
Verbose Startup Logging: Explicit logs about seeding status.
Pre-run Delay: 3-second delay after initial host logs.

Changed

Ephemeral Workspaces: Creates unique qage_<timestamp> directory for each run.
Agent Output Directory: construqtor writes exclusively to qodeyard.
Instruqtor Sensitivity: Re-implemented 10 distinct levels (0-9).
Context Awareness: Both agents read all files from qodeyard.

Fixed

Stricter Path Sanitization: Forcibly removes ../ from AI-generated filenames.
Gatekeeper Assessment Parsing: Correctly parses “Assessment” status.
AI Filename Resilience: Handles AI providing language name as filename.
Build Log Verbosity: Empty lines filtered from docker build output.

[v0.4.4-alpha] - 2025-12-02

Changed

InstruQtor Sensitivity: Implemented 10 distinct levels (0-9).
Context Awareness: InstruQtor reads all files from qodeyard.
Sqrapyard Logging: Improved logging for seeding process.

Fixed

Instruqtor Logic: Overhauled sensitivity logic.
Construqtor: Fixed bug causing agent to fail.
AI Reliability: Implemented robust retry mechanism in lib_ai.
Container Workspace: Isolated agent workspaces, fixed NameError.

[v0.4.3-alpha] - 2025-12-02

Added

Init Seeding: qonqrete.sh init copies from sqrapyard to qodeyard if available.

[v0.4.2-alpha] - 2025-11-28

Added

Architect Role: Implemented “Architect” role in instruqtor.
Micro-dosing: Introduced “micro-dosing” technique for better AI results.

Fixed

Syntax Errors: Addressed multiple syntax errors and regressions.

[v0.4.1-alpha] - 2025-11-27

Fixed

Critical Regressions: Patched syntax errors from v0.4.0.
Pre-flight Checks: Disabled interfering pre-flight checks.

[v0.4.0-alpha] - 2025-11-26

Added

Operational Modes: Agents operate with specific “personas” via --mode flag.
Briq Sensitivity: instruQtor accepts --briq-sensitivity flag (0-9).
TUI Overhaul: Major TUI improvements.

Fixed

Path Regression: Resolved critical bug in dynamic pipeline logic.

Changed

Code Refinements: Significant refactoring for readability.

[v0.3.0-alpha] - 2025-11-25

Changed

Branding: Updated README.md to display logo.png.
Versioning: Hardened build process for clean VERSION file.

[v0.2.7-alpha] - 2025-11-24

Fixed

Hotfix: Addressed critical IndentationError in qrane/qrane.py.

[v0.2.6-alpha] - 2025-11-23

Fixed

TUI Experience: Fixed “flash and gone” issue.

[v0.2.5-alpha] - 2025-11-22

Fixed

Agent Stability: Fixed critical NameError and improved console error visibility.

[v0.2.4-alpha] - 2025-11-21

Changed

Documentation: Consolidated inspection reports into COMING_SOON.md and DOCUMENTATION.md.

[v0.2.3-alpha] - 2025-11-20

Fixed

TUI Stability: Fixed NameError crash in TUI mode.

[v0.2.2-alpha] - 2025-11-19

Changed

Major Refactoring:
- Implemented dynamic agent pipeline.
- Centralized path management.
- Added pre-flight checks for dependencies.
- Implemented TUI state persistence.

[v0.2.1-alpha] - 2025-11-18

Added

Dynamic Versioning: Centralized versioning in VERSION file.
Integrated Docker Output: Streamed Docker build output into TUI.

[v0.2.0-alpha] - 2025-11-17

Added

TUI Enhancements: Added raw log view, fullscreen mode, key shortcuts, improved colors.
Microsandbox (MSB) Integration: Added support for msb.

Changed

AI Models: Updated default models for faster performance.

[v0.1.1-alpha] - 2025-11-14

Added

TUI Mode: Introduced --tui flag for interactive interface.
Workspace Cleaning: Added clean command to qonqrete.sh.

[v0.1.0-alpha] - 2025-11-12

The initial public alpha release of QonQrete.

Multi-Stage Inspeqtion System (v0.8.3)

Overview

The Multi-Stage Inspeqtion system with Interleaved Pipeline provides:

Build → Review → Build → Review per briq (interleaved orchestration)
Local validation after each briq (syntax, imports) - no AI needed
Optional AI quick review per briq for quality assurance
Retry on failure with configurable attempts
Fail-fast or fail-tolerant modes

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     INSTRUQTOR (Once per cycle)                  │
├─────────────────────────────────────────────────────────────────┤
│   tasq.md ──► Break into briqs ──► briq.d/cyqle{N}_*.md         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│            CONSTRUQTOR v0.8.3 (Interleaved Pipeline)             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   FOR EACH briq:                                                 │
│   ┌───────────────────────────────────────────────────────────┐ │
│   │                                                            │ │
│   │   ┌──────────────┐                                         │ │
│   │   │  1. BUILD    │  AI generates code for this briq        │ │
│   │   │  (ConstruQtor)│  Write files to qodeyard/              │ │
│   │   └──────────────┘                                         │ │
│   │          │                                                  │ │
│   │          ▼                                                  │ │
│   │   ┌──────────────┐                                         │ │
│   │   │ 2. VALIDATE  │  Local syntax check (compile())         │ │
│   │   │ (No AI)      │  Import resolution check                │ │
│   │   └──────────────┘                                         │ │
│   │          │                                                  │ │
│   │    ┌─────┴─────┐                                           │ │
│   │    ▼           ▼                                           │ │
│   │   ✅ OK      ❌ FAIL ──► retry (up to max_attempts)        │ │
│   │    │                                                        │ │
│   │    ▼                                                        │ │
│   │   ┌──────────────┐                                         │ │
│   │   │ 3. REVIEW    │  Optional AI quick review               │ │
│   │   │ (if enabled) │  (ai_quick_review: true)                │ │
│   │   └──────────────┘                                         │ │
│   │          │                                                  │ │
│   │    ┌─────┴─────┐                                           │ │
│   │    ▼           ▼                                           │ │
│   │   ✅ PASS    ❌ FAIL ──► retry (if retry_on_review_fail)   │ │
│   │    │                                                        │ │
│   │    ▼                                                        │ │
│   │   Write reqap.d/cyqle{N}/briq{XXX}_reqap.md                │ │
│   │                                                            │ │
│   └────────────────────────────────────────────────────────────┘ │
│          │                                                       │
│          ├── stop_on_briq_fail=true  ──► HALT                   │
│          └── stop_on_briq_fail=false ──► Continue to next briq  │
│                                                                  │
│   Output: exeq.d/cyqle{N}_summary.md (with all briq results)    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│          INSPEQTOR (Final Review & Verification)                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   STAGE 1: Aggregate Per-Briq Results                           │
│   • Read all briq reqaps from construqtor                       │
│   • Detect cross-briq integration warnings                      │
│                                                                  │
│   STAGE 2: Meta-Review (AI)                                     │
│   • Synthesize patterns across briqs                            │
│   • Consolidated suggestions                                    │
│                                                                  │
│   STAGE 3: LoQal Verification (No AI)                           │
│   • Final syntax validation                                     │
│   • Import resolution                                           │
│   • Results appended to reqap                                   │
│                                                                  │
│   Output: reqap.d/cyqle{N}_reqap.md                             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  QRANE: promote_reqap()                          │
├─────────────────────────────────────────────────────────────────┤
│   reqap.d/cyqle{N}_reqap.md ──► tasq.d/cyqle{N+1}_tasq.md       │
│   Self-healing loop!                                             │
└─────────────────────────────────────────────────────────────────┘

Configuration

config.yaml

# Retry Configuration
retry:
  enabled: true
  max_attempts: 3              # Total attempts per briq
  stop_on_briq_fail: false     # Continue to other briqs on failure
  retry_delay: 2               # Seconds between retries

# Interleaved Pipeline (NEW in v0.8.3)
interleaved:
  enabled: true                # Enable build→review per briq
  local_validation: true       # Syntax/import checks (no AI)
  ai_quick_review: false       # Set true for AI review per briq
  retry_on_review_fail: true   # Retry if AI review fails

# Local Verification (final stage)
verification:
  enabled: true
  checks:
    syntax: true               # Python compile() validation
    imports: true              # Import resolution
    skeleton_match: true       # Signature comparison

agents:
  inspeqtor:
    provider: openai
    model: gpt-4.1
    max_prompt_chars_per_briq: 500000
    max_context_files_per_briq: 40
    max_chars_per_context_file: 80000
    use_filtered_context: true
    include_neighbor_depth: 1

Key Settings

Setting	Default	Description
`retry.max_attempts`	3	How many times to retry a failed briq
`retry.stop_on_briq_fail`	false	Halt cycle on failure (true) or continue (false)
`interleaved.local_validation`	true	Run syntax/import checks per briq
`interleaved.ai_quick_review`	false	Run AI review per briq (costs tokens)

How It Works

ConstruQtor processes each briq with interleaved validation:
- Build code → Validate locally → (Optional AI review) → Next briq
- Writes per-briq reqaps: reqap.d/cyqle{N}/briq{XXX}_reqap.md
InspeQtor does final review:
- Aggregates per-briq results
- Meta-review for patterns
- LoQal verification (final syntax check)
promote_reqap() carries everything to next cycle

caching_policy.yaml

The inspeqtor section controls detailed policy:

inspeqtor:
  per_briq:
    max_prompt_chars: 500000
    max_context_files: 40
    context_filter:
      enabled: true
      neighbor_depth: 1
      
  meta_review:
    max_prompt_chars: 100000
    exclude:
      - raw_code
      - full_architectural_context

Output Structure

After running InspeQtor on cyQle 2:

reqap.d/
├── cyqle2/                          # Per-briq reqaps
│   ├── cyqle2_tasq1_briq000_reqap.md
│   ├── cyqle2_tasq1_briq001_reqap.md
│   ├── cyqle2_tasq1_briq002_reqap.md
│   └── ...
└── cyqle2_reqap.md                  # Final aggregated reqap

How Context Filtering Works

Instead of passing ALL .q.yaml files, we filter based on relevance:

Identify Changed Files: Extract files modified by the briq
Find Direct Context: Include .q.yaml for each changed file
Expand Neighbors: Include .q.yaml for dependencies (imports, calls)
Apply Budget: Stop if budget exhausted

Example:

Briq modifies: src/agent/factory.py
Direct context: factory.py.q.yaml
Neighbors: base_agent.py.q.yaml, config.py.q.yaml (imported by factory)
Result: 3 context files instead of 117!

Budget Enforcement

Multiple layers of protection in lib_ai.py:

Max Files: Limit number of context files
Per-File Cap: Truncate individual large files
Total Budget: Stop adding context when budget exhausted
Hard Limit: Nuclear option - drop ALL context if > 9.5MB
Logging: Always logs final prompt size for debugging

Running a Full Cycle

No changes to your workflow! Just run as normal:

./qonqrete.sh --mode program

InspeQtor automatically:

Runs per-briq reviews
Aggregates into meta-review
Outputs single cyqle{N}_reqap.md

Troubleshooting

Still hitting limits?

Reduce budgets in config.yaml:

agents:
  inspeqtor:
    max_prompt_chars_per_briq: 300000    # Lower from 500K
    max_context_files_per_briq: 20       # Fewer files

Want more context per briq?

Increase depth:

agents:
  inspeqtor:
    include_neighbor_depth: 2            # 2-hop neighbors
    max_context_files_per_briq: 60       # More files allowed

Debug mode

Check prompt sizes in stderr:

[PROMPT] Final size: 347,291 chars | Context files: 23

Version History

v0.8.3: Interleaved Pipeline (Build → Review → Build → Review)
- ConstruQtor now validates each briq immediately after building
- Local validation (syntax, imports) runs per-briq with no AI
- Optional AI quick review per briq (ai_quick_review: true)
- Per-briq reqaps generated during construction
- InspeQtor aggregates and does final meta-review
- Fixed various bugs from v0.8.2
v0.8.2: Multi-Stage Inspeqtion with Retry + Local Verification
- Per-briq retry mechanism (configurable max_attempts)
- stop_on_briq_fail option for fail-fast or fail-tolerant modes
- LoQal Verifier for deterministic syntax/import checking
- Verification results appended to reqap (uses existing promote_reqap flow)
v0.9.0: Two-Stage Inspeqtion system (internal)
- Per-briq tactical reviews
- Meta-review aggregation
- Budget enforcement in lib_ai.py
- Context filtering by relevance

VS Code Extension Usage Guide

The QonQrete VS Code extension brings autonomous code generation directly into your editor. This guide covers all features added in v1.2.0.

Installation

From Marketplace

Open VS Code Extensions panel (Ctrl+Shift+X)
Search “QonQrete”
Click Install

From VSIX

code --install-extension qonqrete-1.2.0.vsix

First-Time Setup (Two Clicks)

1. Deploy to Workspace

Open Command Palette (Ctrl+Shift+P)
Run QonQrete: Deploy to Workspace
Runtime installs to .qonqrete/ automatically
.gitignore updated automatically

2. Set AI Configuration

Run QonQrete: Set AI Configuration
Select providers for each agent (TasqLeveler, InstruQtor, ConstruQtor, InspeQtor)
Enter API keys (stored securely in OS keychain)
Done!

Commands Reference

Command	Description	Shortcut
Deploy to Workspace	Install runtime to `.qonqrete/`	—
Set AI Configuration	Configure providers, models, API keys	—
Create tasq.md	Generate starter template	—
Run Tasq	Execute the pipeline	`Ctrl+Alt+Q`
Resume Run	Continue from cheQpoint	—
Init Workspace	Build container image	—
Clean Qages	Remove build artifacts	—

The QonQrete sidebar shows:

Status — Runtime detected, container status
Quick Actions — Deploy, Create Tasq, Run, Resume
Qage Browser — View build artifacts

AI Configuration UI

The “Set AI Configuration” command opens an interactive picker:

┌──────────────────────────────────────────┐
│  QonQrete: AI Configuration              │
├──────────────────────────────────────────┤
│  $(beaker) tasqleveler  OpenAI / gpt-4o  │
│  $(beaker) instruqtor   OpenAI / gpt-4o  │
│  $(beaker) construqtor  Anthropic/sonnet │
│  $(beaker) inspeqtor    Gemini / 2.5-pro │
├──────────────────────────────────────────┤
│  $(key) OpenAI          ✓ Set            │
│  $(key) Anthropic       ✓ Set            │
│  $(key) Google          ✗ Not set        │
│  $(key) OpenRouter      ✓ Set            │
│  $(key) DeepSeek        ✗ Not set        │
│  $(key) Qwen            ✗ Not set        │
├──────────────────────────────────────────┤
│  $(check) Done                           │
└──────────────────────────────────────────┘

Supported Providers:

OpenAI (gpt-4.1, gpt-4o, o3-mini, o4-mini)
Anthropic (claude-sonnet-4, claude-opus-4, claude-haiku-4.5)
Google Gemini (gemini-2.5-pro, gemini-2.5-flash)
DeepSeek (deepseek-chat, deepseek-reasoner)
Qwen (qwen-plus, qwen-turbo, qwen-max)
OpenRouter (200+ models)

Secure API Key Storage

API keys are stored in your OS keychain, not in settings.json:

// Stored securely via VS Code SecretStorage API
await context.secrets.store('qonqrete.OPENAI_API_KEY', key);

Priority chain:

Environment variable (e.g., $OPENAI_API_KEY) — Always wins
Stored secret in keychain — Used if no env var
Prompt to set key

Auto-migration: Old keys in settings.json are automatically moved to secure storage.

Typical Workflow

# 1. Open your project
code /path/to/my-project

# 2. Deploy runtime (first time only)
# Command: QonQrete: Deploy to Workspace

# 3. Configure AI (first time only)
# Command: QonQrete: Set AI Configuration

# 4. Create your task
# Command: QonQrete: Create tasq.md
# Edit tasq.md with your requirements

# 5. Run!
# Command: QonQrete: Run Tasq (Ctrl+Alt+Q)

# 6. View results in qage_001/, qage_002/, etc.

Status Bar

The status bar shows:

$(check) QonQrete — Ready to run
$(sync~spin) QonQrete — Running
$(warning) QonQrete — Runtime not found (click to deploy)

Settings

Available in Settings > Extensions > QonQrete:

Setting	Description	Default
`qonqrete.containerRuntime`	Docker, Podman, or Auto	Auto
`qonqrete.defaultShell`	bash, zsh, or Auto	Auto
`qonqrete.showWelcome`	Show welcome message	true

Troubleshooting

”Runtime not found”

Click the status bar or run QonQrete: Deploy to Workspace.

”Container image not built”

Run QonQrete: Init Workspace to build the image.

”API key required”

Run QonQrete: Set AI Configuration and enter your keys.

Windows Users

Git Bash or WSL required. Native CMD/PowerShell not supported.

Keyboard Shortcuts

Action	Windows/Linux	macOS
Run Tasq	`Ctrl+Alt+Q`	`Cmd+Alt+Q`
Command Palette	`Ctrl+Shift+P`	`Cmd+Shift+P`

Requirements

VS Code 1.80.0+
Docker or Podman
Bash shell (Git Bash on Windows)
API key for at least one provider

IntelliJ Plugin Usage Guide

The QonQrete IntelliJ plugin brings autonomous code generation to all JetBrains IDEs. This guide covers all features added in v1.2.0.

Supported IDEs

All JetBrains IDEs (2023.3+):

IntelliJ IDEA (Community & Ultimate)
WebStorm, PyCharm, PhpStorm
RubyMine, GoLand, CLion, Rider
Android Studio, DataGrip

Installation

From JetBrains Marketplace

Open Settings (Ctrl+Alt+S)
Go to Plugins
Search “QonQrete”
Click Install

From ZIP

Settings → Plugins → ⚙️ → Install Plugin from Disk
Select qonqrete-intellij-1.2.0.zip

First-Time Setup (Two Clicks)

1. Deploy to Workspace

Open Actions (Ctrl+Shift+A)
Run QonQrete: Deploy to Workspace
Runtime installs to .qonqrete/ automatically
.gitignore updated automatically

2. Set AI Configuration

Run QonQrete: Set AI Configuration
Select providers for each agent
Enter API keys (stored securely in PasswordSafe)
Done!

Actions Reference

Action	Description	Shortcut
Deploy to Workspace	Install runtime to `.qonqrete/`	—
Set AI Configuration	Configure providers, models, API keys	—
Create tasq.md	Generate starter template	—
Run Tasq	Execute the pipeline	`Ctrl+Alt+Q`
Resume Run	Continue from cheQpoint	—
Init Workspace	Build container image	—
Clean Qages	Remove build artifacts	—
Show Status	Display runtime status	—
Run as QonQrete Tasq	Run current file as tasq	—

Tool Window

The QonQrete tool window (View → Tool Windows → QonQrete) shows:

Control Panel — Deploy, Create Tasq, Run, Resume buttons
Status — Runtime version, container status
Qage Browser — View build artifacts with file tree
Artifact Details — File contents preview

AI Configuration Dialog

The “Set AI Configuration” action opens a full dialog:

┌─────────────────────────────────────────────────┐
│  QonQrete: AI Configuration                     │
├─────────────────────────────────────────────────┤
│  Agent Providers & Models                       │
│  ─────────────────────────────────────────────  │
│  tasqleveler:    [OpenAI    ▼] [gpt-4o       ] │
│  instruqtor:     [OpenAI    ▼] [gpt-4o       ] │
│  construqtor:    [Anthropic ▼] [claude-sonnet] │
│  inspeqtor:      [Gemini    ▼] [gemini-2.5   ] │
│                                                 │
│  API Keys (stored securely)                     │
│  ─────────────────────────────────────────────  │
│  OpenAI:         [•••••••••••••••••••••••••••] │
│  Anthropic:      [•••••••••••••••••••••••••••] │
│  Google:         [                           ] │
│  DeepSeek:       [                           ] │
│  Qwen:           [                           ] │
│  OpenRouter:     [•••••••••••••••••••••••••••] │
│                                                 │
│            [Cancel]              [OK]           │
└─────────────────────────────────────────────────┘

Supported Providers:

OpenAI (gpt-4.1, gpt-4o, o3-mini, o4-mini)
Anthropic (claude-sonnet-4, claude-opus-4, claude-haiku-4.5)
Google Gemini (gemini-2.5-pro, gemini-2.5-flash)
DeepSeek (deepseek-chat, deepseek-reasoner)
Qwen (qwen-plus, qwen-turbo, qwen-max)
OpenRouter (200+ models)

Secure API Key Storage

API keys are stored in IntelliJ’s PasswordSafe (encrypted credential store):

// Stored securely via IntelliJ PasswordSafe
val attrs = CredentialAttributes(generateServiceName("QonQrete", envKey))
PasswordSafe.instance.set(attrs, Credentials(envKey, value))

Priority chain:

Environment variable (e.g., $OPENAI_API_KEY) — Always wins
PasswordSafe stored key — Used if no env var
Prompt to set key

The status bar widget shows:

QonQrete v1.2.0 — Version info
Click to show status popup

Editor Notifications

When you open a tasq.md file, an editor banner appears:

Run — Execute immediately
Configure — Open AI configuration

Right-click on a .md file to see:

Run as QonQrete Tasq — Execute this file as a task

Typical Workflow

# 1. Open your project in IntelliJ/WebStorm/etc.

# 2. Deploy runtime (first time only)
# Action: QonQrete: Deploy to Workspace

# 3. Configure AI (first time only)
# Action: QonQrete: Set AI Configuration

# 4. Create your task
# Action: QonQrete: Create tasq.md
# Edit tasq.md with your requirements

# 5. Run!
# Action: QonQrete: Run Tasq (Ctrl+Alt+Q)

# 6. View results in Tool Window → Qage Browser

Settings

Available in Settings → Tools → QonQrete:

Setting	Description	Default
Container Runtime	Docker, Podman, or Auto	Auto
Default Shell	bash, zsh, or Auto	Auto
Show Notifications	Display run notifications	true
Auto-refresh Tool Window	Refresh after runs	true

Troubleshooting

”Runtime not found”

Run QonQrete: Deploy to Workspace from Actions.

”Container image not built”

Run QonQrete: Init Workspace to build the image.

”API key required”

Run QonQrete: Set AI Configuration and enter your keys.

Windows Users

Git Bash or WSL required. Native CMD/PowerShell not supported.

Keyboard Shortcuts

Action	Windows/Linux	macOS
Run Tasq	`Ctrl+Alt+Q`	`Cmd+Alt+Q`
Find Action	`Ctrl+Shift+A`	`Cmd+Shift+A`
Settings	`Ctrl+Alt+S`	`Cmd+,`

Requirements

JetBrains IDE 2023.3+
Docker or Podman
Bash shell (Git Bash on Windows)
API key for at least one provider

Quickstart (v1.2.0)

CLI

VS Code

JetBrains / IntelliJ IDEs

Next steps

QonQrete - Secure AI Construction Loop System

Major Improvements: The Dual-Core Memory System with Local Qontextor

The Local Qontextor Stack

Fast vs. Complex Local Mode

Version

What’s New in v1.0.4

Core Principles

Architecture Overview

The Workflow CyQle

System Requirements

1. Docker

2. Microsandbox (Optional)

Getting Started

License

QonQrete Documentation

Table of Contents

Architecture

High-Level System Overview

Detailed Pipeline Flow

ConstruQtor Build Loop (Interleaved Mode)

InspeQtor Batched Review Flow

Directory Structure

Cost Flow Visualization

Execution Flows

1. Initialization Flow (./qonqrete.sh init)

2. Main Execution Flow (./qonqrete.sh run)

3. Cleanup Flow (./qonqrete.sh clean)

Agent & Orchestrator Logic

Orchestrator Logic (qrane/qrane.py)

Default Agent Logic

Core Abstraction: worqer/lib_ai.py

1. instruQtor (The Planner)

2. construQtor (The Executor)

3. inspeQtor (The Reviewer)

Specialized Agents

1. qompressor (The Skeletonizer)

2. qontextor (The Symbol Mapper)

3. calqulator (The Cost Estimator)

Configuration

Getting Started

Terminology

QonQrete Terminology

Core Components & Roles

Environment & Structure

Workflow & Data

Predictability & Enforcement (v1.0.4)

Caching & Memory (v0.8.0)

Build Quality (v0.9.0)

User Interaction

Local Memory Mechanism in QonQrete

Components of Local Memory

1. reqap.d/ (Operational Memory / Feedback Loop)

2. tasq.d/ (Directive Memory / Current Task)

3. qontext.d/ (Semantic Memory / Context Cache)

4. bloq.d/ (Structural Memory / Skeleton Cache)

5. exeq.d/ (Execution Summaries)

6. QONQ_PREVIOUS_LOG Environment Variable (Ephemeral Memory)

Local Memory Management Philosophy

QonQrete Functional Tests

1. Environment and Setup Tests

1.1. qonqrete.sh CLI

2. Core Orchestration (Qrane) Tests

2.1. Run Modes

2.2. Cheqpoint Configuration (config.yaml)

2.3. Cycle and File Management

3. Agent Configuration and Behavior

3.1. Dynamic Pipeline (pipeline_config.yaml)

3.2. Agent Settings (config.yaml)

4. TUI Mode Tests (--tui)

5. Edge Cases and Error Handling

6. Multi-Platform Testing

7. Provider & Model Matrix Tests

7.1 Provider / Model Catalog (Reference)

7.2 Single-Provider / All-Agents Smoke Tests

7.3 Per-Agent Provider Rotation (One Agent at a Time)

1. Initialization Flow (`./qonqrete.sh init`)

2. Main Execution Flow (`./qonqrete.sh run`)

3. Cleanup Flow (`./qonqrete.sh clean`)

Orchestrator Logic (`qrane/qrane.py`)

Core Abstraction: `worqer/lib_ai.py`

1. `instruQtor` (The Planner)

2. `construQtor` (The Executor)

3. `inspeQtor` (The Reviewer)

1. `qompressor` (The Skeletonizer)

2. `qontextor` (The Symbol Mapper)

3. `calqulator` (The Cost Estimator)

1. `reqap.d/` (Operational Memory / Feedback Loop)

2. `tasq.d/` (Directive Memory / Current Task)

3. `qontext.d/` (Semantic Memory / Context Cache)

4. `bloq.d/` (Structural Memory / Skeleton Cache)

5. `exeq.d/` (Execution Summaries)

6. `QONQ_PREVIOUS_LOG` Environment Variable (Ephemeral Memory)

1.1. `qonqrete.sh` CLI

2. Core Orchestration (`Qrane`) Tests

2.2. Cheqpoint Configuration (`config.yaml`)

3.1. Dynamic Pipeline (`pipeline_config.yaml`)

3.2. Agent Settings (`config.yaml`)

4. TUI Mode Tests (`--tui`)

8.3.1 `mode: program`

8.3.2 `mode: enterprise`

8.3.3 `mode: performance`

8.3.4 `mode: security`

8.3.5 `mode: innovative`

8.3.6 `mode: balanced`

8.4 CLI Override Tests (`--mode` and `--briq-sensitivity`)

1. `tasq.d/` (Current Directive Context)

2. `bloq.d/` (Structural Context / Code Skeletons)

3. `qontext.d/` (Semantic Context / Code Index)

4. `QONQ_PREVIOUS_LOG` (Operational History Context)

5. `qodeyard/` (Raw Codebase / Reference Context)

6. `config.yaml` and `pipeline_config.yaml` (System Configuration Context)

1. Initialization Flow (`./qonqrete.sh init`)

2. Main Execution Flow (`./qonqrete.sh run`)

3. Cleanup Flow (`./qonqrete.sh clean`)

Orchestrator Logic (`qrane/qrane.py`)

Core Abstraction: `worqer/lib_ai.py`

0. `tasqLeveler` (The Enhancer) - NEW in v0.9.0

1. `instruQtor` (The Planner)

2. `construQtor` (The Executor)

3. `inspeQtor` (The Reviewer)

1. `qompressor` (The Skeletonizer)

2. `qontextor` (The Symbol Mapper)

3. `calqulator` (The Cost Estimator)