KeiSeiKit-1.0/skills/ci-scaffold/phase-2-matrix.md

Phase 2 — Build matrix (OS × version × target)

Decide how the build fans out. Matrix minimum: OS × primary-language version. Max reasonable: 3 OS × 3 versions × 3 targets = 27 cells — beyond that CI time-to-green kills iteration speed.

2a — Matrix click (AskUserQuestion, multi-select across three axes)

The question encodes three axes in one screen to keep the click contract tight. Each selection is stored as a set; the cartesian product becomes MATRIX.

{
  "questions": [
    {
      "question": "Build OS?",
      "header": "OS",
      "multiSelect": true,
      "options": [
        {"label": "ubuntu-24.04",       "description": "GH-hosted default; also available as self-hosted label on Forgejo"},
        {"label": "ubuntu-22.04",       "description": "Older glibc; pick if targeting older prod"},
        {"label": "macos-14",           "description": "Apple Silicon (M1); required for Swift/iOS/macOS builds"},
        {"label": "macos-13",           "description": "Intel macOS; x86_64 test matrix on Apple software"},
        {"label": "windows-2022",       "description": "Only when a .exe / MSVC artefact is shipped"},
        {"label": "self-hosted (Forgejo runner)", "description": "Labels from ci-forgejo-actions.md: self-hosted,linux,x64,docker"}
      ]
    },
    {
      "question": "Language / toolchain versions (picks combine with every OS)?",
      "header": "Versions",
      "multiSelect": true,
      "options": [
        {"label": "Rust stable + MSRV 1.80",    "description": "rust: [stable, 1.80] — MSRV pin catches accidental newer-feature use"},
        {"label": "Node 20 LTS + 22 LTS",       "description": "node-version: [20, 22] — covers current + upcoming LTS"},
        {"label": "Python 3.11 + 3.12 + 3.13",  "description": "python-version: ['3.11','3.12','3.13'] — matches supported pip-audit range"},
        {"label": "Go 1.22 + 1.23",             "description": "go-version: ['1.22','1.23'] — current + previous minor"},
        {"label": "Flutter stable",             "description": "Single version; pin via flutter-version-file"},
        {"label": "Swift 6.0 (Xcode 16)",       "description": "xcode-select on macos-14; one version per OS cell"},
        {"label": "Single version only",        "description": "Matrix collapses on the version axis; OS axis still fans out"}
      ]
    },
    {
      "question": "Cross-compile targets (Rust / Go only; skip otherwise)?",
      "header": "Targets",
      "multiSelect": true,
      "options": [
        {"label": "host (no cross)",           "description": "Default; one per OS"},
        {"label": "aarch64-unknown-linux-gnu", "description": "ARM64 server deploy; use cross or native ARM runner"},
        {"label": "wasm32-unknown-unknown",    "description": "Browser / edge Worker target"},
        {"label": "x86_64-pc-windows-gnu",     "description": "MinGW Windows from Linux build"},
        {"label": "aarch64-apple-darwin",      "description": "Apple Silicon; native on macos-14, cross on ubuntu"}
      ]
    }
  ]
}

Store the three sets as MATRIX.os, MATRIX.versions, MATRIX.targets. The scaffold uses the cartesian product.

2b — Sanity check (no AskUserQuestion)

Compute N = |os| × |versions| × |targets|. Print inline:

Matrix cells: N (os=<...>) × (versions=<...>) × (targets=<...>)
Estimated runtime: ~<N × typical-cell-minutes> minutes wall-clock (parallel)

If N > 12, warn once: "Matrix is wide. Consider dropping one axis or using strategy.fail-fast: true for PR-time feedback. Continue?"

If MATRIX.os includes both macos-* and MATRIX.targets includes only host, collapse the targets axis silently — host-on-mac is the only useful combination.

2c — Fail-fast click inferred (inline, no extra AskUserQuestion)

• PR matrix: fail-fast: false (user wants to see ALL failing cells at once).
• Scheduled cron + release matrix: fail-fast: true (first failure is enough to trigger remediation).

Emitted in Phase 3 ci.yml / release.yml accordingly.

Verify-criterion

• MATRIX.os has ≥1 entry.
• MATRIX.versions has ≥1 entry (or "Single version only").
• MATRIX.targets has ≥1 entry (defaults to host).
• N ≤ 27 or explicit user override recorded in the final report.
• If LANGS = {Swift} then MATRIX.os MUST include a macos-* entry (fail-closed otherwise).