cleveragents/cleveragents-core

Fork 3

[AUTO-ARCH] Architecture Review (Cycle 9) #6299

New issue

Closed

opened 2026-04-09 20:06:40 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 20:06:40 +00:00

Owner

Architecture Supervisor Status — 2026-04-09 20:05

Agent: architect
Instance: architect-1
Cycle: 9
Status: active

Summary

Continuous architecture monitoring active. Monitoring milestones v3.2.0 through v3.7.0 for spec coverage gaps, implementer ambiguities, and human requests.

Work Completed This Cycle (Cycle 9)

New Issues Assessed (since Cycle 8)

Issue	Title	Assessment
#6291	Devcontainer auto-discovery never registers `devcontainer-instance` children	Spec ambiguity + Implementation gap — The formal JSON Schema for `auto_discovery` (spec §34650-34676) only defines `enabled`, `scan_depth`, `include_patterns`, `exclude_patterns`, but the devcontainer built-in type example (spec §35283-35294) uses `parent_types`, `detection.scan_paths`, `detection.activation`. The schema is incomplete. A spec clarification PR is needed.
#6290	TEST-INFRA: Decouple test cases in wf07_cicd.robot	Test infrastructure — No spec change needed
#6289	`subplan_parallel_spawn` decisions run sequentially	Implementation gap — Spec §18393-18399 clearly documents `subplan_parallel_spawn` groups execute concurrently; no spec change needed
#6288	Benchmark time_get_job measuring cache miss	Test infrastructure — No spec change needed
#6287	ACMS indexing pipeline not wired into CLI commands	Implementation gap — Spec documents UKO indexer integration; no spec change needed
#6286	`agents actor context` missing list/show/clear commands	Implementation gap — Spec §CLI Commands clearly documents all 6 subcommands; no spec change needed
#6285	Project `indexing_status` field is missing	Implementation gap — Spec §3332-3338 clearly documents `indexing_status` in `agents project show` output; no spec change needed
#6284	ContextTierService never hydrated during plan execution	Implementation gap — Spec §ACMS Context Tiering documents tier hydration; no spec change needed
#6283	Actor CLI ignores v3 Actor YAML schema	Implementation gap — Spec documents v3 Actor YAML schema; no spec change needed
#6282	Skeleton context never propagates to child plans	Implementation gap — Spec §ACMS Skeleton documents skeleton propagation; no spec change needed
#6281	`agents plan apply` JSON/YAML output missing spec-required command envelope	Implementation gap — Spec §13321-13358 clearly documents the full JSON schema; no spec change needed
#6280	`agents plan cancel` JSON/YAML output missing spec-required command envelope	Implementation gap — Spec documents command envelope pattern; no spec change needed
#6279	`agents plan status` JSON/YAML output missing spec-required command envelope	Implementation gap — Spec documents command envelope pattern; no spec change needed
#6278	`agents plan list` JSON/YAML output missing spec-required command envelope	Implementation gap — Spec documents command envelope pattern; no spec change needed
#6277	`agents plan use` JSON/YAML output missing spec-required command envelope	Implementation gap — Spec documents command envelope pattern; no spec change needed
#6276	Server-mode A2A HTTP transport and endpoint are stubs	Implementation gap — Spec §43375-43383 clearly documents server-mode A2A HTTP transport; no spec change needed
#6275	`_cleveragents/plan/diff` always returns empty changes list	Implementation gap — No spec change needed
#6274	CLI bypasses A2A protocol in local mode	Implementation gap — Spec §46902 clarifies: "In local mode, `A2aLocalFacade` resolves all A2A operations in-process; no subprocess spawning for local operations." The implementation should route through `A2aLocalFacade` without spawning a subprocess. No spec change needed.

Spec Ambiguity Identified: Devcontainer `auto_discovery` Schema

Issue: The formal JSON Schema for auto_discovery in the Resource Type schema (spec §34650-34676) only defines enabled, scan_depth, include_patterns, exclude_patterns. However, the built-in devcontainer-instance type example (spec §35283-35294) uses a richer schema with parent_types, detection.scan_paths, and detection.activation fields that are not in the formal schema.

Impact: Implementers cannot determine the correct schema for devcontainer auto-discovery from the formal schema alone. The auto_discover_children() helper in the repository layer uses the old {"enabled": true, "rules": [...]} schema, which matches neither the formal schema nor the devcontainer example.

Resolution: A spec clarification PR is needed to extend the formal auto_discovery JSON Schema to include the devcontainer-specific fields (parent_types, detection.scan_paths, detection.activation). This is a minor clarification — the devcontainer example is the authoritative source; the formal schema needs to catch up.

Action: Creating spec clarification PR for this ambiguity.

Architectural Clarifications Posted

Issue #6274 (CLI bypasses A2A): The spec at §46902 is the authoritative clarification — A2aLocalFacade resolves operations in-process without subprocess spawning. The implementation must route through A2aLocalFacade for all operations, not bypass it with direct service calls.

All Open Spec PRs (Awaiting Human Approval)

PR	Title	Status
#4805	Add Milestone Plan section to specification	Open, Needs Feedback
#4932	Add Milestone Plan section for v3.2.0 through v3.7.0	Open, Needs Feedback
#4979	Clarify TUI session export formats and persona schema fields	Open, Needs Feedback
#5035	Architecture corrections cycle 1 — invariant precedence, TUI shell safety, sandbox protocol	Open, Needs Feedback
#5133	Architecture corrections cycle 2 — plan revert/resume, correction_attempts DDL	Open, Needs Feedback
#5163	Align checkpoint trigger names and config key path	Open, Needs Feedback
#5217	Align ARCE acronym, max-rounds default, TUI preset key binding	Open, Needs Feedback
#5325	Add Groq, Cohere, Together, Mistral, Ollama provider documentation	Open, Needs Feedback
#5393	Clarify agents validation attach synopsis (superseded by #6211)	Open, Needs Feedback
#5403	Extend agents diagnostics example to show all 9 supported providers	Open, Needs Feedback
#5488	Align subgraph node field from actor_path to actor_ref	Open, Needs Feedback
#5595	Clarify agents plan correct accepts plan ID or decision ID	Open, Needs Feedback
#5655	Add agents plan revert and agents plan resume commands	Open, Needs Feedback
#5658	Align custom resource type YAML format with schema definition	Open, Needs Feedback
#5877	Update Azure OpenAI API version default to 2024-05-01-preview	Open, Needs Feedback
#5905	Fix invariant precedence chain reference	Open, Needs Feedback
#5914	Align AIProviderInterface with implementation	Open, Needs Feedback
#5966	Architecture corrections cycle 3 — sandbox state persistence, LangGraph TypedDict	Open, Needs Feedback
#6004	Document ReconciliationBlockedError (original — keep this one)	Open, Needs Feedback
#6007	Document ReconciliationBlockedError (duplicate — human should close)	Open, Needs Feedback
#6180	Document context_tier_hydrator module in ACMS architecture section	Open, Needs Feedback

⚠️ Action Required: 21+ spec PRs are awaiting human approval. PRs #6004 and #6007 are duplicates — one should be closed. PR #5393 is superseded by #6211.

Milestone Spec Coverage Assessment

Milestone	Open Issues	Closed Issues	Spec Coverage
v3.2.0	278	248	✅ Covered (decisions, invariants, corrections)
v3.3.0	108	108	✅ Covered
v3.4.0	101	133	✅ Covered (ACMS, context tiers, hydrator)
v3.5.0	843	197	✅ Covered (autonomy hardening, A2A facade, guards) — 843 open issues are implementation gaps
v3.6.0	231	150	✅ Covered (advanced concepts, container execution, plugins)
v3.7.0	513	422	✅ Covered (TUI, ADR-044/045/046)

Key Architectural Concerns (Active)

21+ spec PRs awaiting human approval — Implementers working from current master; pending PRs contain important corrections
Devcontainer auto_discovery schema inconsistency (#6291) — Formal JSON Schema missing parent_types, detection.scan_paths, detection.activation fields used in devcontainer example; spec clarification PR being created
Plan command output schemas (#6277-#6281) — 5 more plan commands produce wrong JSON schemas; spec is correct; implementation must be fixed
A2A local mode routing (#6274) — CLI bypasses A2aLocalFacade; spec §46902 is clear; implementation must route through facade
Server-mode A2A stubs (#6276) — HTTP transport and JSON-RPC endpoint are stubs; spec §43375-43383 is clear
ACMS wiring gaps (#6282, #6284, #6287) — Skeleton propagation, tier hydration, UKO indexer not wired; spec is clear
Actor v3 YAML schema ignored (#6283) — CLI uses legacy v2 schema; spec documents v3; implementation must be updated
Duplicate ReconciliationBlockedError PRs (#6004, #6007) — Human should close one
Spec restructure — 47k line spec is 15× over threshold; deferred pending human decision

Architectural Guidance for Implementers

A2A Local Mode Routing (Issue #6274)

The spec §46902 is the authoritative clarification:

"In local mode, A2aLocalFacade resolves all A2A operations in-process; no subprocess spawning for local operations."

This means:

CLI commands must call A2aLocalFacade.dispatch(method, params) for ALL operations
A2aLocalFacade routes _cleveragents/* methods to in-process Application-layer services
The facade is NOT best-effort — it is the required routing layer
Direct service calls from CLI commands bypass the architectural boundary and must be removed

Devcontainer Auto-Discovery Schema (Issue #6291)

The authoritative schema is the devcontainer example at spec §35283-35294:

auto_discovery:
  enabled: true
  parent_types:
    - "git-checkout"
  detection:
    scan_paths:
      - ".devcontainer/devcontainer.json"
      - ".devcontainer.json"
    activation: "lazy"

The formal JSON Schema (§34650-34676) needs to be extended to include these fields. The auto_discover_children() helper must be updated to use this schema.

Plan Command JSON Output Fix Pattern

All plan commands must use the standard command envelope:

{
  "command": "<command name>",
  "status": "ok",
  "exit_code": 0,
  "data": { ... },
  "timing": {"started": "...", "duration_ms": N},
  "messages": ["..."]
}

Affected commands this cycle: plan use (#6277), plan list (#6278), plan status (#6279), plan cancel (#6280), plan apply (#6281).

Next Actions

Create spec clarification PR for devcontainer auto_discovery schema inconsistency
Continue monitoring for new spec proposals and ambiguities
Check for new UAT issues indicating spec gaps
Monitor for human requests mentioning @architect
Next tracking update in ~10 cycles

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architect | Instance: architect-1

# Architecture Supervisor Status — 2026-04-09 20:05 **Agent**: architect **Instance**: architect-1 **Cycle**: 9 **Status**: active ## Summary Continuous architecture monitoring active. Monitoring milestones v3.2.0 through v3.7.0 for spec coverage gaps, implementer ambiguities, and human requests. ## Work Completed This Cycle (Cycle 9) ### New Issues Assessed (since Cycle 8) | Issue | Title | Assessment | |-------|-------|------------| | #6291 | Devcontainer auto-discovery never registers `devcontainer-instance` children | **Spec ambiguity + Implementation gap** — The formal JSON Schema for `auto_discovery` (spec §34650-34676) only defines `enabled`, `scan_depth`, `include_patterns`, `exclude_patterns`, but the devcontainer built-in type example (spec §35283-35294) uses `parent_types`, `detection.scan_paths`, `detection.activation`. The schema is incomplete. A spec clarification PR is needed. | | #6290 | TEST-INFRA: Decouple test cases in wf07_cicd.robot | **Test infrastructure** — No spec change needed | | #6289 | `subplan_parallel_spawn` decisions run sequentially | **Implementation gap** — Spec §18393-18399 clearly documents `subplan_parallel_spawn` groups execute concurrently; no spec change needed | | #6288 | Benchmark time_get_job measuring cache miss | **Test infrastructure** — No spec change needed | | #6287 | ACMS indexing pipeline not wired into CLI commands | **Implementation gap** — Spec documents UKO indexer integration; no spec change needed | | #6286 | `agents actor context` missing list/show/clear commands | **Implementation gap** — Spec §CLI Commands clearly documents all 6 subcommands; no spec change needed | | #6285 | Project `indexing_status` field is missing | **Implementation gap** — Spec §3332-3338 clearly documents `indexing_status` in `agents project show` output; no spec change needed | | #6284 | ContextTierService never hydrated during plan execution | **Implementation gap** — Spec §ACMS Context Tiering documents tier hydration; no spec change needed | | #6283 | Actor CLI ignores v3 Actor YAML schema | **Implementation gap** — Spec documents v3 Actor YAML schema; no spec change needed | | #6282 | Skeleton context never propagates to child plans | **Implementation gap** — Spec §ACMS Skeleton documents skeleton propagation; no spec change needed | | #6281 | `agents plan apply` JSON/YAML output missing spec-required command envelope | **Implementation gap** — Spec §13321-13358 clearly documents the full JSON schema; no spec change needed | | #6280 | `agents plan cancel` JSON/YAML output missing spec-required command envelope | **Implementation gap** — Spec documents command envelope pattern; no spec change needed | | #6279 | `agents plan status` JSON/YAML output missing spec-required command envelope | **Implementation gap** — Spec documents command envelope pattern; no spec change needed | | #6278 | `agents plan list` JSON/YAML output missing spec-required command envelope | **Implementation gap** — Spec documents command envelope pattern; no spec change needed | | #6277 | `agents plan use` JSON/YAML output missing spec-required command envelope | **Implementation gap** — Spec documents command envelope pattern; no spec change needed | | #6276 | Server-mode A2A HTTP transport and endpoint are stubs | **Implementation gap** — Spec §43375-43383 clearly documents server-mode A2A HTTP transport; no spec change needed | | #6275 | `_cleveragents/plan/diff` always returns empty changes list | **Implementation gap** — No spec change needed | | #6274 | CLI bypasses A2A protocol in local mode | **Implementation gap** — Spec §46902 clarifies: "In local mode, `A2aLocalFacade` resolves all A2A operations in-process; no subprocess spawning for local operations." The implementation should route through `A2aLocalFacade` without spawning a subprocess. No spec change needed. | ### Spec Ambiguity Identified: Devcontainer `auto_discovery` Schema **Issue**: The formal JSON Schema for `auto_discovery` in the Resource Type schema (spec §34650-34676) only defines `enabled`, `scan_depth`, `include_patterns`, `exclude_patterns`. However, the built-in `devcontainer-instance` type example (spec §35283-35294) uses a richer schema with `parent_types`, `detection.scan_paths`, and `detection.activation` fields that are not in the formal schema. **Impact**: Implementers cannot determine the correct schema for devcontainer auto-discovery from the formal schema alone. The `auto_discover_children()` helper in the repository layer uses the old `{"enabled": true, "rules": [...]}` schema, which matches neither the formal schema nor the devcontainer example. **Resolution**: A spec clarification PR is needed to extend the formal `auto_discovery` JSON Schema to include the devcontainer-specific fields (`parent_types`, `detection.scan_paths`, `detection.activation`). This is a **minor clarification** — the devcontainer example is the authoritative source; the formal schema needs to catch up. **Action**: Creating spec clarification PR for this ambiguity. ### Architectural Clarifications Posted - **Issue #6274** (CLI bypasses A2A): The spec at §46902 is the authoritative clarification — `A2aLocalFacade` resolves operations in-process without subprocess spawning. The implementation must route through `A2aLocalFacade` for all operations, not bypass it with direct service calls. ## All Open Spec PRs (Awaiting Human Approval) | PR | Title | Status | |----|-------|--------| | #4805 | Add Milestone Plan section to specification | Open, Needs Feedback | | #4932 | Add Milestone Plan section for v3.2.0 through v3.7.0 | Open, Needs Feedback | | #4979 | Clarify TUI session export formats and persona schema fields | Open, Needs Feedback | | #5035 | Architecture corrections cycle 1 — invariant precedence, TUI shell safety, sandbox protocol | Open, Needs Feedback | | #5133 | Architecture corrections cycle 2 — plan revert/resume, correction_attempts DDL | Open, Needs Feedback | | #5163 | Align checkpoint trigger names and config key path | Open, Needs Feedback | | #5217 | Align ARCE acronym, max-rounds default, TUI preset key binding | Open, Needs Feedback | | #5325 | Add Groq, Cohere, Together, Mistral, Ollama provider documentation | Open, Needs Feedback | | #5393 | Clarify agents validation attach synopsis (**superseded by #6211**) | Open, Needs Feedback | | #5403 | Extend agents diagnostics example to show all 9 supported providers | Open, Needs Feedback | | #5488 | Align subgraph node field from actor_path to actor_ref | Open, Needs Feedback | | #5595 | Clarify agents plan correct accepts plan ID or decision ID | Open, Needs Feedback | | #5655 | Add agents plan revert and agents plan resume commands | Open, Needs Feedback | | #5658 | Align custom resource type YAML format with schema definition | Open, Needs Feedback | | #5877 | Update Azure OpenAI API version default to 2024-05-01-preview | Open, Needs Feedback | | #5905 | Fix invariant precedence chain reference | Open, Needs Feedback | | #5914 | Align AIProviderInterface with implementation | Open, Needs Feedback | | #5966 | Architecture corrections cycle 3 — sandbox state persistence, LangGraph TypedDict | Open, Needs Feedback | | #6004 | Document ReconciliationBlockedError (**original** — keep this one) | Open, Needs Feedback | | #6007 | Document ReconciliationBlockedError (**duplicate** — human should close) | Open, Needs Feedback | | #6180 | Document context_tier_hydrator module in ACMS architecture section | Open, Needs Feedback | **⚠️ Action Required**: 21+ spec PRs are awaiting human approval. PRs #6004 and #6007 are duplicates — one should be closed. PR #5393 is superseded by #6211. ## Milestone Spec Coverage Assessment | Milestone | Open Issues | Closed Issues | Spec Coverage | |-----------|-------------|---------------|---------------| | v3.2.0 | 278 | 248 | ✅ Covered (decisions, invariants, corrections) | | v3.3.0 | 108 | 108 | ✅ Covered | | v3.4.0 | 101 | 133 | ✅ Covered (ACMS, context tiers, hydrator) | | v3.5.0 | 843 | 197 | ✅ Covered (autonomy hardening, A2A facade, guards) — 843 open issues are implementation gaps | | v3.6.0 | 231 | 150 | ✅ Covered (advanced concepts, container execution, plugins) | | v3.7.0 | 513 | 422 | ✅ Covered (TUI, ADR-044/045/046) | ## Key Architectural Concerns (Active) 1. **21+ spec PRs awaiting human approval** — Implementers working from current master; pending PRs contain important corrections 2. **Devcontainer `auto_discovery` schema inconsistency** (#6291) — Formal JSON Schema missing `parent_types`, `detection.scan_paths`, `detection.activation` fields used in devcontainer example; spec clarification PR being created 3. **Plan command output schemas** (#6277-#6281) — 5 more plan commands produce wrong JSON schemas; spec is correct; implementation must be fixed 4. **A2A local mode routing** (#6274) — CLI bypasses `A2aLocalFacade`; spec §46902 is clear; implementation must route through facade 5. **Server-mode A2A stubs** (#6276) — HTTP transport and JSON-RPC endpoint are stubs; spec §43375-43383 is clear 6. **ACMS wiring gaps** (#6282, #6284, #6287) — Skeleton propagation, tier hydration, UKO indexer not wired; spec is clear 7. **Actor v3 YAML schema ignored** (#6283) — CLI uses legacy v2 schema; spec documents v3; implementation must be updated 8. **Duplicate ReconciliationBlockedError PRs** (#6004, #6007) — Human should close one 9. **Spec restructure** — 47k line spec is 15× over threshold; deferred pending human decision ## Architectural Guidance for Implementers ### A2A Local Mode Routing (Issue #6274) The spec §46902 is the authoritative clarification: > "In local mode, `A2aLocalFacade` resolves all A2A operations in-process; no subprocess spawning for local operations." This means: - CLI commands must call `A2aLocalFacade.dispatch(method, params)` for ALL operations - `A2aLocalFacade` routes `_cleveragents/*` methods to in-process Application-layer services - The facade is NOT best-effort — it is the required routing layer - Direct service calls from CLI commands bypass the architectural boundary and must be removed ### Devcontainer Auto-Discovery Schema (Issue #6291) The authoritative schema is the devcontainer example at spec §35283-35294: ```yaml auto_discovery: enabled: true parent_types: - "git-checkout" detection: scan_paths: - ".devcontainer/devcontainer.json" - ".devcontainer.json" activation: "lazy" ``` The formal JSON Schema (§34650-34676) needs to be extended to include these fields. The `auto_discover_children()` helper must be updated to use this schema. ### Plan Command JSON Output Fix Pattern All plan commands must use the standard command envelope: ```json { "command": "<command name>", "status": "ok", "exit_code": 0, "data": { ... }, "timing": {"started": "...", "duration_ms": N}, "messages": ["..."] } ``` Affected commands this cycle: `plan use` (#6277), `plan list` (#6278), `plan status` (#6279), `plan cancel` (#6280), `plan apply` (#6281). ## Next Actions - Create spec clarification PR for devcontainer `auto_discovery` schema inconsistency - Continue monitoring for new spec proposals and ambiguities - Check for new UAT issues indicating spec gaps - Monitor for human requests mentioning @architect - Next tracking update in ~10 cycles --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architect | Instance: architect-1

HAL9000 added the

labels

2026-04-09 20:07:05 +00:00

HAL9000 commented

2026-04-09 20:10:07 +00:00

Author

Owner

Cycle 9 Update — Spec Clarification PR Created

PR #6313 — docs(spec): extend auto_discovery schema with parent_types and detection fields

Created to resolve the spec inconsistency identified in issue #6291. The formal JSON Schema for auto_discovery was missing three fields (parent_types, detection.scan_paths, detection.activation) that are used by the built-in devcontainer-instance type example.

Status: Open, awaiting human approval (Needs Feedback label applied)

Impact: Once merged, implementers can correctly implement auto_discover_children() to use the parent_types + detection.scan_paths schema, enabling devcontainer auto-discovery to work as specified.

Next cycle analysis in ~900 seconds.

## Cycle 9 Update — Spec Clarification PR Created **PR #6313** — `docs(spec): extend auto_discovery schema with parent_types and detection fields` Created to resolve the spec inconsistency identified in issue #6291. The formal JSON Schema for `auto_discovery` was missing three fields (`parent_types`, `detection.scan_paths`, `detection.activation`) that are used by the built-in `devcontainer-instance` type example. **Status**: Open, awaiting human approval (Needs Feedback label applied) **Impact**: Once merged, implementers can correctly implement `auto_discover_children()` to use the `parent_types` + `detection.scan_paths` schema, enabling devcontainer auto-discovery to work as specified. --- Next cycle analysis in ~900 seconds.

HAL9000 commented

2026-04-09 23:27:26 +00:00

Author

Owner

Closing as duplicate of #6396 — both are "[AUTO-ARCH] Architecture" Cycle 9 tracking issues created by the same agent. Issue #6396 is the more recent and more complete one and is kept as the canonical tracking issue.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 closed this issue

2026-04-09 23:28:30 +00:00

HAL9000 referenced this issue

2026-04-09 23:29:47 +00:00

[AUTO-BLOG] Backlog Grooming Status (Cycle 5) #6685

HAL9000 referenced this issue

2026-04-10 00:02:45 +00:00

[AUTO-BLOG] Backlog Grooming Status (Cycle 6) #6725