ForgeLoop

A human-supervised autonomous SDLC + STLC control plane. ForgeLoop orchestrates the full software delivery lifecycle — from requirements to production — coordinating AI agent runs, enforcing human approvals, delegating code execution to existing tools, and routing every LLM call through a deterministic, cost- and sensitivity-aware model selector.

ForgeLoop is the control plane, not a from-scratch coding agent. Code execution is delegated to existing tools (Aider, OpenHands, Semgrep, Trivy, Gitleaks, axe-core, Playwright, Kodus/Kody, OSV-Scanner). ForgeLoop adds orchestration, governance, approvals, audit trails, project memory, and model routing.

Build status

Scope	Status
Releases 1–6 (core, 32 tasks)	Complete
Post-32 controlled adoption (Tasks 75–85)	Complete
Release 10 — Operational Execution Layer (86–100)	Complete
Release 10.1 — Runner Quality Hardening (101–106)	Complete
Release 10.2 — Quality-Gate Hardening (107–110)	Complete
Release 10.3 — Multi-Provider Model Pool & Selection (111–119)	Complete
Task 120 — selector adoption into live routing	Complete (enabled by default)
Task 121 — real WorkSafePolicy sensitivity in live hook	Complete

Backend test suite: 1611 passing, 1 skipped — no GCP, no real LLM keys, no network required.

docs/roadmap.md + docs/architecture.md + CLAUDE.md are the authoritative scope/direction. This README is a summary.

What ForgeLoop does today

Delivery pipeline

1. Accept structured requirements or tickets (API or web UI).
2. Project context + project memory (architecture decisions, standards, prior feedback).
3. Requirement analysis + clarification questions before planning.
4. Planning agent → implementation-ready markdown brief.
5. Decompose briefs into dev tasks / subtasks with lifecycle management.
6. Human approval gates at every risky transition; full audit trail.
7. Connect repositories + enforce repo safety profiles (branch protection, no force-push).
8. ToolRunner abstraction → real Aider (local Ollama subprocess) and OpenHands (HTTP) execution bridges — gated, audited, snapshot-diffed.
9. Native multi-dev-task integration (POST /workspaces/{id}/integration-runs — ordered merge, structured 409 on conflict, never silent-drops a member, stale-base reconcile).
10. PR draft workflow + Kodus/Kody AI review (real CLI-key HTTP adapter) + a closed review-remediation loop (findings re-enter execute→commit→QA→re-review, approval-gated).
11. Deterministic QA/security checks (Semgrep, Trivy, OSV-Scanner, Gitleaks, axe-core, Playwright, native tests).
12. CI failure ingestion → advisory analysis; incident workflow → advisory triage; project-memory learning loop (human-approved candidates).

Runner-output quality (Releases 10.1–10.2)

A deterministic, cheap, offline gate (generated_test_quality.py) rejects vacuous / placeholder / pass-only / no-assertion / prose / shallow-hint-stub / syntax-broken / non-importable / acceptance-criteria-incomplete generated tests before they count as success. Text + ast.parse only — never executes candidate code, runs pytest, imports the test, or uses AI.

Multi-provider model selection (Release 10.3 + Tasks 120/121)

A deterministic, pure selection strategy routes every LLM call by sensitivity (fail-closed) → capability → complexity tier → cost → provider health:

• Provider pool: DeepSeek (primary paid default), Kimi (approval-gated, fail-closed — Agent Swarm), GLM/Z.ai (free Flash tiers default-eligible + paid + coding-plan), MiniMax, Ernie (via OpenRouter, baidu/… slugs), Xiaomi MiMo. (Qwen/Alibaba was dropped by owner directive — subscription-only + data-privacy.)
• All providers are OpenAI-API-compatible → one OpenAICompatibleProvider + config profiles + a generic vendor-quirk hook. No per-vendor classes.
• A data-only model catalog (model_catalog.py) carries each model's price, context window, capabilities, gating, and data-retention posture (conservative data_retention_ok=False).
• Fail-closed sensitivity: restricted/confidential data routes local-only or is blocked — never silently sent to an external provider.
• Cost controls: metered paid only inside the fail-closed budget guard; Kimi/GLM-Max approval-gated; free Flash default-eligible; a context-cost engine budgets context per tier (prompt-cache prefix ordering, free-model pre-summarization) so a smaller context can unlock a cheaper model.
• Live: the selector drives real routing via resolve_routed_provider behind MODEL_SELECTOR_ROUTING_ENABLED (default on, env-overridable, fail-safe; the existing expensive/budget/rate-limit guards still enforce on top). Preview without executing: POST /model-selection/preview, POST /model-selection/context-cost-preview, GET /runtime/model-selection, GET /runtime/context-cost.

What it does NOT do (by design / safety)

• No autonomous branch, commit, PR, merge, deploy, or rollback. Controlled forgeloop/* branch + draft PR automation is config-gated (default off), approval-gated, QA-gated, audited; merge/deploy/force-push/protected-branch are always forbidden.
• No live monitoring integration (Sentry/Datadog/Cloud-Logging-polling/OpenTelemetry-as-source).
• No Slack/email/PagerDuty notifications; no GitHub webhook/CI-provider direct integration.
• No multi-tenancy/billing.
• No broad RAG/vector indexing of raw code/logs/secrets (only redacted project-memory/summary retrieval, controlled).
• No secrets in logs or prompts; no proprietary data to external LLMs without approval.

The direction is controlled adoption, not endless expansion — items once phrased "always out of scope" are deferred/controlled, governed by docs/roadmap.md. The scope is hard-bounded: no task beyond the current roadmap bound without an explicit docs/roadmap.md update.

Runtime profiles

ForgeLoop is cloud-supported, not cloud-dependent. Profile is env-selected, never hard-coded:

Profile	Storage	LLM	Secrets	Cloud
local	InMemory (dev/tests) → MongoDB (durable local)	Mock / Ollama / hosted pool	env vars	not required
hybrid	local storage	hosted pool if configured	env vars	GitHub optional
cloud	Firestore	any configured provider	Secret Manager	Cloud Run

Tech stack

Layer	Technology
Backend	Python 3.12, FastAPI, Uvicorn, Pydantic v2
AI	Mock (tests/default), Ollama (local), and the hosted pool: DeepSeek · Kimi · GLM · MiniMax · Ernie (via OpenRouter) · MiMo — provider-agnostic, deterministically routed
Persistence	In-memory (local/tests) · MongoDB (durable local) · Firestore (cloud) — repository-abstraction with parity tests
Frontend	React 18, Vite, TypeScript (currently minimal — a proper operator UI is the next authorized release)
Container	Docker (python:3.12-slim), port 8080
Cloud	Google Cloud Run, Artifact Registry, Firestore, Secret Manager
Infra	Terraform (google ~> 5.0)
CI/CD	GitHub Actions + Workload Identity Federation

Repository structure

incidentpilot/
├── services/api/                 # FastAPI backend
│   └── app/
│       ├── main.py, config.py, auth.py
│       ├── models/               # pydantic models (package)
│       ├── repositories.py, repositories_mongo.py, repositories_state.py
│       ├── routes/               # API routers
│       ├── services/             # business logic (model_catalog/_selection/
│       │                         #  _sensitivity/_complexity/_health/
│       │                         #  context_cost/model_routing/…)
│       ├── llm/                  # provider adapters (single OpenAICompatible
│       │                         #  + mock/ollama/deepseek/kimi)
│       └── tool_runners/         # aider, openhands
│   └── tests/                    # pytest (1611 passing)
├── apps/web/                     # React + Vite frontend (minimal today)
├── infra/terraform/              # GCP infrastructure
├── docs/                         # roadmap.md, architecture.md,
│                                 #  tooling-strategy.md, qa-strategy.md,
│                                 #  security-*.md, dogfood-run-*-findings.md
├── .github/workflows/            # api-ci.yml, api-deploy.yml
├── CLAUDE.md                     # agent operating instructions (authoritative)
└── README.md

Local setup — backend

cd services/api
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env            # defaults: mock LLM + in-memory storage
uvicorn app.main:app --port 8080 --reload

API at http://localhost:8080, interactive docs at /docs. Tests: cd services/api && .venv/bin/python -m pytest -q (no GCP/keys/network).

Optional real coding runner (Aider, local):

uv tool install aider-chat --with audioop-lts   # Python 3.13 audioop workaround

Local setup — frontend

cd apps/web
npm install
cp .env.example .env            # VITE_API_BASE_URL defaults to :8080
npm run dev                     # http://localhost:5173

Environment variables (key ones)

Core

Variable	Default	Description
ENVIRONMENT	local	Runtime label
REPOSITORY_PROVIDER	memory	memory · local_document (MongoDB) · firestore
LLM_PROVIDER	mock	Default provider; mock short-circuits routing (tests/no-key)
AUTH_ENABLED	true	false only for local/tests
AUTH_ADMIN_EMAIL / AUTH_ADMIN_PASSWORD	(empty)	Single admin login
AUTH_TOKEN_SECRET	(empty)	Required when auth on (≥32 chars; fail-fast)
CORS_ALLOWED_ORIGINS	http://localhost:5173,http://127.0.0.1:5173	No wildcard default

Model selection (Release 10.3 + 120/121)

Variable	Default	Description
MODEL_SELECTOR_ROUTING_ENABLED	true	Selector drives live routing; fail-safe; set false to disable
MODEL_ROUTING_ENABLED / MODEL_ROUTING_ENFORCED	true	Routing policy enforced
OLLAMA_ENABLED / OLLAMA_BASE_URL	false / http://localhost:11434	Local runner availability (sensitivity fallback)
DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL	(empty) / https://api.deepseek.com	Primary paid default
KIMI_API_KEY / KIMI_BASE_URL	(empty) / https://api.moonshot.ai/v1	Approval-gated, fail-closed
GLM_API_KEY / GLM_BASE_URL / GLM_MODEL	(empty) / https://api.z.ai/api/paas/v4 / glm-4.7-flash	Free Flash default-eligible
MINIMAX_API_KEY / MINIMAX_BASE_URL / MINIMAX_MODEL	(empty) / https://api.minimax.io/v1 / MiniMax-M2
ERNIE_API_KEY / ERNIE_BASE_URL / ERNIE_MODEL	(empty) / https://openrouter.ai/api/v1 / baidu/ernie-4.5-300b-a47b	Via OpenRouter (key = OpenRouter key)
MIMO_API_KEY / MIMO_BASE_URL / MIMO_MODEL	(empty) / https://api.xiaomimimo.com/v1 / mimo-v2.5-pro
PROVIDER_BUDGETS_ENABLED / DAILY_*_BUDGET_USD	true / per-provider	Fail-closed budget guard

Base URLs/model slugs are seeds — confirm against your real accounts. Absent keys ⇒ provider unconfigured and not routing-eligible (graceful).

See services/api/app/config.py for the full list (auth, Mongo, Firestore, ContextPack, observability, etc.).

Deployment

infra/terraform/ provisions Artifact Registry, Firestore, Cloud Run, runtime SA + IAM, Secret Manager. terraform apply is operator-managed (not in CI). Merges to main trigger build→push→deploy via GitHub Actions + WIF (no JSON keys). The Cloud Run service is private by default; provider secrets and AUTH_TOKEN_SECRET/AUTH_ADMIN_PASSWORD go in Secret Manager.

ForgeLoop vs ForgeLoop Studio

ForgeLoop (this repo) is the engineering control plane. ForgeLoop Studio is the parked future vision — ProductScout (discovery), ForgeLoop (this), AuditLens (independent auditor), LaunchPilot (marketing). Studio modules are not implemented and out of scope unless explicitly requested.

Roadmap

Authoritative scope lives in docs/roadmap.md. Releases 1–6, controlled-adoption 75–85, Releases 10 / 10.1 / 10.2 / 10.3, and Tasks 120–121 are complete. Owner-authorized upcoming work (sequenced): operator UI/dashboard, agent-quality features (critic pass, capability-weighted routing, acceptance-criteria-driven prompts + patch validation, golden-task benchmark, project-memory retrieval, flaky-test detection + cost/quality dashboards), then Dogfood Run 3 (end-to-end validation with real provider keys). Each is bounded and recorded in docs/roadmap.md before implementation.

License

ForgeLoop is source-available, not open-source. It is licensed under the PolyForm Noncommercial License 1.0.0 — a standard, plain-language license maintained by the PolyForm Project.

• Permitted (free): personal use, research, experiment, study, hobby/amateur projects, and use by charitable, educational, public-research, public-safety/health, environmental, or government organizations — including modifying and redistributing under the same terms.
• Not permitted without a separate commercial license: any commercial use, including use within a for-profit organization, in a paid product or service, or for commercial advantage.

For a commercial license, contact the licensor at zeeshan04956@gmail.com. Full terms are in LICENSE; the canonical text lives at https://polyformproject.org/licenses/noncommercial/1.0.0.