Weekly A2UI Compliance Report (2026-08-07)

## Summary

The weekly compliance audit was conducted across all eight production codebases in the A2UI repository (`agent_sdks/python/a2ui_agent`, `agent_sdks/python/a2ui_core`, `renderers/angular`, `renderers/flutter`, `renderers/lit`, `renderers/react`, `renderers/web_core`, and `swift/core`). The audit evaluated codebase blueprint compliance, synchronization between code and documentation, and test suite quality across SDKs and renderers.

Overall, all eight codebases are currently flagged as out-of-date regarding pinned blueprint commit hashes. Documentation drift was identified in renderer READMEs and SDK docstrings where setup commands and API signatures require updates. Test quality checks revealed instances of weak assertions in several test suites, where object presence or truthiness is checked rather than structural correctness or detailed property value assertions.

## Recommendations

1. **P0**: **Update Pinned Blueprint Commits**: Update pinned commit hashes across all 8 codebase blueprints (`blueprints/codebases/*`) to align with latest module specifications.
2. **P1**: **Strengthen Test Assertions in Python SDKs and Web Renderers**: Replace generic existence checks (e.g. `assert parsed is not None`, `expect(btn).toBeTruthy()`) in `agent_sdks/python/a2ui_agent/tests/test_prompt_examples.py:L134` and `renderers/angular/a2ui_explorer/src/app/tests/v0_8/00_simple-login-form.spec.ts:L52` with exact value and structural payload assertions.
3. **P1**: **Synchronize Codebase READMEs**: Update build, test, and dependency setup instructions in codebase READMEs (`renderers/angular/README.md`, `renderers/react/README.md`, `agent_sdks/python/a2ui_agent/README.md`) to reflect current CLI parameters and entrypoints.
4. **P2**: **Add Swift Core README**: Create a comprehensive `README.md` in `swift/core/` detailing package setup, architecture, and test invocation.

> 🤖 **Automated Remediation**: Comment `/fix ` (e.g., `/fix 1`) on this issue to have an agent create a draft PR for that recommendation.

## 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 | 0 | `null` | `unknown` |
| `agent_sdks/python/a2ui_core` | `a2ui_core` | 🟡 Out of Date | 0 | `null` | `unknown` |
| `renderers/angular` | `a2ui_framework_adapter` | 🟡 Out of Date | 0 | `null` | `unknown` |
| `renderers/flutter` | `a2ui_framework_adapter` | 🟡 Out of Date | 0 | `null` | `unknown` |
| `renderers/lit` | `a2ui_framework_adapter` | 🟡 Out of Date | 0 | `null` | `unknown` |
| `renderers/react` | `a2ui_framework_adapter` | 🟡 Out of Date | 0 | `null` | `unknown` |
| `renderers/web_core` | `a2ui_core` | 🟡 Out of Date | 0 | `null` | `unknown` |
| `swift/core` | `a2ui_core` | 🟡 Out of Date | 0 | `null` | `unknown` |

### Detailed Findings & Discrepancies

- **`agent_sdks/python/a2ui_agent`**: Pinned commit in codebase blueprint is `null`. Needs baselining against module blueprint `a2ui_agent.blueprint.md`.
- **`agent_sdks/python/a2ui_core`**: Pinned commit in codebase blueprint is `null`. Needs baselining against module blueprint `a2ui_core.blueprint.md`.
- **`renderers/angular`**: Pinned commit in codebase blueprint is `null`. Needs baselining against module blueprint `a2ui_framework_adapter.blueprint.md`.
- **`renderers/flutter`**: Pinned commit in codebase blueprint is `null`. Needs baselining against module blueprint `a2ui_framework_adapter.blueprint.md`.
- **`renderers/lit`**: Pinned commit in codebase blueprint is `null`. Needs baselining against module blueprint `a2ui_framework_adapter.blueprint.md`.
- **`renderers/react`**: Pinned commit in codebase blueprint is `null`. Needs baselining against module blueprint `a2ui_framework_adapter.blueprint.md`.
- **`renderers/web_core`**: Pinned commit in codebase blueprint is `null`. Needs baselining against module blueprint `a2ui_core.blueprint.md`.
- **`swift/core`**: Pinned commit in codebase blueprint is `null`. Missing codebase README and pinned commit baselining against `a2ui_core.blueprint.md`.

## Code & Documentation Sync Audit

| Directory | Status | Identified Issues |
|---|---|---|
| `agent_sdks/python/a2ui_agent` | 🟡 Drift Detected | Minor docstring parameter naming mismatches in transport layer |
| `agent_sdks/python/a2ui_core` | 🟢 Up to Date | Aligned with specification docs |
| `renderers/angular` | 🟡 Drift Detected | README build flags out of sync with Angular v19 CLI |
| `renderers/flutter` | 🟢 Up to Date | Aligned with specification docs |
| `renderers/lit` | 🟡 Drift Detected | Outdated package import paths in user guide |
| `renderers/react` | 🟡 Drift Detected | Component prop table in README missing recent event handler props |
| `renderers/web_core` | 🟢 Up to Date | Aligned with specification docs |
| `swift/core` | 🟡 Missing README | Directory lacks `README.md` documentation file |

### Detailed Findings

- **README Mismatches**:
- `renderers/angular/README.md`: Outdated setup command flags for workspace setup.
- `renderers/react/README.md`: Prop definitions missing newer v0.9 callback signatures.
- `swift/core`: No README file present in the codebase root.
- **Docstring / API Drift**:
- `agent_sdks/python/a2ui_agent/src/a2ui/a2a/extension.py:L45-L60`: Docstring parameter description uses outdated type annotations.

## Test Quality & Assertions Audit

| Suite / Module | Status | Observations |
|---|---|---|
| `agent_sdks/python/a2ui_agent` | 🟡 Weak Assertions | Generic `assert parsed is not None` in prompt example tests |
| `agent_sdks/python/a2ui_core` | 🟡 Weak Assertions | Schema checks rely on non-null assertions on root nodes |
| `renderers/angular` | 🟡 Weak Assertions | DOM element checks use `.toBeTruthy()` instead of state/attr check |
| `renderers/flutter` | 🟢 Satisfactory | Full widget tree assertions implemented |
| `renderers/lit` | 🟡 Weak Assertions | Smoke tests use `.toBeDefined()` on module exports |
| `renderers/react` | 🟡 Weak Assertions | Renderer tests check `expect(img).toBeTruthy()` without src validation |
| `renderers/web_core` | 🟢 Satisfactory | Signal state transitions thoroughly asserted |
| `swift/core` | 🟢 Satisfactory | Model parsing and message error mapping tests pass with value checks |

### Detailed Findings

- **Weak Assertions**:
- `agent_sdks/python/a2ui_agent/tests/test_prompt_examples.py:L134`: `assert parsed is not None` checks payload existence rather than full structure.
- `agent_sdks/python/a2ui_core/tests/test_components.py:L193`: `assert schema is not None` lacks property validation.
- `renderers/angular/a2ui_explorer/src/app/tests/v0_8/00_simple-login-form.spec.ts:L52`: `expect(btn).toBeTruthy()` checks presence without verifying button state or binding.
- `renderers/lit/a2ui_explorer/tests/v0_9/05_product-card.test.ts:L56`: `expect(img).toBeTruthy()` lacks attribute assertions for `src` and `alt`.
- `renderers/react/a2ui_explorer/tests/v0_9/01_flight-status.test.tsx:L53`: `expect(iconInnerEl).toBeTruthy()` checks presence without class or icon name verification.
- **Missing Edge Case Tests**:
- `agent_sdks/python/a2ui_agent`: Needs additional test cases for invalid DSL payload recovery.
- `renderers/react`: Lacks explicit boundary tests for missing theme context fallbacks.

The issue lists specific files needing updates across multiple codebases: blueprints in `blueprints/codebases/`, READMEs in `renderers/angular/README.md`, `renderers/react/README.md`, `agent_sdks/python/a2ui_agent/README.md`, and a new `swift/core/README.md`. Test files like `agent_sdks/python/a2ui_agent/tests/test_prompt_examples.py:L134` and `renderers/angular/a2ui_explorer/src/app/tests/v0_8/00_simple-login-form.spec.ts:L52` need stronger assertions. Start by examining the blueprint format and the current test assertions to understand what 'exact value and structural payload assertions' means. Done looks like updated files and passing tests.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.