Coding-Autopilot-System · OgeonX-Ai · Jul 8, 2026 · Jul 8, 2026
diff --git 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)
+
+<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->
diff --git a/docs/wiki/Architecture.md 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<br/>gemini-2.5-pro] --> Research[Researcher<br/>gemini-2.5-flash]
+        Research --> Impl[Implementer<br/>gemini-2.5-pro]
+        Impl --> Review[Reviewer<br/>gemini-2.5-pro]
+    end
+    subgraph Boundary["Worker boundary (maf_starter/worker_boundary.py)"]
+        WB[WorkerBoundary<br/>async dispatch, run_id, status polling]
+    end
+    subgraph Telemetry["Telemetry (in progress, PR #12)"]
+        T[emit_failure_telemetry<br/>structured JSON on stderr]
+    end
+    subgraph Critic["Peer critic gate (in progress, PR #14)"]
+        C[Deterministic pattern-scan<br/>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
+```
+
+<!-- codex:generate-image prompt="A factory floor with a manager robot dispatching four numbered worker robots (Planner, Researcher, Implementer, Reviewer) through a glass boundary wall; failed work items trigger a small telemetry beacon; a fifth robot with a magnifying glass (the critic) inspects finished work at a gate before it passes through; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
+
+## 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:<msg>`
+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.
+
+<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->
diff --git a/docs/wiki/Decisions.md 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/<NN-topic>/*-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.
+
+<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->
diff --git a/docs/wiki/Home.md 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)
+
+<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->
diff --git a/docs/wiki/Operations.md 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`).
+
+<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->