latest refactoring
Some checks failed
validation / verify (push) Failing after 10s

This commit is contained in:
2026-10-06 20:22:37 +01:00
parent e94b2493e7
commit 7ee49ab352
414 changed files with 15768 additions and 3896 deletions

View File

@@ -67,7 +67,7 @@ These are carried from the decision log. The numbers refer to it.
### Module layout
New code only. The current modules stay untouched until [increment 9](#build-increments).
The engine sits in the KAB workflow-agent layout since 2026-10-06 (`.agents/plans/iter-03-kab-layout/`). The original pipeline was deleted the same day.
```
agents/ # framework-neutral role files (one per role)
@@ -75,6 +75,7 @@ agents/ # framework-neutral role files (one per rol
requirements-analyst.md decomposer.md product-selector.md diagrammer.md
describer.md design-advisor.md pillar-advisor.md iac-author.md
validator.md packager.md
partials/specialist-protocol.md
providers/
gcp.yaml # Cloud provider bundle
skills/
@@ -84,32 +85,41 @@ skills/
cloud-discovery/SKILL.md # our tooling Skills (Agent Skills spec compliant)
iac-validation/SKILL.md
app/
execution/
deliverables.py # DeliverableKind, PhaseId, DEPENDENCY_GRAPH, contracts
main.py # A2A server on A2A_PORT: /a2a, agent card, /health, /generate
a2a_server.py # maps A2A tasks <-> Executions and interrupts
agent.py # ExecutionEngine (start, resume, interaction) and open_assembly
card.py # A2A agent card, derived from the dependency graph
states/
execution_state.py # ExecutionState TypedDict
ledger.py # Ledger: Deliverable/Phase states, acceptance, Revision (pure, no I/O)
graph.py # LangGraph StateGraph: orchestrator turn, Specialist fan-out, interrupts
tools.py # Orchestrator and Specialist execution tools bound to the Ledger
state.py # ExecutionState TypedDict
recorder.py # records submissions, Approvals, Revisions, final files
agents/
nodes/
execution_nodes.py # orchestrator turn, Specialist task, await user, finalize
workflows/
deliverables.py # DeliverableKind, PhaseId, DEPENDENCY_GRAPH, contracts
execution_graph.py # LangGraph StateGraph wiring of the nodes
adk/
runtime.py # AgentRuntime protocol, RoleSpec, AgentTask, Outcome types
roles.py # loads agents/*.md into RoleSpec
adk_runtime.py # ADK LlmAgent + SkillToolset + LiteLlm implementation
fake_runtime.py # scripted implementation for tests (under app/ so eval can reuse it)
skills/
agent_skills.py # Agent Skills discovery and frontmatter validation
tools/
general/ # mermaid check, terraform fmt/validate (local)
cloud_read/ # terraform plan (local CLI, reads live state)
execution.py # Orchestrator and Specialist execution tools bound to the Ledger
toolkit.py # which tools each role gets
pillars.py # the design advisor's fan-out to pillar advisors
local.py # mermaid check, terraform fmt/validate/plan (local, tiered)
mcp.py # McpServerSpec, read-only allowlist, tier + permission metadata
providers.py # loads providers/<name>.yaml
a2a/
server.py # aiohttp A2A server on :8000, agent_card.json
executor.py # maps A2A tasks <-> Executions and interrupts
recorder.py # records submissions, Approvals, Revisions, status
checkpointing.py # memory | sqlite | postgres checkpointer
presentation.py # prompts and the /generate response
scripts/sync-vendored-skills.sh
```
### Deliverables and the dependency graph <a id="dependency-graph"></a>
`app/execution/deliverables.py` declares the graph as data. It is the only place Phases, Deliverables and Dependencies are listed.
`app/workflows/deliverables.py` declares the graph as data. It is the only place Phases, Deliverables and Dependencies are listed.
| Phase | Deliverable kind | Specialist role | Depends on | Tools (tier) |
|---|---|---|---|---|
@@ -131,7 +141,7 @@ scripts/sync-vendored-skills.sh
### The Ledger: acceptance and Revision rules
`app/execution/ledger.py` is a pure module. It holds every rule code owns, and the tests exercise it heavily.
`app/states/ledger.py` is a pure module. It holds every rule code owns, and the tests exercise it heavily.
- **Deliverable states:** `pending → in_progress → submitted`. Only a Revision goes backwards.
- **Phase states:** `open → awaiting_approval → approved`. A Phase becomes `awaiting_approval` when the Orchestrator calls `request_approval` with all its Deliverables `submitted`.
@@ -149,7 +159,7 @@ scripts/sync-vendored-skills.sh
### Execution graph (LangGraph)
`app/execution/graph.py` compiles once at startup with the configured checkpointer: `SqliteSaver` locally and in tests, `PostgresSaver` in production. The Execution id is the LangGraph `thread_id`.
`app/workflows/execution_graph.py` wires the nodes in `app/nodes/execution_nodes.py`, and the graph compiles once at startup with the configured checkpointer: `SqliteSaver` locally and in tests, `PostgresSaver` in production. The Execution id is the LangGraph `thread_id`.
**State (`ExecutionState`):**
- `execution_id`, `session_id`, `workflow_request`, `mode: "interactive" | "pre_approved"`, `allow_cloud_read: bool | None`
@@ -182,7 +192,7 @@ await_user ───────────────────────
- **Escalations:** end the Execution as `completed_with_warnings`.
- **`finalize`:** runs after Phase 4 is `approved`. It writes files to `deliverables/executions/{execution_id}/`: the Solution guide, every Deliverable as markdown, and attachments under `terraform/`. It then records completion.
**Orchestrator tools** (`app/execution/tools.py`):
**Orchestrator tools** (`app/tools/execution.py`):
| Tool | Effect |
|---|---|
@@ -200,7 +210,7 @@ await_user ───────────────────────
### Agent runtime interface
`app/agents/runtime.py`:
`app/adk/runtime.py`:
```python
class AgentRuntime(Protocol):
@@ -299,10 +309,10 @@ role_mcp_servers:
### Tools
- **General, local** (`app/tools/general/`):
- **General, local** (`app/tools/local.py`):
- `mermaid_check`: moved from `validation_tools.validate_mermaid_diagram`.
- `terraform_fmt` and `terraform_validate`: run the `terraform` CLI in a temp dir with `-backend=false`. There are no credentials, and the tool fails clearly if `terraform` is missing.
- **Cloud read, local** (`app/tools/cloud_read/`): `terraform_plan` needs ADC and `-lock=false`, and never runs `apply`.
- **Cloud read, local** (`app/tools/local.py`): `terraform_plan` needs ADC and `-lock=false`, and never runs `apply`.
- **Remote MCP servers** (`app/tools/mcp.py`): the Cloud provider's own hosted servers, declared in the provider bundle and used for both discovery and grounding. They replace `GCPEnvironmentScanner` (hand-written REST calls) and the hand-rolled JSON-RPC `DeveloperKnowledgeMCPClient`, including its offline fallback knowledge base and the `data`/`documents` bug from review candidate 02. Both are deleted in increment 9.
- `McpServerSpec(id, url, tier, allow, preview)` is framework-neutral. The ADK runtime maps each one to `McpToolset(StreamableHTTPConnectionParams(url, headers=auth), tool_filter=allow)`.
- **Read-only in depth.** Tools outside `allow` are never offered to any agent. At startup, a server whose `tools/list` reports an allowed tool with `readOnlyHint` not true fails to load, loudly. Operators should also run the agent's identity with only viewer roles, plus Google Cloud's control that blocks read-write MCP tool use and an IAM deny policy (`docs/operations/mcp-access.md`, written in increment 6).
@@ -314,7 +324,7 @@ role_mcp_servers:
### Interaction
**A2A** (`app/a2a/`), using `a2a-sdk>=0.3` on `aiohttp` :8000, with `agent_card.json` and `/.well-known/agent.json`:
**A2A** (`app/main.py`, `app/a2a_server.py`, `app/card.py`), using `a2a-sdk>=0.3` on `aiohttp` :8000, with `agent_card.json` and `/.well-known/agent.json`:
- **Task ↔ Execution:** an A2A task is an Execution (`task.id` = `execution_id`), and `context_id` is the Session.
- **Status updates:** `working` while nodes run.
- **`input-required`** at every `interrupt()`. The interrupt payload goes out as a `DataPart`, with a text rendering for plain clients.
@@ -332,7 +342,7 @@ The route switches to the new graph in increment 7, behind `AGENT_ENGINE=hierarc
### Recording
`app/execution/recorder.py` reuses `DatabaseManager` tables until candidate 03:
`app/recorder.py` reuses `DatabaseManager` tables until candidate 03:
- `workflow_executions`: one row per Execution, updated at each interrupt and at completion.
- `adk_artifacts`: one row per Deliverable submission. Rows for earlier Revisions stay as history.
- `orchestrator_review_logs`: one row per Ledger event. `review_status` holds the event type, `reviewer_agent` holds the role or `user`, and `feedback` holds the reason or feedback.
@@ -430,7 +440,7 @@ These are ordered, and each leaves the suite green. They are called *increments*
- The A2A server and executor, `agent_card.json`, `test_executor.py`.
- `/generate` behind `AGENT_ENGINE`, and the Dockerfile exposing :8000 and :8080.
8. **Evaluation:** scripted answers, template-heading scoring, and a real-model eval run with results recorded under `## Comments`. Proceed to 9 only when the pass rate meets the current harness threshold (≥ 80% per case).
9. **Cleanup** (carried over from the superseded spec):
9. **Cleanup** (carried over from the superseded spec). **Done differently on 2026-10-06:** the engine moved into the KAB layout and the original pipeline was then deleted. See `.agents/plans/iter-03-kab-layout/`. The list below is the plan as first written:
- **Delete:** `app/tools/gcp_scanner.py`, `app/tools/mcp_developer_knowledge.py` (replaced by remote MCP servers), `app/adk/`, `app/nodes/`, `app/states/`, `app/workflows/gcp_architecture_graph.py`, `app/skills/` (the loader and the 5 non-compliant Skills), `tests/test_graph_workflow.py`, the ADK and orchestrator tests in `tests/test_adk_architecture.py` (keeping the DB test as `tests/test_database.py`), and `test_adk_mcp_function_tools`.
- **Fix:** remove the unreachable duplicate `return` in `routes.py`. Rename `ADK_MAX_LOOP_ITERATIONS` → removed, and delete `ADK_ENABLE_ARTIFACT_STORE`.
- **Update:**
@@ -444,8 +454,8 @@ These are ordered, and each leaves the suite green. They are called *increments*
## Acceptance
- [ ] **Upstream parity:** a pre-approved evaluation run produces a Solution guide containing every heading of the upstream `output-template.md`, and all benchmark cases pass the threshold.
- [ ] **Single source for the workflow:** Phases, Deliverables and Dependencies are listed only in `app/execution/deliverables.py`, and card and manifest data is derived from it.
- [ ] **No framework types outside `app/agents/adk_runtime.py`:** `rg -n "google\.adk" app | grep -v adk_runtime.py` is empty. After increment 9, `rg -n "app\.adk|OrchestratorLoopAgent|compat" app eval tests` is empty.
- [ ] **Single source for the workflow:** Phases, Deliverables and Dependencies are listed only in `app/workflows/deliverables.py`, and card and manifest data is derived from it (`tests/test_workflow_manifest.py` checks `workflow.yaml`).
- [ ] **No framework types outside `app/adk/adk_runtime.py`:** `rg -n "google\.adk" app | grep -v adk_runtime.py` is empty. Nothing of the original pipeline remains: `rg -n "OrchestratorLoopAgent|compat|app\.legacy" app eval tests` is empty.
- [ ] **Vendored Skills unchanged:** they match the `81a31a6` checksums, and every Skill under `skills/` passes the frontmatter rules.
- [ ] **Approvals only by structured decision:** no path grants an Approval from free text (covered by tests).
- [ ] **Nothing changes cloud resources:** no tool can run `terraform apply`, a deploy or a script (`run_skill_script` absent from the tool lists). Cloud-read tools, MCP included, are unreachable without permission.
@@ -457,7 +467,7 @@ These are ordered, and each leaves the suite green. They are called *increments*
- **Specialists submitting without asking (D32).** A Specialist might submit without getting the user's conversational OK. Mitigation: role files require confirmation through `needs_input` before `submit_deliverable`, and the evaluation checks that submissions follow a question. If it's still observed, fall back to Approval per Deliverable (the Q31 alternative).
- **ADK Skills are Experimental.** The `SkillToolset` API may change. It's confined to `adk_runtime.py`, and Deep Agents is the planned second implementation.
- **Parallel Specialists and rate limits.** Fan-out multiplies concurrent model calls. Cap concurrency per Execution (default 4) in `graph.py`.
- **Parallel Specialists and rate limits.** Fan-out multiplies concurrent model calls. Cap concurrency per Execution (default 4) in `app/nodes/execution_nodes.py` (not built; `.agents/plans/iter-04-learning-and-skills/` step 5).
- **Upstream Skill drift.** Upstream edits may assume a different workflow. Re-sync only through the script, and review the diff against `agents/*.md` and `deliverables.py`.
- **Two frameworks in one process.** LangGraph and ADK both manage async state. Keep ADK sessions in memory per run, and never put ADK objects in graph state.
- **Remote MCP server availability and drift.** Several servers are Preview (Asset Inventory, Network Intelligence, Billing), each needs its product API enabled in the user's project, and tool sets can change. Mitigations:
@@ -469,6 +479,8 @@ These are ordered, and each leaves the suite green. They are called *increments*
## Comments
The dated entries below are history and keep the module paths of their day. Translate them with the table in `.agents/plans/README.md`.
### 2026-09-15 · Increment 1: environment and baseline
**Environment**