Baike.dev
Log in
Back to tool/Back to issues
#2666·a2ui

Weekly A2UI Compliance Report (2026-09-15)

Author: github-actions[bot]Created Sep 15, 2026Updated Sep 15, 2026
Labelscomponent: specificationstatus: needs reviewstatus: needs-triage

Spec-Driven Development Compliance and Quality Audit Report (2026-09-15)

Summary

This report provides a comprehensive static compliance, documentation synchronization, and test quality audit for the A2UI repository across all 8 production codebases and 1 planned implementation. The audit evaluates alignment against Spec-Driven Development (SDD) module blueprints (blueprints/modules/), public architectural specifications (specification/ and docs/), and rigorous software verification standards.

Overall, the repository demonstrates a mature multi-platform architecture implementing the A2UI v0.9 protocol across Python, TypeScript/Web (React, Angular, Lit, Web Core), and Apple Swift ecosystems. However, significant governance and quality gaps remain. Most notably, all 8 production codebases have unpinned module blueprint commits (module_blueprint_commit: null) and have not declared their supported feature sets in implemented_features, causing all codebases to be flagged as out-of-date. Furthermore, architectural drift exists in the agent SDK (missing CatalogTransformer abstractions and high-level application facade) and core SDKs (non-normative package naming in Python and unreleased bidirectional RPC modules).

Documentation and test quality audits reveal localized drift: package installation errors in renderers/web_core/README.md (invalid Yarn syntax), docstring parameter mismatches in Python inference parsers, and widespread reliance on shallow truthy/non-null assertions across UI renderer test suites (specifically Angular with 192 shallow assertions, React with 42, and SwiftUI component render tests). Remediation actions are prioritized below to restore spec-driven traceability, sync documentation, and elevate behavioral assertion quality.

Recommendations

  1. P0: Pin Module Blueprint Commits and Declare Implemented Features

    • Update module_blueprint_commit in all 9 codebase.blueprint.md files (blueprints/codebases/**/codebase.blueprint.md) to point to the latest module specification commits.
    • Populate implemented_features across all codebases to reflect actually implemented modules (e.g. direct_json, express, adk, a2a in agent_sdks/python/a2ui_agent; reactive signals and data context in agent_sdks/python/a2ui_core and renderers/web_core). Copy this prompt to implement this recommendation:
    markdown
    Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2666 and use the `a2ui-remediate-problem` skill to implement recommendation 1 described in the issue's Recommendation section.

  2. P1: Implement Missing Architectural Interfaces in Agent and Core SDKs

    • Implement CatalogTransformer, ComponentPruningTransformer, and FunctionPruningTransformer as specified in blueprints/modules/a2ui_agent.blueprint.md Section 3.A.
    • Implement high-level application facades A2uiGenerator and A2uiRequestProcessor in agent_sdks/python/a2ui_agent as specified in blueprints/modules/a2ui_agent.blueprint.md Section 3.F.
    • Align package naming in agent_sdks/python/a2ui_core with normative blueprint specifications (rename or alias validating to validation and rendering to resolution per blueprints/modules/a2ui_core.blueprint.md Section 2). Copy this prompt to implement this recommendation:
    markdown
    Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2666 and use the `a2ui-remediate-problem` skill to implement recommendation 2 described in the issue's Recommendation section.

  3. P1: Fix Deprecated and Invalid Setup Commands in Codebase READMEs

    • Fix renderers/web_core/README.md by replacing the invalid command yarn install @a2ui/web_core with yarn add @a2ui/web_core.
    • Update terminology in renderers/web_core/README.md to replace references to incoming "A2A messages" with standard "A2UI messages" in compliance with the canonical glossary (docs/public/concepts/glossary.md).
    • Fix agent_sdks/python/a2ui_agent/README.md which refers to non-existent src/a2ui/parser/streaming.py (relocated to src/a2ui/inference_formats/direct_json/streaming.py).
    • Fix agent_sdks/python/a2ui_core/README.md to include src/a2ui/core/validating in the core packages list and correct the location of Signal to a2ui.core.common.events. Copy this prompt to implement this recommendation:
    markdown
    Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2666 and use the `a2ui-remediate-problem` skill to implement recommendation 3 described in the issue's Recommendation section.

  4. P2: Resolve Inline Docstring and API Documentation Drift

    • Correct mismatched parameter names in Python agent SDK parsers:
      • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/atom/parser.py:L57 (has_format_content): fix docstring referencing complete instead of content.
      • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/atom/parser.py:L93 (compile): fix docstring referencing is_final instead of format_content.
      • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/elemental/parser.py:L44 & L80: fix complete and is_final parameter docstrings.
      • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/express/parser.py:L49: fix complete parameter docstring.
      • agent_sdks/python/a2ui_agent/src/a2ui/parser/parser.py:L27 & L81: fix complete and is_final parameter docstrings.
    • Fix JSDoc parameter documentation in renderers/web_core/src/v0_9/basic_catalog/expressions/expression_parser.ts:L138 (parseExpression). Copy this prompt to implement this recommendation:
    markdown
    Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2666 and use the `a2ui-remediate-problem` skill to implement recommendation 4 described in the issue's Recommendation section.

  5. P2: Strengthen Shallow Test Assertions Across UI Framework Test Suites

    • Refactor shallow assertions in renderers/angular (192 instances of expect(...).toBeTruthy()) to assert concrete DOM text content, attributes, and emitted component event payloads.
    • Refactor shallow assertions in renderers/react (42 instances of expect(...).toBeTruthy()) in a2ui_explorer/tests/v0_9/ to assert exact rendered attributes (e.g. img.src, button labels, card contents).
    • Refactor shallow assertions in renderers/lit (24 instances of expect(...).toBeTruthy()) in sidebar-and-navigation.test.ts to check element accessibility states and navigation targets.
    • Refactor SwiftUI component test suites (swift/swiftui/Tests/A2UISwiftUITests/A2UIAudioPlayerTests.swift:L67, A2UIChoicePickerTests.swift:L107, A2UIDateTimeInputTests.swift:L95, A2UIVideoTests.swift:L63, CatalogImplementationTests.swift:L38, A2UIListTests.swift:L78) by replacing #expect(rendered != nil) with checks on specific SwiftUI hierarchy traits or property bindings. Copy this prompt to implement this recommendation:
    markdown
    Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2666 and use the `a2ui-remediate-problem` skill to implement recommendation 5 described in the issue's Recommendation section.

  6. P3: Add Missing Boundary and Edge-Case Tests for Core Parsers and State Engines

    • Add failing test cases for malformed and truncated streaming chunks in agent_sdks/python/a2ui_agent/src/a2ui/parser/.
    • Add negative test cases for UAX #31 identifier validation in agent_sdks/python/a2ui_core/src/a2ui/core/validating/ testing disallowed characters, mathematical symbols, and emoji prefixes.
    • Add boundary expression evaluation tests in renderers/web_core/src/v0_9/basic_catalog/expressions/ covering division by zero, mismatched string delimiters, and deeply recursive expressions. Copy this prompt to implement this recommendation:
    markdown
    Read the A2UI issue at https://github.com/a2ui-project/a2ui/issues/2666 and use the `a2ui-remediate-problem` skill to implement recommendation 6 described in the issue's Recommendation section.

Codebase Blueprint Compliance Audit

Codebase Implementation Associated Module Status Commits Behind Current Commit Latest Commit
agent_sdks/python/a2ui_agent a2ui_agent Out of Date 4 null 919a04da
agent_sdks/python/a2ui_core a2ui_core Out of Date 5 null 96cc6f63
renderers/angular a2ui_framework_adapter Out of Date 1 null f821d716
renderers/flutter a2ui_framework_adapter Out of Date 1 null f821d716
renderers/lit a2ui_framework_adapter Out of Date 1 null f821d716
renderers/react a2ui_framework_adapter Out of Date 1 null f821d716
renderers/web_core a2ui_core Out of Date 5 null 96cc6f63
swift/core a2ui_core Out of Date 5 null 96cc6f63
swift/swiftui a2ui_framework_adapter Out of Date 1 null f821d716

Detailed Findings & Discrepancies

  • agent_sdks/python/a2ui_agent:

    • Commit Drift: module_blueprint_commit is null. Codebase is 4 commits behind latest module commit 919a04da (refactor(blueprint): remove BundledCatalogProvider from a2ui_agent blueprint).
    • Undeclared Implemented Features: Frontmatter only claims skill_generator, omitting active implementations of direct_json, express, atom, elemental, a2a_extension, adk_tools, and file_resolve.
    • Missing Module Blueprint Specifications: Module blueprint blueprints/modules/a2ui_agent.blueprint.md requires CatalogTransformer, ComponentPruningTransformer, and FunctionPruningTransformer (Section 3.A) as well as the high-level application facade A2uiGenerator and A2uiRequestProcessor (Section 3.F), none of which are implemented in src/a2ui/.

  • agent_sdks/python/a2ui_core:

    • Commit Drift: module_blueprint_commit is null. Codebase is 5 commits behind latest module commit 96cc6f63 (docs(blueprints): align a2ui_core blueprint with implemented core SDK APIs).
    • Undeclared Implemented Features: Frontmatter lists implemented_features: [], despite having functional implementations of state, validating, basic_catalog, processing, and rendering.
    • Architecture / Spec Drift: Module blueprint specifies that package names are normative (validation and resolution). The codebase implements validating and rendering instead. Additionally, the bidirectional RPC module (a2ui.core.rpc) defined in Section 3.D is completely absent.

  • renderers/angular:

    • Commit Drift: module_blueprint_commit is null. Codebase is 1 commit behind f821d716 (feat: introduce Spec-Driven Development blueprints).
    • Undeclared Implemented Features: Frontmatter lists implemented_features: []. The codebase contains complete Angular 19+ Signal-based adapters, A2uiRendererService, DynamicComponentLoader, and a2ui_explorer.

  • renderers/flutter:

    • Commit Drift: module_blueprint_commit is null. Codebase is 1 commit behind f821d716.
    • Planned Status: Codebase is a scaffolded placeholder directory containing only README.md. No production Dart/Flutter implementation exists yet.

  • renderers/lit:

    • Commit Drift: module_blueprint_commit is null. Codebase is 1 commit behind f821d716.
    • Undeclared Implemented Features: Frontmatter lists implemented_features: []. Codebase implements full Lit element wrappers, dynamic component registries, and a2ui_explorer.

  • renderers/react:

    • Commit Drift: module_blueprint_commit is null. Codebase is 1 commit behind f821d716.
    • Undeclared Implemented Features: Frontmatter lists implemented_features: []. Codebase implements complete React adapters for v0.8 and v0.9, context providers, and a2ui_explorer.

  • renderers/web_core:

    • Commit Drift: module_blueprint_commit is null. Codebase is 5 commits behind 96cc6f63.
    • Undeclared Implemented Features: Frontmatter lists implemented_features: []. Codebase implements state models (SurfaceGroupModel, DataModel), reactive signals via @preact/signals-core, and expression evaluation.
    • Missing Module Blueprint Specifications: Lacks the bidirectional RPC layer (a2ui.core.rpc) and explicit schema validation package specified in Section 3.C and 3.D of a2ui_core.blueprint.md.

  • swift/core:

    • Commit Drift: module_blueprint_commit is null. Codebase is 5 commits behind 96cc6f63.
    • Undeclared Implemented Features: Frontmatter lists implemented_features: []. Codebase provides A2UIJSON, A2UICore, and BasicCatalog.
    • Missing Module Blueprint Specifications: The bidirectional RPC layer (a2ui.core.rpc) is not implemented in Swift SPM targets.

  • swift/swiftui:

    • Commit Drift: module_blueprint_commit is null. Codebase is 1 commit behind f821d716.
    • Undeclared Implemented Features: Frontmatter lists implemented_features: []. Codebase implements SwiftUI ComponentNodeView, Surface, and BasicCatalogSwiftUI.
    • Missing Gallery App: Blueprint Section 7 specifies an interactive Gallery / Explorer app; unlike web renderers, swift/swiftui does not currently bundle an explorer application.

Code & Documentation Sync Audit

Directory Status Identified Issues
agent_sdks/python/a2ui_agent Needs Attention Outdated parser references in README; unlisted inference formats; 7 docstring parameter mismatches.
agent_sdks/python/a2ui_core Needs Attention Missing validating package in README; inaccurate Signal module location; package naming discrepancy.
renderers/web_core Needs Attention Invalid Yarn command in README (yarn install @a2ui/web_core); incorrect A2A vs A2UI terminology; JSDoc parameter mismatch.
renderers/angular Healthy Setup and execution commands verified against package.json and Angular CLI.
renderers/flutter ⚪ Scaffolded Placeholder README documenting planned status; no code to audit.
renderers/lit Healthy Usage examples, v0.9 imports, and build scripts match repository configuration.
renderers/react Healthy Comprehensive setup documentation; test and dev commands align with project files.
swift/core Healthy SPM targets, test commands, and basic catalog documentation match Package.swift.
swift/swiftui Healthy Component implementation guides and view builder patterns match Swift source code.

Detailed Findings

  • README Mismatches:

    • renderers/web_core/README.md:L34: Prescribes yarn install @a2ui/web_core. Under modern Yarn Berry, package installation requires yarn add @a2ui/web_core; running yarn install <package> causes command syntax errors.
    • renderers/web_core/README.md:L24: States that "MessageProcessor translates incoming A2A messages into state updates." This violates the canonical glossary (docs/public/concepts/glossary.md#a2ui-message), which reserves "A2A" for Agent-to-Agent protocol communication and designates UI JSON payloads as "A2UI messages".
    • agent_sdks/python/a2ui_agent/README.md:L21: Documents streaming.py under src/a2ui/parser/streaming.py. That file was relocated to src/a2ui/inference_formats/direct_json/streaming.py.
    • agent_sdks/python/a2ui_core/README.md:L42-L58: Documents Signal as part of 1. State Layer (src/a2ui/core/state). Signal is actually defined in agent_sdks/python/a2ui_core/src/a2ui/core/common/events.py. Additionally, package src/a2ui/core/validating is completely omitted from the README's core package directory listing.

  • Docstring / API Drift:

    • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/atom/parser.py:L57: Function has_format_content(content: str) documents parameter complete in its docstring instead of content.
    • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/atom/parser.py:L93: Method compile(format_content: str) documents parameter is_final in its docstring instead of format_content.
    • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/elemental/parser.py:L44: Function has_format_content(content: str) documents parameter complete in its docstring instead of content.
    • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/elemental/parser.py:L80: Method compile(format_content: str) documents parameter is_final in its docstring instead of format_content.
    • agent_sdks/python/a2ui_agent/src/a2ui/inference_formats/experimental/express/parser.py:L49: Function has_format_content(content: str) documents parameter complete in its docstring instead of content.
    • agent_sdks/python/a2ui_agent/src/a2ui/parser/parser.py:L27: Function has_format_content(content: str) documents parameter complete in its docstring instead of content.
    • agent_sdks/python/a2ui_agent/src/a2ui/parser/parser.py:L81: Method compile(format_content: str) documents parameter is_final in its docstring instead of format_content.
    • renderers/web_core/src/v0_9/basic_catalog/expressions/expression_parser.ts:L138: JSDoc for parseExpression(expr: string, depth = 0) lists @param depth without documenting default evaluation semantics or expression token constraints.

Test Quality & Assertions Audit

Suite / Module Status Observations
agent_sdks/python/a2ui_agent Needs Improvement 15+ weak assertions using self.assertIsNotNone on response parts without payload structure verification.
agent_sdks/python/a2ui_core Needs Improvement 14+ weak assertions checking assert surface is not None without validating child component graph nodes.
renderers/web_core Strong High-rigor test suite using native Node.js test runner with zero weak truthy assertions.
renderers/angular Weak 192 shallow assertions relying on toBeTruthy() / toBeDefined() across component tests and explorer specs.
renderers/lit Needs Improvement 24 shallow assertions checking button/element presence with .toBeTruthy() without attribute assertions.
renderers/react Needs Improvement 42 shallow assertions checking DOM nodes with .toBeTruthy() instead of verifying rendered attributes.
swift/core Strong Rigorous test suite using Swift Testing #expect; minor weak #expect(... != nil) on catalog queries.
swift/swiftui Needs Improvement 6 weak assertions checking #expect(rendered != nil) for basic catalog views without hierarchy checks.
renderers/flutter ⚪ Scaffolded No test suite present in planned codebase.

Detailed Findings

  • Weak Assertions:
    • agent_sdks/python/a2ui_agent/tests/elemental/test_integration.py:L70: self.assertIsNotNone(parts[0].a2ui_json) passes as long as an object exists, failing to assert that the generated A2UI payload contains valid createSurface or updateComponents envelope structures.
    • agent_sdks/python/a2ui_agent/tests/express/test_integration.py:L192, L200, L220: Repeatedly uses self.assertIsNotNone(expected_msg) without comparing the actual compiled output against expected JSON AST models.
    • agent_sdks/python/a2ui_core/tests/test_processing.py:L79, L102, L115: Uses assert surface is not None and assert comp is not None without checking component ID, typeName, or properties dictionary contents.
    • renderers/angular/a2ui_explorer/src/app/agent-stub.service.spec.ts:L58: expect(service).toBeTruthy() verifies service instantiation but omits any verification of mock message stream emission.
    • `renderers/angular/a2ui_explorer/src/app/te

Source: a2ui-project/a2ui

View original on GitHubView discussion on GitHub