diff --git a/README.md b/README.md index 65ca9db..8b06d94 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,16 @@ This repo already carries more engineering evidence than the old README surfaced - `tests/test_phase5_ui_contract.py` and `tests/test_phase5_operator_views.py` lock the operator UI to timeline, routing, artifact, and specialist-view contracts. - `.github/workflows/ci.yml` installs the declared environment and runs the full suite, Python compilation, dependency consistency, and JavaScript syntax checks on Windows and Linux. +### Test Coverage + +`main`'s `Run full test suite` CI step installs `pytest-cov` and runs `pytest --cov=. --cov-report=xml`, +but does not currently fail the build on a coverage threshold. A ratcheted coverage gate is +**in progress (PR #11)**: it adds a `.coveragerc` with `branch = true` and a `--cov-fail-under` +threshold, plus branch-coverage telemetry read from the produced `coverage.xml`. Per the PR's +own recorded validation, the repo-local suite reached ~73.3% total coverage and ~54.6% branch +coverage against the ratcheted threshold. Until PR #11 merges, coverage is measured but not +enforced on `main`. + ## Quickstart The checked-in snapshot supports a clean-clone local dashboard and full validation workflow: @@ -135,3 +145,5 @@ That is the right foundation for a later Azure-hosted control plane or worker bo ## License MIT -- see [LICENSE](LICENSE) + + diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..3d4ea7d --- /dev/null +++ b/docs/wiki/Architecture.md @@ -0,0 +1,74 @@ +# Architecture + +## Worker fan-out + telemetry boundary + critic gate + +```mermaid +flowchart TD + subgraph Manager["Manager-led workflow (entities/repo_team/workflow.py)"] + Plan[Planner
gemini-2.5-pro] --> Research[Researcher
gemini-2.5-flash] + Research --> Impl[Implementer
gemini-2.5-pro] + Impl --> Review[Reviewer
gemini-2.5-pro] + end + subgraph Boundary["Worker boundary (maf_starter/worker_boundary.py)"] + WB[WorkerBoundary
async dispatch, run_id, status polling] + end + subgraph Telemetry["Telemetry (in progress, PR #12)"] + T[emit_failure_telemetry
structured JSON on stderr] + end + subgraph Critic["Peer critic gate (in progress, PR #14)"] + C[Deterministic pattern-scan
engine] + end + subgraph Fallback["Provider fallback (maf_starter/provider_fallback.py)"] + F[Gemini -> Anthropic -> local CLI] + end + Manager --> Boundary + Impl --> Fallback + Fallback -.->|on failure| Telemetry + Review --> Critic + Critic -.->|gates| Manager +``` + + + +## Worker fan-out (landed on `main`) + +`entities/repo_team/workflow.py` wires the canonical `planning -> research -> implementation -> +review -> validation` sequence via `agent_framework_orchestrations.SequentialBuilder`. Each +specialist is built in `maf_starter/team_factory.py` with a distinct model tier. Long-running +executions are dispatched through `WorkerBoundary` (`maf_starter/worker_boundary.py`), which +returns a `run_id` immediately and exposes `pending` / `running` / `done` / `error:` +status polling instead of blocking HTTP ingress on the full execution path. + +## Telemetry boundary — in progress (PR #12) + +`main` today does not have a `maf_starter/telemetry.py` module. PR #12 +(`feat(28-02): structured JSON failure telemetry + CLI fallback size guards`) adds +`emit_failure_telemetry(event, **fields)` — a stdlib-only, never-raising function that writes +one flushed JSON line to stderr — wired into `provider_fallback.py`'s fallback middleware at +`provider_failed`, `fallback_step_failed`, `fallback_succeeded`, and `fallback_exhausted` +points, plus a 1MB CLI output/prompt size guard. Until merged, provider-fallback failures are +still caught (existing `except Exception` boundaries in `provider_fallback.py` and +`worker_boundary.py`) but not emitted as structured telemetry. + +## Critic gate — in progress (PR #14) + +No critic module exists on `main` yet. PR #14 +(`feat(29-01): deterministic peer critic pattern-scan engine`) introduces a deterministic +pattern-scan reviewer intended to sit after the Reviewer specialist as an additional gate. +Until merged, review is limited to the LLM-based Reviewer agent's own assessment. + +## Provider routing and fallback (landed on `main`) + +`maf_starter/routing_policy.py` selects a model tier by task depth; `maf_starter/ +provider_fallback.py` retries across the Gemini API, optional Anthropic API, and local CLI +providers (`gemini.cmd`, `claude`, `codex.cmd`) on heuristic quota/rate-limit errors, recording +route-attempt history. + +## Approvals and bounded repo tools (landed on `main`) + +`maf_starter/tools.py` enforces repo-root path boundaries and blocks writes to sensitive +targets (e.g. `.env`). `maf_starter/approval_policy.py` classifies file operations and +validation commands so destructive or externally visible actions pause for operator approval +via the dashboard's approval surface. + + diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md new file mode 100644 index 0000000..f4f956a --- /dev/null +++ b/docs/wiki/Decisions.md @@ -0,0 +1,35 @@ +# Decisions + +## ADR convention + +`docs/adr/README.md` establishes the convention (sequential numbering, Context/Decision/ +Consequences) but **no numbered ADR files exist in the repo yet**. Decisions to date live in +`.planning/phases/` plan/summary pairs instead. + +## Phase history (`.planning/phases/`, this repo's own GSD project) + +| Phase | Topic | +|---|---| +| 01 | Workspace and durable run foundation | +| 02 | Manager-led orchestration core | +| 03 | Specialist delegation and routing visibility | +| 04 | Autonomous repo execution and validation guardrails | +| 05 | Polished operator workbench | +| 06 | API boundary and control-plane contract | +| 07 | Worker boundary | + +See each `.planning/phases//*-SUMMARY.md` for the detailed record. + +## Open decisions tracked in this Phase 36 refresh + +- **PR #11** (`feat/phase-26-coverage-gates`) — ratchets CI to a pytest-cov branch-coverage + gate; open, not yet merged. +- **PR #12** (`feat/phase-28-fault-injection`) — structured JSON failure telemetry + CLI + fallback size guards; open, not yet merged. +- **PR #13** (`ci/phase-31-workflow-hardening`) — pins third-party GitHub Actions to commit + SHAs and least-privilege permissions; open, not yet merged. +- **PR #14** (`feat/phase-29-peer-critic`) — deterministic peer critic pattern-scan engine; + open, not yet merged. See [Architecture](./Architecture.md) for the critic-gate design this + PR introduces. + + diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..c13663c --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,32 @@ +# autogen Wiki + +## Role in the CAS portfolio + +`autogen` is the **Execution plane** of the Coding-Autopilot-System three-plane model (Control +/ Execution / Governance). Built on Microsoft Agent Framework, it runs manager-led, +specialist-delegated engineering work against a real repository: planning, research, +implementation, review, and validation, with bounded repo tools and an approval gate for +destructive actions. + +| Plane | This repo's responsibility | +|---|---| +| Control | *(not this repo — see `gsd-orchestrator`)* | +| Execution | Manager-led worker fan-out, bounded repo tools, provider routing/fallback, run artifacts | +| Governance | *(not this repo — see `Promptimprover`, `cas-contracts`, `cas-evals`)* | + +## Quickstart + +- [README.md](../../README.md) — Quickstart, configuration reference, evidence posture +- [Architecture](./Architecture.md) — worker fan-out, telemetry boundary (in progress), critic gate (in progress) +- [Operations](./Operations.md) — verified run/test/CI commands +- [Decisions](./Decisions.md) — phase history and open PRs + +## Ecosystem links + +Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) org: +[gsd-orchestrator](https://github.com/Coding-Autopilot-System/gsd-orchestrator) (control plane) · +[Promptimprover](https://github.com/Coding-Autopilot-System/Promptimprover) (prompt governance) · +[cas-contracts](https://github.com/Coding-Autopilot-System/cas-contracts) (shared schemas) · +[cas-evals](https://github.com/Coding-Autopilot-System/cas-evals) (evidence gate) + + diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md new file mode 100644 index 0000000..fa043cc --- /dev/null +++ b/docs/wiki/Operations.md @@ -0,0 +1,46 @@ +# Operations + +## Setup + +```powershell +git clone https://github.com/Coding-Autopilot-System/autogen.git +Set-Location autogen +python -m venv .venv +.\.venv\Scripts\python.exe -m pip install -r requirements.txt +Copy-Item .env.example .env +``` + +## Run + +```powershell +.\.venv\Scripts\python.exe main.py providers +.\.venv\Scripts\python.exe main.py dashboard --host 127.0.0.1 --port 8000 +``` + +## Test + +```powershell +.\.venv\Scripts\python.exe -m pytest -q --tb=short +``` + +Contract-compatibility gate only (consumer-side check against the pinned `cas-contracts` v1.1 +release): + +```powershell +.\.venv\Scripts\python.exe -m pytest tests/test_contract_compatibility.py -q --tb=short +``` + +## CI (`.github/workflows/ci.yml`, matrix: ubuntu-latest + windows-latest, Python 3.12, 20-minute timeout) + +1. `actions/checkout@v7` +2. `actions/setup-python@v6` (Python 3.12, pip cache) +3. `pip install -r requirements.txt` +4. `pip check` — dependency consistency +5. **Contract compatibility** — `tests/test_contract_compatibility.py`, fails red on pinned-contract drift +6. **Run full test suite** — installs `pytest-cov`, runs `pytest --cov=. --cov-report=xml` (coverage is measured; no `--cov-fail-under` threshold is enforced on `main` yet — see [Architecture](./Architecture.md) and PR #11) +7. `python -m compileall autogen_starter autogen_dashboard maf_starter main.py -q` +8. `node --check autogen_dashboard/static/app.js` — legacy dashboard JS syntax check + +A separate `.github/workflows/codeql.yml` runs CodeQL analysis (badge in the root `README.md`). + +