v1.4.5 MLCon Edition

QonQrete

The First 100% File-Based

Controlled Execution For AI-Assisted Coding

QonQrete quickstart

Bootstrap, Init, Run

One curl installs QonQrete into your project. Then init and run.

Install

Drop it in.

curl -fsSL https://qonqrete.sh/install.sh | bash

Key

Set one key.

export OPENAI_API_KEY="..."

Init

Prepare runtime.

./.qonqrete/qonqrete.sh init

Run

Build inside control.

./.qonqrete/qonqrete.sh run -f tasq.md --auto -N
./.qonqrete/qonqrete.sh status
./.qonqrete/qonqrete.sh audit

GET QONQRETE FOR YOUR IDE

Construction yard art

QonQrete Build Loop

Decorative runtime scene.

🏗️ WHAT IS QONQRETE?

QonQrete is a controlled execution layer for AI-assisted coding. You provide a task, QonQrete runs a structured plan → build → validate → inspect loop in an isolated qage, and you decide how and when outputs sync back into your repository.

THE PIPELINE

📝

tasq.md YOUR INPUT

You write what you want in plain English. "Build a REST API with user authentication" - that's it!

🏠 Like: Telling an architect "I want a 3-bedroom house with a pool"

🎯

Qrystallizer + Qonstrictor INTAKE + CONSTRAINTS 🧠 AI

Clarifies ambiguous intake, enforces readiness, and applies explicit constraints before planning starts.

🏠 Like: Finalizing scope and permit constraints before construction begins.

📋

InstruQtor THE PLANNER 🧠 AI

Produces briqs, execution blueprint, and completion criteria. CalQulator estimates cost before build.

🏠 Like: Turning a project brief into sequenced build tickets with cost visibility.

🔨

ConstruQtor THE BUILDER 🧠 AI

Writes and edits code in qodeyard using `hybrid` coding mode, with bounded retry and validation-aware attempts.

🏠 Like: Building from tickets, then reworking only where inspection says it is needed.

🔍

InspeQtor THE REVIEWER 🧠 AI

Runs deterministic checks, optional smoketests, and AI review, then emits a structured verdict and repair plan.

🏠 Like: Inspection with written findings, evidence, and bounded corrective actions.

✋

Sync + Save Control CONTAINMENT ⚡ FREE

Choose repo sync or `--no-sync`. With `-N/--no-sync`, outputs stay in qage/qonstruction paths for review and comparison.

🏠 Like: Keeping new work in a staging yard until you explicitly decide what enters the main project.

🔄

Bounded Repair ITERATE WITH LIMITS

QonQrete can continue with bounded repair and continuation metadata, but does not blindly loop forever.

🏠 Like: Controlled punch-list iterations with clear stop conditions.

THE SECRET SAUCE: LOCAL AGENTS

Local helpers keep runs inspectable and efficient while preserving model flexibility:

🦴

QOMPRESSOR

Builds deterministic structural skeletons in bloq.d/ for Python, shell, JS/TS, HTML, and CSS.

→ Smaller context with architecture preserved

🔍

QONTEXTOR

Emits deterministic structural context maps in qontext.d/, including multi-language extraction metadata.

→ Better grounding before generation

🌀

QONTRABENDER

Policy-driven cache payload composer, most relevant when Gemini-oriented caching is enabled.

→ Optional context reuse strategy

✅

QUALIFIER + SMOQETESTER

Deterministic syntax/import/structure checks plus optional smoketest evidence for stronger inspection outcomes.

→ Validation during the run, not only after

WHY THIS MATTERS

🔒

SECURE BY DESIGN

Runs inside a qage container path with hardened runtime defaults and explicit artifact boundaries.

💰

MODEL FLEXIBILITY

Primary defaults align to venice / deepseek-v3.2, with provider and model selection configurable per agent.

👀

FULLY TRANSPARENT

Run manifests, timelines, validation bundles, verdicts, and audit payloads keep execution inspectable.

🏠

LOCAL FIRST

Supports local runtime providers through mlx and llama-cpp with explicit api_base_url configuration.

⚡ SEE IT IN ACTION

$ curl -fsSL https://qonqrete.sh/install.sh | bash

$ ./.qonqrete/qonqrete.sh init

$ ./.qonqrete/qonqrete.sh run -f tasq.md --auto -N

Get started View on GitHub

V1.4.5 MLCON EDITION

Structured execution, bounded repair, truthful inspection, and cleaner runtime defaults for live runs.

🛡️

TRUTHFUL INSPECTION

Final qodeyard/ files are treated as authoritative review evidence with deterministic snippet metadata.

→ Less relay noise, better evidence gating

🔄

STREAMING UX CLEANUP

Heartbeat chatter is reduced, concise heredoc streaming is default, and raw stream mode is still available on demand.

→ Cleaner terminal output without losing audit capture

📐

HYBRID CODING DEFAULT

ConstruQtor defaults to hybrid, with deterministic fallback/escalation behavior between direct and heredoc transports.

→ Controlled iteration instead of blind looping

DO NOT TRUST THE AI. CONTROL THE PROCESS.

QonQrete is designed for bounded autonomy, inspectable execution, and explicit sync control.

✋

NO-SYNC WORKFLOW

-N/--no-sync skips repo-root sync-back while preserving qage/qonstruction outputs for review.

→ Safer experimentation without repo pollution

✏️

QAGE PRESERVATION

Runs stay inspectable with manifests, validation bundles, realization bundles, and verdict artifacts tied to each qage.

→ Compare runs before manually applying outputs

⚡

LOCAL-FIRST DIRECTION

Local runtime providers (mlx, llama-cpp) are supported through OpenAI-compatible local/LAN endpoints.

→ Local models solve where; QonQrete controls how

AUDIT TRAIL + FAILURE CONTAINMENT

QonQrete keeps execution visible on disk so teams can inspect what happened before trusting the output.

📂

FULL ARTIFACT TRAIL

Runs record audit/timeline.md, audit/events.ndjson, run-manifest.v1.json, planning, build, validation, realization, and verdict artifacts.

→ Inspectable by design

🔐

KEEP CODE OUT OF CLOUD AI

Seed repo content only when needed (--seed-repo). By default, fresh runs start from empty qodeyard and stay isolated.

→ Reduced accidental overwrite risk

🔁

REPRODUCIBLE & DEBUGGABLE

Resume preserves pass lineage and continuation metadata, including interrupted-pass semantics.

→ Clear iteration history across reruns

Why QonQrete?

Execution first, generation second

Most tools optimize for code output. QonQrete optimizes the execution process: clarification, constraints, planning, build, validation, inspection, and controlled continuation.

Bounded repair over endless loops

Repair attempts are structured and capped. QonQrete favors explicit continuation metadata over invisible retry spirals.

Model-flexible by design

Provider/model choices can change per task or budget. Default runtime alignment is venice / deepseek-v3.2, with local runtime support for mlx and llama-cpp.

Audit trail built in

Artifacts and manifests are recorded in each qage so teams can inspect timelines, outputs, and verdict paths before syncing anything back.

Controlled sync for safer experimentation

-N/--no-sync keeps run outputs in qage/qonstruction paths so you can compare, test, and apply changes deliberately.