Weekly A2UI Compliance Report (2026-08-25)

[github-actions]

Weekly Compliance Audit Report (2026-08-25)

Summary

This comprehensive weekly compliance audit evaluates repository health across the 8 production codebases of the A2UI project against language-agnostic module blueprints, documentation consistency, and test assertion quality.

Key Audit Findings:

1. Blueprint Compliance & Spec Drift: All 8 production codebase blueprints (codebase.blueprint.md) currently have module_blueprint_commit: null and empty implemented_features: [] lists. The underlying module blueprints (a2ui_agent, a2ui_core, and a2ui_framework_adapter) have evolved with key specification updates (e.g. conformance test reorganization #2250, agent API refinement #1990, core updates #1991, and SDD introduction #1768), leaving all codebases tracked as 1–2 commits behind their module specifications. Furthermore, renderers/flutter remains a planned stub with no framework adapter implementation.
2. Code & Documentation Synchronization: Several broken internal documentation links exist in docs/public/concepts/ pointing to non-existent JSON catalog paths. In swift/core, the codebase blueprint references ./scripts/fix_format.sh which does not exist in the filesystem, and no localized README.md is present in swift/core/.
3. Test Quality & Assertion Strength: High assertion volumes are present across TypeScript, Python, and Swift test suites, but a significant number of weak assertions (e.g., expect(...).toBeTruthy(), assert ... is not None, #expect(... != nil)) exist in test files such as test_specification_roundtrip.py, test_node_graph.py, and Angular/React component explorer tests without asserting deep payload structure or property invariants.

---

Recommendations

1. P0: Pin Module Blueprint Commits & Populate Implemented Features across All 8 Codebases

   • Update module_blueprint_commit in blueprints/codebases/**/codebase.blueprint.md for all 8 codebases to their respective latest commits (b54a0e87 for a2ui_agent, 00979551 for a2ui_core, and 71a2d7d7 for a2ui_framework_adapter).
   • Populate implemented_features lists with actual supported features (e.g. direct_json, express, data_binding, message_processor, catalog_validation).

2. P1: Fix Broken Relative Documentation Links in Concepts & Glossary

   • Fix broken links in docs/public/concepts/components.md and docs/public/concepts/glossary.md referencing ../specification/v0_9_1/catalogs/basic/catalog.json and ../specification/v1_0/catalogs/basic/catalog.json to point to valid schema definitions in specification/.

3. P1: Remediate Swift Core Blueprint Configuration & Add Localized Documentation

   • Create swift/core/scripts/fix_format.sh or update swift/core/codebase.blueprint.md lint/format commands to reference valid project formatting scripts.
   • Add a localized swift/core/README.md providing architectural context and Swift Package Manager build/test instructions.

4. P2: Strengthen Weak Assertions Across Python, Swift, and Renderer Test Suites

   • Replace generic assert is not None checks in agent_sdks/python/a2ui_agent/tests/test_specification_roundtrip.py and agent_sdks/python/a2ui_core/tests/test_node_graph.py with structural assertions on component hierarchy and payload fields.
   • Replace superficial expect(element).toBeTruthy() / #expect(x != nil) assertions in renderers/angular, renderers/react, and swift/core test suites with explicit DOM attribute and model state verifications.

5. P2: Bootstrap Flutter Framework Adapter Implementation

   • Implement the planned Flutter framework adapter under renderers/flutter to satisfy a2ui_framework_adapter.blueprint.md or integrate the existing Flutter samples/client bindings into the production renderer architecture.

---

Codebase Blueprint Compliance Audit

Summary Status

Codebase Implementation	Associated Module	Status	Commits Behind	Current Commit	Latest Commit
agent_sdks/python/a2ui_agent	a2ui_agent	🟡 Out of Date	2	null	b54a0e87
agent_sdks/python/a2ui_core	a2ui_core	🟡 Out of Date	2	null	00979551
renderers/angular	a2ui_framework_adapter	🟡 Out of Date	1	null	71a2d7d7
renderers/flutter	a2ui_framework_adapter	🟡 Out of Date	1	null	71a2d7d7
renderers/lit	a2ui_framework_adapter	🟡 Out of Date	1	null	71a2d7d7
renderers/react	a2ui_framework_adapter	🟡 Out of Date	1	null	71a2d7d7
renderers/web_core	a2ui_core	🟡 Out of Date	2	null	00979551
swift/core	a2ui_core	🟡 Out of Date	2	null	00979551

Details by Codebase

📦 agent_sdks/python/a2ui_agent (🟡 Out of Date)

• Associated Module: a2ui_agent (blueprints/modules/a2ui_agent.blueprint.md)
• Current Pinned Commit: null
• Latest Module Commit: b54a0e872a2d90696508aff6797282ee316410ec
• Reason/Info: Codebase is behind by 2 commit(s) and has unpopulated implemented_features.
• Missing Commits/Specification Diffs:

  b54a0e8 refactor: move conformance test suites to root and organize by domain (#2250)
  0b7c113 Update a2ui_agent blueprint with refined APIs (#1990)
  

• Implemented Features Status: Frontmatter lists implemented_features: []. Actual codebase implements DirectJson, Express, Elemental, Atom, A2uiSchemaManager, and A2uiRequestProcessor.

📦 agent_sdks/python/a2ui_core (🟡 Out of Date)

• Associated Module: a2ui_core (blueprints/modules/a2ui_core.blueprint.md)
• Current Pinned Commit: null
• Latest Module Commit: 0097955129136724b67fb1b2e4e42e32e3be999a
• Reason/Info: Codebase is behind by 2 commit(s) and has unpopulated implemented_features.
• Missing Commits/Specification Diffs:

  0097955 Update a2ui-core blueprint (#1991)
  71a2d7d feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)
  

• Implemented Features Status: Frontmatter lists implemented_features: []. Actual codebase implements Catalog, ComponentModel, DataModel, SurfaceModel, MessageProcessor, GenericBinder, and CatalogSchemaValidator.

📦 renderers/angular (🟡 Out of Date)

• Associated Module: a2ui_framework_adapter (blueprints/modules/a2ui_framework_adapter.blueprint.md)
• Current Pinned Commit: null
• Latest Module Commit: 71a2d7d71a7d89d66359a0d1f4f4b6338c5196ca
• Reason/Info: Codebase is behind by 1 commit(s) and has unpopulated implemented_features.
• Missing Commits/Specification Diffs:

  71a2d7d feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)
  

• Implemented Features Status: Frontmatter lists implemented_features: []. Actual codebase implements Angular signal-based reactive components (v0_8 and v0_9), A2uiRendererService, and ComponentBinderService.

📦 renderers/flutter (🟡 Out of Date)

• Associated Module: a2ui_framework_adapter (blueprints/modules/a2ui_framework_adapter.blueprint.md)
• Current Pinned Commit: null
• Latest Module Commit: 71a2d7d71a7d89d66359a0d1f4f4b6338c5196ca
• Reason/Info: Codebase is behind by 1 commit(s). Codebase is currently an unbootstrapped stub containing only a README.md.
• Missing Commits/Specification Diffs:

  71a2d7d feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)
  

• Implemented Features Status: implemented_features: []. Planned renderer mapping A2UI schemas into Flutter widget trees.

📦 renderers/lit (🟡 Out of Date)

• Associated Module: a2ui_framework_adapter (blueprints/modules/a2ui_framework_adapter.blueprint.md)
• Current Pinned Commit: null
• Latest Module Commit: 71a2d7d71a7d89d66359a0d1f4f4b6338c5196ca
• Reason/Info: Codebase is behind by 1 commit(s) and has unpopulated implemented_features.
• Missing Commits/Specification Diffs:

  71a2d7d feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)
  

• Implemented Features Status: Frontmatter lists implemented_features: []. Actual codebase implements A2uiLitElement, A2uiController, BasicCatalogA2uiLitElement, and v0.8/v0.9 component catalogs.

📦 renderers/react (🟡 Out of Date)

• Associated Module: a2ui_framework_adapter (blueprints/modules/a2ui_framework_adapter.blueprint.md)
• Current Pinned Commit: null
• Latest Module Commit: 71a2d7d71a7d89d66359a0d1f4f4b6338c5196ca
• Reason/Info: Codebase is behind by 1 commit(s) and has unpopulated implemented_features.
• Missing Commits/Specification Diffs:

  71a2d7d feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)
  

• Implemented Features Status: Frontmatter lists implemented_features: []. Actual codebase implements A2uiSurface, A2uiNodeSurface, useA2UI, A2UIProvider, and v0.8/v0.9 React component catalogs.

📦 renderers/web_core (🟡 Out of Date)

• Associated Module: a2ui_core (blueprints/modules/a2ui_core.blueprint.md)
• Current Pinned Commit: null
• Latest Module Commit: 0097955129136724b67fb1b2e4e42e32e3be999a
• Reason/Info: Codebase is behind by 2 commit(s) and has unpopulated implemented_features.
• Missing Commits/Specification Diffs:

  0097955 Update a2ui-core blueprint (#1991)
  71a2d7d feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)
  

• Implemented Features Status: Frontmatter lists implemented_features: []. Actual codebase implements @preact/signals-core reactive state (SurfaceModel, ComponentModel, DataModel), MessageProcessor, GenericBinder, and BasicCatalog.

📦 swift/core (🟡 Out of Date)

• Associated Module: a2ui_core (blueprints/modules/a2ui_core.blueprint.md)
• Current Pinned Commit: null
• Latest Module Commit: 0097955129136724b67fb1b2e4e42e32e3be999a
• Reason/Info: Codebase is behind by 2 commit(s) and has unpopulated implemented_features.
• Missing Commits/Specification Diffs:

  0097955 Update a2ui-core blueprint (#1991)
  71a2d7d feat: introduce Spec-Driven Development (SDD) blueprints, skills, and codebase metadata (#1768)
  

• Implemented Features Status: Frontmatter lists implemented_features: []. Actual codebase implements A2UICore models, SurfaceViewModel, MessageProcessor, A2UIJSON schema registry, and BasicCatalog functions.

---

Code & Documentation Sync Audit

Summary Status

Component / Area	Status	Key Issues / Drift Found
docs/public/concepts/	⚠️ Drift Detected	Broken links referencing non-existent JSON catalog paths (v0_9_1 / v1_0).
swift/core	⚠️ Drift Detected	Missing localized README.md; blueprint references missing ./scripts/fix_format.sh.
renderers/flutter	⚠️ Incomplete	README.md documents external packages (genui), but internal implementation is unbootstrapped.
agent_sdks/python/a2ui_agent	🟢 In Sync	README.md and module architecture accurately describe parser/prompt/schema layers.
agent_sdks/python/a2ui_core	🟢 In Sync	README.md matches pyproject.toml and core data models.
renderers/angular	🟢 In Sync	README.md and package.json align with Angular Signals architecture.
renderers/lit	🟢 In Sync	README.md installation and component registration align with package exports.
renderers/react	🟢 In Sync	README.md examples align with v0_8 and v0_9 component APIs.
renderers/web_core	🟢 In Sync	README.md accurately describes @preact/signals-core state model and protocol processor.

Detailed Findings

1. Broken Relative Links in Conceptual Documentation:

   • docs/public/concepts/components.md:L42: Link [Basic Catalog](../specification/v0_9_1/catalogs/basic/catalog.json) points to a missing file path (docs/public/specification/v0_9_1/catalogs/basic/catalog.json).
   • docs/public/concepts/glossary.md:L18, L54, L112: Multiple links referencing ../specification/v1_0/catalogs/basic/catalog.json and ../specification/v0_9/json/common_types.json target non-existent file paths.

2. Missing Script & Local README in Swift Core:

   • blueprints/codebases/swift/core/codebase.blueprint.md:L7-L8: Configures lint_command: './scripts/fix_format.sh --check' and format_command: './scripts/fix_format.sh', but swift/core/scripts/ does not exist.
   • swift/core/: No localized README.md exists within the swift/core package root (only top-level swift/README.md exists).

3. Flutter Renderer Documentation vs Implementation:

   • renderers/flutter/README.md: Describes Flutter Gen UI SDK and links to external pub.dev packages, while blueprints/codebases/renderers/flutter/codebase.blueprint.md lists local commands (flutter test, flutter analyze) that cannot execute in the absence of a pubspec.yaml in that directory.

---

Test Quality & Assertions Audit

Summary Status

Target Package / Test Suite	Assertion Quality Score	Primary Weaknesses
agent_sdks/python/a2ui_agent	⚠️ Moderate (26 weak assertions)	assert is not None on roundtrip recompiled objects without deep payload verification.
agent_sdks/python/a2ui_core	⚠️ Moderate (30 weak assertions)	assert root_node is not None and assert schema is not None without validating properties.
renderers/angular	⚠️ Low (197 weak assertions)	High volume of expect(...).toBeTruthy() without inspecting rendered DOM structure.
renderers/react	⚠️ Moderate (46 weak assertions)	expect(...).toBeTruthy() used in explorer sidebar and flight status tests.
renderers/lit	⚠️ Moderate (24 weak assertions)	expect(...).toBeDefined() and expect(...).toBeTruthy() in smoke and navigation tests.
renderers/web_core	🟢 High (0 weak assertions)	Strict deep equality and behavioral signal tests.
swift/core	⚠️ Moderate (22 weak assertions)	Extensive use of #expect(x != nil) rather than verifying unwrapped instance state.
renderers/flutter	⚪ N/A (0 test files)	No local test suite implemented.

Detailed Findings

1. Python Agent SDK (agent_sdks/python/a2ui_agent):

   • agent_sdks/python/a2ui_agent/tests/test_specification_roundtrip.py:L123, L133, L143:

     assert recompiled is not None

     Issue: Fails to assert semantic JSON equality between the original specification payload and the recompiled output.
   • agent_sdks/python/a2ui_agent/tests/test_prompt_examples.py:L134:

     assert parsed is not None, f"Atom Example {i+1} returned None payload"

     Issue: Does not check component ID validity, child bindings, or event map structures.

2. Python Core SDK (agent_sdks/python/a2ui_core):

   • agent_sdks/python/a2ui_core/tests/test_node_graph.py:L155, L180, L221, L270, L321, L360, L383, L428, L581, L616:

     assert root_node is not None

     Issue: Node graph tests repeatedly verify object presence without checking child counts, node relationships, or data binding reactivity.
   • agent_sdks/python/a2ui_core/tests/test_accessibility.py:L78:

     assert comp.accessibility is not None

     Issue: Omits assertions verifying role, label, or live_region attribute values.

3. Angular Renderer (renderers/angular):

   • renderers/angular/a2ui_explorer/src/app/app.spec.ts:L35, L60, L68:

     expect(app).toBeTruthy();
     expect(collapseBtn).toBeTruthy();
     expect(expandBtn).toBeTruthy();

     Issue: Tests only check component instance truthiness rather than verifying that button click events properly mutate sidebar collapse state.

4. React Renderer (renderers/react):

   • renderers/react/a2ui_explorer/tests/v0_9/01_flight-status.test.tsx:L53:

     expect(iconInnerEl).toBeTruthy();

     Issue: Does not assert icon name, SVG class name, or accessibility label.

5. Swift Core SDK (swift/core):

   • swift/core/Tests/A2UICoreTests/MessageProcessorTests.swift:L45, L82, L118:

     #expect(processor.surfaceGroupModel.surfacesMap["s1"] != nil)
     #expect(surface != nil)

     Issue: Verifies dictionary key existence but does not validate surface component hierarchy or initial data model state.

---

Generated automatically by the A2UI Compliance Auditor.

[gspencergoog]

🤖 Automated remediation triggered! Created PR (#2421) on branch remediation/issue-2391-2 to address recommendation 2.