Skip to content

Migrate .ai/ AICaC context to the v2 schema (+ all v1-structure consumers) #227

@eFAILution

Description

@eFAILution

Summary

Migrate the repo's AICaC context (.ai/*.yaml) from the v1.0 schema to v2.0. Deferred from #226 because it cascades well beyond a schema change — it breaks the repo's own .ai/-consuming tooling and shipped SDK code, so the .ai/ files and every consumer must migrate in lockstep.

Background

aicac-adoption@0.6.0 auto-stages a v1→v2 migration on every default-branch run. We disabled that in #225 (auto-migrate: false, regenerate-index: false) so it stops failing against the signed-commits ruleset / "Actions can't open PRs". The migration is worth doing, just not a drop-in.

Why it's not a simple PR

The v2 schema requires shapes — flat entrypoints string-map, components as a dict, decisions/errors as dicts keyed by id, reshaped data_flow — that every consumer currently parses in the v1 shape:

  • scripts/ci/check_architecture_sync.py — reads entrypoints.cli_subcommands as a dict → CI gate fails on v2 (verified: exit 1)
  • scripts/docsite/architecture.py — reads components as a list + cli_subcommands dict → public docs (Deploy Docs) build breaks
  • argus/architecture_map.py — transforms architecture.yaml + decisions.yaml; feeds the MCP argus://architecture resource, the browser viewer /architecture route, and the docsite → shipped SDK features break
  • their tests (scripts/docsite/tests/test_architecture.py, architecture-map tests, …)

Acceptance criteria

  • .ai/*.yaml migrated to v2 and validating against eFAILution/AICaC:spec/v2/*.schema.json (done on the draft branch — see chore(ai): migrate .ai/ AICaC context to the v2.0 schema #226; 0 violations, content counts preserved)
  • check_architecture_sync.py reads v2 shapes; unit-test job green
  • scripts/docsite/architecture.py renders from v2; Deploy Docs green
  • argus/architecture_map.py consumes v2; MCP argus://architecture + browser /architecture verified
  • all affected tests updated and green
  • re-enable AICaC auto-migrate/regenerate-index (revert fix(ci): disable AICaC auto-migrate/regenerate-index unsigned pushes #225) once v2 is live — or confirm they're no longer needed
  • review the aicac/** ruleset bypass + "Allow GitHub Actions to create and approve pull requests" setting added during triage — keep or revert

Starting point

References

#226 (draft v2 .ai/), #225 (interim fix), ADR-029 (the github-actions→Renovate→AICaC-bump→v2 cascade), eFAILution/AICaC:spec/v2/.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions