Loop Engineering Platform

A clean, standalone product skeleton for enterprise Loop Engineering:

• one unified loop kernel;
• two first-class workflows: PR diff and log root cause;
• shared fix, test, verify, gate, state, and report infrastructure;
• MR submission intentionally left behind a human approval boundary.

This project is independent from ForgeWorks. ForgeWorks remains the mechanism research and prototype source; this repository owns the productized loop boundary.

Current Scope

PR diff --------> PR workflow ----\
                                  > LoopKernel -> fix -> test -> verify -> gate -> MR-ready report
Log root cause -> Log workflow ---/

The current implementation is a local-first MVP. It can read PR diff text or git diff, extract local log error seeds, query Loki for production log context, call either the deterministic local agent or an OpenAI-compatible LLM gateway, propose patches, preview/apply exact old_code replacements, run dry-run or local test commands, persist JSONL state, and write MR-ready Markdown reports. Git hosting and CI/CD connectors implement the existing adapter boundaries; SLS/ELK can be added behind the same log-source contract.

Quick Start

python -m pytest -q -p no:cacheprovider

$env:PYTHONPATH='src'
python -m loop_engineering_platform.cli pr --scope src/payment.py --diff "fix SQL string concat"
python -m loop_engineering_platform.cli log --affected-scope OrderService.java --root-cause "NPE at OrderService.java:42"

Reports are written to .loop-runs/reports/. State summaries are appended to .loop-runs/state/runs.jsonl.

Useful Commands

Read a diff directly from git:

$env:PYTHONPATH='src'
python -m loop_engineering_platform.cli pr --scope src/payment.py --from-git-diff --repo-root .

Read a root-cause seed from a local log file:

$env:PYTHONPATH='src'
python -m loop_engineering_platform.cli log --affected-scope src/order.py --log-file logs/app.log

Query Loki for production log context:

$env:PYTHONPATH='src'
$env:LOOP_LOKI_URL='https://loki.example.com'
$env:LOOP_LOKI_TOKEN='<optional-loki-token>'
python -m loop_engineering_platform.cli log `
  --affected-scope src/order.py `
  --log-provider loki `
  --log-query '{service="orders",level=~"error|critical"}' `
  --log-since 30m `
  --log-limit 100 `
  --loki-token-env LOOP_LOKI_TOKEN

The Loki connector calls /loki/api/v1/query_range, normalizes stream labels into log events, keeps signal lines such as ERROR, Exception, Traceback, CRITICAL, and FATAL, and feeds that compact evidence into the existing log root-cause workflow. Tokens are read only from environment variables; no secret values should be stored in config files.

Run a real local test command:

$env:PYTHONPATH='src'
python -m loop_engineering_platform.cli pr --scope src/payment.py --diff "fix SQL" --test-command "python -m pytest tests/payment -q"

Preview or apply exact patch replacements under a repo root:

$env:PYTHONPATH='src'
python -m loop_engineering_platform.cli pr --scope src/payment.py --diff "fix SQL" --repo-root . --preview-patches
python -m loop_engineering_platform.cli pr --scope src/payment.py --diff "fix SQL" --repo-root . --apply-patches

--apply-patches only applies exact unique old_code matches. Ambiguous or missing matches are rejected.

Use an OpenAI-compatible relay or model gateway:

$env:PYTHONPATH='src'
$env:LOOP_LLM_BASE_URL='https://ai-gate.cloud/v1'
$env:LOOP_LLM_API_KEY='<your-api-key>'
$env:LOOP_LLM_MODEL='gpt-5.5'
python -m loop_engineering_platform.cli pr --agent openai-compatible --scope src/payment.py --diff "fix SQL string concat"
python -m loop_engineering_platform.cli log --agent openai-compatible --affected-scope OrderService.java --root-cause "NPE at OrderService.java:42"

The LLM adapter talks to /v1/chat/completions semantics and intentionally stores no secrets. Change LOOP_LLM_BASE_URL and LOOP_LLM_MODEL to point at other compatible gateways for DeepSeek, Zhipu, Claude-code-GPT style relays, or internal model routers. Provider-specific adapters can be added later behind the same agent boundary.

Run with enterprise safety boundaries:

$env:PYTHONPATH='src'
python -m loop_engineering_platform.cli pr `
  --enterprise-mode `
  --repo-root D:\path\to\repo `
  --workspace-dir .loop-runs/workspaces `
  --runs-dir .loop-runs `
  --scope src/payment.py `
  --diff "fix SQL string concat" `
  --test-command "python -m pytest tests/payment -q" `
  --require-real-tests `
  --require-patches-applied `
  --protected-path "src/payments/**" `
  --create-mr-draft

Enterprise mode copies the repository into an isolated workspace, applies proposed patches only inside that workspace, runs the test command from the workspace root, appends audit events to .loop-runs/audit/events.jsonl, writes state/report artifacts, and creates a local MR draft JSON when gates pass. It still does not submit or merge anything automatically.

Generate a GitHub draft PR request preview without calling GitHub:

$env:PYTHONPATH='src'
$env:LOOP_GITHUB_TOKEN='<github-token-with-minimal-scope>'
python -m loop_engineering_platform.cli pr `
  --enterprise-mode `
  --repo-root D:\path\to\repo `
  --runs-dir .loop-runs `
  --scope src/payment.py `
  --diff "fix SQL string concat" `
  --test-command "python -m pytest tests/payment -q" `
  --require-real-tests `
  --create-mr-draft `
  --mr-provider github `
  --github-repository SYZ-Coder/loop-engineering-platform `
  --github-dry-run

GitHub mode defaults to dry-run unless --github-live is explicitly supplied. Dry-run writes the exact POST /repos/{owner}/{repo}/pulls payload into .loop-runs/mr-drafts/*.json; live mode uses LOOP_GITHUB_TOKEN, creates a draft PR request through the GitHub REST API, and still leaves merge/release approval to a human.

Preview branch publication before creating a GitHub draft PR:

$env:PYTHONPATH='src'
$env:LOOP_GITHUB_TOKEN='<github-token-with-minimal-scope>'
python -m loop_engineering_platform.cli pr `
  --enterprise-mode `
  --repo-root D:\path\to\repo `
  --workspace-strategy git-clone `
  --scope src/payment.py `
  --diff "fix SQL string concat" `
  --test-command "python -m pytest tests/payment -q" `
  --publish-branch `
  --create-mr-draft `
  --mr-provider github `
  --github-repository SYZ-Coder/loop-engineering-platform `
  --github-dry-run

--publish-branch also defaults to dry-run. It records the planned git add, git commit, and git push origin HEAD:refs/heads/loop/<run-id> commands in the audit trail. Supplying --branch-live actually commits and pushes from a git-clone workspace, so use it only after reviewing the generated report and confirming the target remote/branch policy.

Require GitHub Actions before MR-ready:

$env:PYTHONPATH='src'
$env:LOOP_GITHUB_TOKEN='<github-token-with-actions-read-scope>'
python -m loop_engineering_platform.cli pr `
  --enterprise-mode `
  --repo-root D:\path\to\repo `
  --scope src/payment.py `
  --diff "fix SQL string concat" `
  --test-command "python -m pytest tests/payment -q" `
  --require-real-tests `
  --require-ci-success `
  --ci-provider github-actions `
  --ci-wait-attempts 10 `
  --ci-wait-interval-seconds 15 `
  --github-repository SYZ-Coder/loop-engineering-platform `
  --create-mr-draft

The GitHub Actions provider reads the latest workflow run for the loop branch through GET /repos/{owner}/{repo}/actions/runs?branch=<branch>&per_page=1. Use --ci-wait-attempts and --ci-wait-interval-seconds to poll queued or in-progress runs before the enterprise gate decides. If the latest run is still not completed/success, the enterprise gate escalates and no MR draft is produced.

Safety Boundary

The platform generates patch suggestions, isolated workspace changes, audit events, local MR drafts, and readiness reports. It does not create remote MRs, merge code, or submit approvals automatically. The intended production boundary remains: automatic diagnosis, patch proposal, isolated test execution, and report generation; a human decides whether to create or submit the MR.

Next Connector Milestones

1. Add provider-specific request/response shims where OpenAI-compatible relays are insufficient.
2. Add SLS and ELK providers behind the same log-source boundary now used by Loki.
3. Add GitLab/GitLab CI parity behind the same MR and CI provider boundaries.
4. Add CI/CD pre-release deployment, approval-card integrations, permission/secret governance, and post-run metrics observation behind policy gates.