CI/CD Flow Diagrams

flowchart TD
    A[Open, edit, synchronize, or mark PR ready] --> B[PR Governance]
    B --> B1{Template complete and ready?}
    B1 -- no --> B2[Add needs author action label and governance comment]
    B1 -- yes --> B3[Add ready for review label when no blocking status exists]

    A --> C[Path filters decide workflow surface]
    C --> D{Code paths changed?}
    D -- yes --> E[CI changes job]
    E --> F[lint: ruff, format, mypy]
    E --> G[build-wheel: Rust extension wheel]
    E --> H[prefetch-model: Hugging Face cache]
    G --> I[test shards 1 to 4]
    H --> I
    G --> J[test-extras, test-agno, dashboard UI]
    E --> K[build: release-profile wheel and sdist smoke]

    C --> L{E2E paths changed?}
    L -- yes --> M[Docker native e2e and platform wrapper checks]
    C --> N{Init or wrap paths changed?}
    N -- yes --> O[Init E2E, Wrap E2E, native init or wrap smoke tests]
    C --> P{Rust paths changed?}
    P -- yes --> Q[Rust fmt, clippy, tests, wheel build, audit]
    C --> R{Devcontainer paths changed?}
    R -- yes --> S[Devcontainer validation and linked worktree smoke]
    C --> T{Release-critical paths changed?}
    T -- yes --> U[Release dry-run: wheel matrix and smoke-import gates]
    C --> V{Workflow files changed?}
    V -- yes --> W[Workflow validation with actionlint and act dry-run]

    F --> X{All required checks green?}
    I --> X
    J --> X
    K --> X
    M --> X
    O --> X
    Q --> X
    S --> X
    U --> X
    W --> X
    B3 --> X
    X -- no --> Y[Fix, rebase, or request changes]
    X -- yes --> Z[Human review and merge when approved]

flowchart TD
    A[Review an open PR] --> B{Draft?}
    B -- yes --> C[Do not approve. Comment with remaining readiness steps.]
    B -- no --> D{Governance label says needs author action?}
    D -- yes --> E[Fix or ask author to complete template and real behavior proof]
    D -- no --> F{Merge state dirty or behind?}
    F -- dirty --> G[Resolve conflicts before reviewing final code]
    F -- behind --> H[Rebase or update branch, then rerun checks]
    F -- clean or unknown --> I{Any failing check?}
    I -- yes --> J[Read failing logs, classify as stale-main, infra, or code bug]
    J --> K{Can maintainer safely fix without changing author intent?}
    K -- yes --> L[Patch, test locally, push with lease]
    K -- no --> M[Request changes with exact file and line references]
    I -- no --> N{Code review complete?}
    N -- no --> O[Review diff, tests, docs, and behavior proof]
    N -- yes --> P[Approve]

flowchart TD
    A[Fork PR has action_required workflows] --> B{Diff is understandable and not suspicious?}
    B -- no --> C[Do not approve. Ask for changes or close if unsafe.]
    B -- yes --> D{Workflow runs use pull_request with read-scoped token?}
    D -- no --> E[Inspect workflow permissions before approving]
    D -- yes --> F[Approve queued CI runs]
    F --> G[Wait for fresh check results on latest head SHA]

flowchart TD
    A[Merge ordinary PR to main] --> B[Release Please on push to main]
    B --> C{Commit is releasable?}
    C -- docs, ci, chore only --> D[No release PR change]
    C -- fix, feat, breaking change --> E[Create or update Release PR]
    E --> F[Release PR contains version bump and changelog]
    F --> G{Ready to ship?}
    G -- no --> H[Keep merging regular PRs; bot updates Release PR]
    G -- yes --> I[Merge Release PR]
    I --> J[release-please tags vX.Y.Z and publishes GitHub Release]
    J --> K[release.yml starts on release: published]
    K --> L[detect-version]
    L --> M[build: sync versions, verify versions, changelog, npm packs]
    M --> N[build-wheels matrix]
    N --> O[collect-dist]
    O --> P[smoke-import wheels]
    P --> Q{Smoke import green?}
    Q -- no --> R[Stop before publishing broken wheels]
    Q -- yes --> S[publish PyPI]
    Q -- yes --> T[publish npm packages]
    Q -- yes --> U[publish GitHub Package Registry packages]
    Q -- yes --> V[publish Docker images through docker.yml]
    S --> W{PyPI published or PYPI_SKIP=true?}
    W -- no --> X[Do not update release assets]
    W -- yes --> Y[Create or update GitHub Release assets and notes]
    T --> Y
    U --> Y
    V --> Y

flowchart TD
    A[Need a release?] --> B{Release PR exists?}
    B -- no --> C[Merge at least one releasable conventional commit to main]
    B -- yes --> D{Release PR checks green and changelog correct?}
    D -- no --> E[Fix source PRs or release config, then let release-please update]
    D -- yes --> F{Registry skip variables needed?}
    F -- yes --> G[Set PYPI_SKIP, NPM_SKIP, or GH_PACKAGES_SKIP deliberately]
    F -- no --> H[Merge Release PR]
    G --> H
    H --> I[Watch release.yml]
    I --> J{Failure before publish?}
    J -- yes --> K[Fix and rerun before any package is public]
    J -- no --> L{Failure after partial publish?}
    L -- yes --> M[Use rerun or skip variables to reach consistent GitHub Release state]
    L -- no --> N[Release complete]

flowchart TD
    A[Docker workflow starts] --> B[Matrix: variant x architecture]
    B --> C[Build each platform image by digest only]
    C --> D[Smoke-test image imports pydantic_core and headroom._core]
    D --> E{Smoke test green?}
    E -- no --> F[Stop before tag manifest]
    E -- yes --> G[Upload digest marker]
    G --> H[Per-variant manifest merge]
    H --> I[Apply tags to multi-arch manifest]
    I --> J{Release event?}
    J -- yes --> K[Version tags and latest retag rules]
    J -- no --> L[Branch, PR, dev, or manual tags as configured]

flowchart TD
    A[Docs change in PR] --> B[PR review and normal checks]
    B --> C[Merge to main]
    C --> D{docs/**, mkdocs.yml, or docs workflow changed?}
    D -- no --> E[No docs deploy]
    D -- yes --> F[Deploy Documentation workflow]
    F --> G[Build docs site]
    G --> H[Deploy generated site]

flowchart TD
    A[Edit workflow or release scripts] --> B[Run local workflow validation]
    B --> C[actionlint]
    B --> D[act dry-run fixtures]
    C --> E{Local validation green?}
    D --> E
    E -- no --> F[Fix before opening or updating PR]
    E -- yes --> G[Push PR]
    G --> H[workflow-validation job reruns same validation in CI]

bash scripts/validate-workflows.sh

act workflow_dispatch -W .github/workflows/release.yml -e .github/act/dry-run.json