issue-loop

Issue-driven repair loop with a Gatekeep audit gate, a dual-layer OKF knowledge base, and Herdr-managed CLI agents.

Architecture in one paragraph

A main agent (Codex) is the loop brain. It attaches to the Gatekeep MCP server — a Python tool layer exposing an audit graph, a dual-layer OKF knowledge base, a semantic linter, and Herdr wrappers. Through these tools it runs each issue through: understand (lint gate) → repair loop (review→repair→validate) → memory, parking human-decision nodes on the audit graph. Sub-agents (Cline + glm-5.2) are launched by Herdr inside each issue's project directory.

主 Agent (Codex) ──挂 Gatekeep MCP──┐
                                    ▼
            Gatekeep MCP Server (Python :8100)
              ├ audit graph (BonsAI CanvasMCP, re-semanted)
              ├ kb (OKF 0.1, dual-layer: global + project)
              ├ linter (BonsAI SemanticLintService, verbatim policy)
              ├ state (checkpoints + decisions)
              └ herdr wrappers (start/wait/read/send)
                                    │
                                    ▼
                         Herdr manages sub-agent processes
                         (Cline + glm-5.2, cwd = issue.project)

Quick start

This project uses uv for dependency and Python management.

# Install dependencies (creates .venv, locks to uv.lock)
uv sync --group test

# Start the Gatekeep MCP server
uv run issue-loop --config config.yaml serve

# (separate terminal) launch the main orchestrator agent
uv run issue-loop --config config.yaml start

Common commands:

uv run pytest                          # run tests
uv add <package>                       # add a runtime dependency
uv add --group test <package>          # add a test dependency
uv sync                                # sync env from uv.lock

Layout

• issue_loop/ — the Python tool layer (MCP server + tools).
• gatekeep/ — ported assets (linter prompt verbatim from BonsAI, schema, audit system prompt).
• prompts/ — fixed per-phase agent instructions.
• kb/ — global OKF knowledge bundle.
• examples/issues/ — sample issues.
• tests/ — pytest suite.

Provenance

The linter policy and audit-graph MCP design are ported (policy verbatim, mechanism 1:1) from BonsAI (SemanticLintService.swift, CanvasMCP.swift, CanvasGraph.swift). The knowledge base follows the Open Knowledge Format (OKF) 0.1 spec.