Taskfile.yml

# Taskfile for mecatl (https://taskfile.dev).
#
# Required tools (assumed on PATH; install commands below):
#   - go            >= 1.27.3   (the toolchain)
#   - golangci-lint (version in scripts/install-golangci-lint.sh)
#                               task tools:golangci-lint (installs the CI-matching
#                               official release binary into .tools/bin)
#   - goimports     (only for `task fmt`)
#                               go install golang.org/x/tools/cmd/goimports@latest
#   - buf           (for `task generate` and `task docs:grpc-ref`)
#                               https://buf.build/docs/installation
#   - helm unittest (only for `task deploy:helm-unittest`)
#                               task deploy:helm-unittest installs the pinned
#                               plugin when it is absent
#
# golangci-lint is invoked with --allow-parallel-runners everywhere so several
# work packages can lint the same checkout concurrently without clobbering each
# other's run lock.
version: '3'

includes:
  site:
    taskfile: website/Taskfile.yml
    dir: website
  sdk:
    taskfile: sdk/typescript/Taskfile.yml
    dir: sdk/typescript
  slack-bot:
    taskfile: sdk/typescript/examples/slack-bot/Taskfile.yml
    dir: sdk/typescript/examples/slack-bot
  studio:
    taskfile: apps/Taskfile.yml
    dir: apps
  mecak8s:
    taskfile: deploy/mecak8s-kind/Taskfile.yml
    dir: .
  mecak8s-vmcp:
    taskfile: deploy/mecak8s-vmcp/Taskfile.yml
    dir: .
  mecak8s-idbroker:
    taskfile: deploy/mecak8s-idbroker/Taskfile.yml
    dir: .

vars:
  GO_MODULES:
    - '.'
    - engine
    - internal/adaptersupport
    - contracts/gen/go/mecatl/driver
    - adapters
    - authn/oidc
    - environment/microvm
    - integration/microvm
    - provider/ssefilter
    - provider/anthropic
    - provider/openai
    - provider/openaichat
  PKG: github.com/stacklok/mecatl
  # BUILD_ID is an optional explicit linker stamp. Otherwise, resolve the source
  # checkout identity at build time; direct Go/ko builds retain the runtime VCS fallback.
  BUILD_ID:
    sh: |
      if [ -n "${BUILD_ID:-}" ]; then
        printf %s "$BUILD_ID"
      else
        git describe --tags --match 'v[0-9]*' --always --dirty 2>/dev/null || printf %s dev
      fi
  MECATL_METRICS_KEY: '{{.MECATL_METRICS_KEY | default ""}}'
  BUILD_LDFLAGS: '-X github.com/stacklok/mecatl/internal/buildinfo.BuildID={{.BUILD_ID}} -X github.com/stacklok/mecatl/internal/adapter/productmetrics.bakedKey={{.MECATL_METRICS_KEY}}'
  # The GoReleaser BINARY version. Must stay in lockstep with the `version:`
  # pinned in .github/workflows/release.yml and .github/workflows/ci.yml.
  # .goreleaser.yaml is loaded STRICTLY, so a config field newer than this pin
  # is a hard failure rather than a warning.
  GORELEASER_VERSION: v2.16.0

tasks:
  default:
    desc: List available tasks
    cmds:
      - task --list
    silent: true

  build:
    desc: Compile binaries into bin/
    cmds:
      - go build -ldflags "{{.BUILD_LDFLAGS}}" -o bin/mecated ./cmd/mecated
      - go build -ldflags "{{.BUILD_LDFLAGS}}" -o bin/mecademo ./cmd/mecademo
      # mecatequi: the single-shot, headless CI/batch runner (one prompt -> diff +
      # summary JSON + optional durable event log -> exit code).
      - go build -ldflags "{{.BUILD_LDFLAGS}}" -o bin/mecatequi ./cmd/mecatequi
      # mecak8s: the storage-free, k8s-native agent binary (a thin peer
      # of mecated composing app.Build with Redis store + k8s lease + drain gate).
      - go build -ldflags "{{.BUILD_LDFLAGS}}" -o bin/mecak8s ./cmd/mecak8s
      # Optional native Kubernetes execution provider and its fixed workload helper.
      - go build -ldflags "{{.BUILD_LDFLAGS}}" -o bin/mecatl-execution-provider ./cmd/mecatl-execution-provider
      - go build -ldflags "{{.BUILD_LDFLAGS}}" -o bin/mecatl-executor ./cmd/mecatl-executor
      - go build -ldflags "{{.BUILD_LDFLAGS}}" -o bin/mecatui ./cmd/mecatui
      # engine/ is its own Go module (consumed via the committed go.work). Building
      # it here keeps the importable-core module compiling alongside the binaries.
      - cd engine && go build ./...
      - cd internal/adaptersupport && go build ./...
      - cd contracts/gen/go/mecatl/driver && go build ./...
      - cd adapters && go build ./...
      # authn/oidc is the opt-in caller-identity adapter module,
      # separate from both the dependency-free engine and provider modules.
      - cd authn/oidc && go build ./...
      # environment/microvm is the opt-in local microVM runtime module.
      # It remains isolated from the root and engine dependency graphs.
      - cd environment/microvm && go build ./...
      # provider/ holds the opt-in LLM-provider Go submodules, each its
      # own module under the workspace. Building them here keeps the importable
      # adapters compiling alongside the binaries.
      - cd provider/ssefilter && go build ./...
      - cd provider/anthropic && go build ./...
      - cd provider/openai && go build ./...
      - cd provider/openaichat && go build ./...

  build:mecated:
    desc: Compile only bin/mecated, the daemon the SDK, Slack bot, and Studio suites spawn
    # CI builds bin/mecated once and hands it to those suites as an artifact;
    # MECATL_PREBUILT_MECATED=1 tells this task to use that binary as is.
    status:
      - test "${MECATL_PREBUILT_MECATED:-}" = 1 && test -x bin/mecated
    cmds:
      - go build -ldflags "{{.BUILD_LDFLAGS}}" -o bin/mecated ./cmd/mecated

  install:
    desc: Install mecated and mecatui into GOBIN/GOPATH/bin
    cmds:
      - go install -ldflags "{{.BUILD_LDFLAGS}}" ./cmd/mecated
      - go install -ldflags "{{.BUILD_LDFLAGS}}" ./cmd/mecatui

  test:golden:
    desc: Refresh mecatui View/teatest golden files (-update) then re-run them
    cmds:
      - go test ./cmd/mecatui/ui/ -update
      - go test ./cmd/mecatui/ui/

  api:check:
    desc: |
      The api-compat gate — fail if the engine module's public API surface (the
      eight core packages) drifts from the committed engine/api/*.txt snapshots.
      See engine/COMPATIBILITY.md. (Also runs under `task test` via ./...)
    cmds:
      - go test ./internal/apicheck

  api:update:
    desc: |
      Regenerate the committed engine/api/*.txt public-API snapshots after an
      INTENTIONAL change to a core engine package. Commit the result and add an
      engine/CHANGELOG.md entry classified per engine/COMPATIBILITY.md.
    cmds:
      - go test ./internal/apicheck -update

  api:release-check:
    desc: |
      ADVISORY (never fails CI): run gorelease over the engine module to preview
      the SemVer classification of the surface change. It needs a base engine/vX.Y.Z
      tag to be meaningful — none exists yet, so until the first tag is cut the
      authoritative PR guard is `task api:check`. See engine/COMPATIBILITY.md.
    cmds:
      - echo "advisory only — gorelease is meaningful once an engine/vX.Y.Z tag exists; the api-compat text gate (task api:check) is the PR guard until then."
      - cd engine && go run golang.org/x/exp/cmd/gorelease@v0.0.0-20260611194520-c48552f49976 || true

  clean:
    desc: Remove the bin/ build output directory
    cmds:
      - rm -rf bin/

  # --- Container image / deploy (ko) ----------------------------------------
  #
  # These tasks package mecated as a container image with ko (https://ko.build) —
  # no Dockerfile. Install ko first: https://ko.build/install/. The image is
  # built straight from ./cmd/mecated onto the distroless base pinned in .ko.yaml.
  #
  # Required env for publish/resolve:
  #   KO_DOCKER_REPO  destination registry/repo, e.g. ghcr.io/stacklok/mecatl
  #                   (ko:build hardcodes ko.local for a purely local image).

  ko:build:
    desc: Build the mecated image locally with ko (no push; tagged under ko.local)
    env:
      KO_DOCKER_REPO: ko.local
      VERSION: "{{.BUILD_ID}}"
    cmds:
      # --local loads the image into the local Docker/podman daemon; --bare
      # keeps the repo path clean (no extra import-path suffix) and prints the
      # fully-qualified image ref (with content-hash tag) on stdout.
      - ko build --local --bare ./cmd/mecated

  ko:publish:
    desc: Build and push the mecated image with ko (honours KO_DOCKER_REPO)
    env:
      VERSION: "{{.BUILD_ID}}"
    cmds:
      - cmd: |
          if [ -z "${KO_DOCKER_REPO:-}" ]; then
            echo "KO_DOCKER_REPO is required (e.g. export KO_DOCKER_REPO=ghcr.io/stacklok/mecatl)"; exit 1
          fi
        silent: true
      - ko build --push --bare ./cmd/mecated

  ko:resolve:
    desc: Render deploy/ manifests with the ko-built image ref (honours KO_DOCKER_REPO)
    cmds:
      - cmd: |
          if [ -z "${KO_DOCKER_REPO:-}" ]; then
            echo "KO_DOCKER_REPO is required (e.g. export KO_DOCKER_REPO=ghcr.io/stacklok/mecatl)"; exit 1
          fi
        silent: true
      # ko resolve substitutes the ko://… image placeholder in deploy/ with the
      # built+pushed ref and emits the rendered manifests on stdout. Pipe to
      # kubectl: `task ko:resolve | kubectl apply -f -`.
      - ko resolve -f deploy/

  ko:build:k8s:
    desc: Build the mecak8s image locally with ko (no push; tagged under ko.local)
    env:
      KO_DOCKER_REPO: ko.local
      VERSION: "{{.BUILD_ID}}"
    cmds:
      - ko build --local --bare ./cmd/mecak8s

  ko:publish:k8s:
    desc: Build and push the mecak8s image with ko (honours KO_DOCKER_REPO)
    env:
      VERSION: "{{.BUILD_ID}}"
    cmds:
      - cmd: |
          if [ -z "${KO_DOCKER_REPO:-}" ]; then
            echo "KO_DOCKER_REPO is required (e.g. export KO_DOCKER_REPO=ghcr.io/stacklok/mecatl/mecak8s)"; exit 1
          fi
        silent: true
      - ko build --push --bare ./cmd/mecak8s

  ko:build:mecatui:
    desc: Build the mecatui image locally with ko (issue #302; no push; tagged under ko.local)
    env:
      KO_DOCKER_REPO: ko.local
      VERSION: "{{.BUILD_ID}}"
    cmds:
      # --image-label sets the OCI config label brood-box reads to locate the
      # agent manifest (cmd/mecatui/kodata/agent.yaml, which ko lands at
      # /var/run/ko/agent.yaml via $KO_DATA_PATH). VERSION feeds the
      # {{.Env.VERSION}} ldflag template in .ko.yaml.
      - ko build --local --bare
          --image-label=org.stacklok.broodbox.agent=/var/run/ko/agent.yaml
          ./cmd/mecatui

  ko:publish:mecatui:
    desc: Build and push the mecatui image with ko (issue #302; honours KO_DOCKER_REPO)
    env:
      VERSION: "{{.BUILD_ID}}"
    cmds:
      - cmd: |
          if [ -z "${KO_DOCKER_REPO:-}" ]; then
            echo "KO_DOCKER_REPO is required (e.g. export KO_DOCKER_REPO=ghcr.io/stacklok/mecatl/mecatui)"; exit 1
          fi
        silent: true
      - ko build --push --bare
          --image-label=org.stacklok.broodbox.agent=/var/run/ko/agent.yaml
          ./cmd/mecatui

  # --- Release archives / Homebrew cask (GoReleaser) -------------------------
  #
  # GoReleaser owns ONLY the mecated+mecatui binary archives, the GitHub Release
  # they attach to, and the `mecatl` cask in stacklok/homebrew-tap. Container
  # images stay with ko (the ko:* targets above, .ko.yaml). See .goreleaser.yaml.
  #
  # These targets are LOCAL VERIFICATION only — the real release runs from
  # .github/workflows/release.yml on a vX.Y.Z tag. Deliberately not part of
  # `task ci`: they need a tool most contributors do not have, exactly like the
  # ko:* targets and `task vuln`.

  release:require-goreleaser:
    internal: true
    desc: Fail early with an actionable message if goreleaser is missing, and warn on version skew
    cmds:
      # goreleaser is expected ON PATH, like ko. Deliberately NOT
      # `go run github.com/goreleaser/goreleaser/v2@<ver>`: goreleaser does not
      # build from source on this repo's Go toolchain (its module graph resolves
      # grpc v1.80.0 against an x/net without http2.TrailerPrefix). CI is
      # unaffected because goreleaser-action downloads a PREBUILT binary.
      - cmd: |
          if ! command -v goreleaser >/dev/null 2>&1; then
            echo "goreleaser is not installed. Install it: https://goreleaser.com/install/"
            echo "CI pins {{.GORELEASER_VERSION}}; match it locally for representative output."
            exit 1
          fi
          have="$(goreleaser --version 2>/dev/null | awk '/GitVersion:/ {print $2}')"
          if [ "$have" != "{{.GORELEASER_VERSION}}" ]; then
            echo "warning: local goreleaser $have differs from the CI pin {{.GORELEASER_VERSION}};"
            echo "         snapshot output is representative but not identical."
          fi
        silent: true

  release:check:
    desc: Validate .goreleaser.yaml offline (strict schema; deprecations warn, not fail)
    cmds:
      # `goreleaser check` exits 2 for "valid, but uses DEPRECATED properties".
      # A deprecation is reported but accepted, so a GoReleaser upgrade that
      # deprecates a field we use does not block unrelated work; only exit 1
      # (genuinely invalid config) fails this gate.
      - task: release:require-goreleaser
      - cmd: |
          status=0
          goreleaser check || status=$?
          case "$status" in
            0) ;;
            2) echo "goreleaser check: config valid; uses deprecated properties - accepted" ;;
            *) exit "$status" ;;
          esac

  release:snapshot:
    desc: Build the release archives and Homebrew cask locally into dist/ (no tag, no upload, no tokens)
    cmds:
      # --snapshot skips publish/announce/validate, so this needs neither a clean
      # tree, nor a tag, nor GITHUB_TOKEN, nor HOMEBREW_TAP_GITHUB_TOKEN (the tap
      # token is only templated inside the publish path, which is never reached).
      # It does NOT skip sign or sbom, so skip those explicitly to avoid needing
      # cosign and syft locally. --skip=publish is redundant but self-documenting.
      - task: release:require-goreleaser
      - goreleaser release --snapshot --clean --skip=publish,sign,sbom

  release:verify:
    desc: Prove the release:snapshot output - both binaries per archive, the linker stamp, and cask style
    cmds:
      # Run `task release:snapshot` first. Three assertions, each guarding a
      # failure mode that would otherwise reach Homebrew users silently:
      #   1. the archive is FLAT and carries BOTH binaries (the generated
      #      `binary "mecated"` stanzas require them at the archive root),
      #   2. --version reports the stamped tag and not buildinfo's `dev+<rev>`
      #      VCS fallback (which is what a wrong -X symbol path produces),
      #   3. the generated cask passes Homebrew's own rubocop rules.
      # Note `brew style` is called WITHOUT --cask: that flag requires the
      # file to live in a real tap and rejects a path under dist/.
      # Cask/StanzaOrder is skipped because .goreleaser.yaml's custom_block puts
      # postflight_steps at the top of the cask; drop the exception once that
      # moves to GoReleaser's hooks.post.install_steps.
      - cmd: |
          set -eu
          arch="$(ls dist/mecatl_*_"$(go env GOOS)"_"$(go env GOARCH)".tar.gz)"
          echo "==> $arch"
          tar -tzf "$arch"
          for want in mecated mecatui; do
            tar -tzf "$arch" | grep -qx "$want" || { echo "MISSING $want at archive root"; exit 1; }
          done
          work="$(mktemp -d)"
          trap 'rm -rf "$work"' EXIT
          tar -xzf "$arch" -C "$work"
          for bin in mecated mecatui; do
            out="$("$work/$bin" --version)"
            echo "==> $out"
            case "$out" in
              *"dev+"*) echo "STAMP LOST: $bin reports the buildinfo VCS fallback; check the -X symbol path"; exit 1 ;;
            esac
          done
          echo "==> brew style dist/homebrew/Casks/mecatl.rb"
          brew style --except-cops Cask/StanzaOrder dist/homebrew/Casks/mecatl.rb

  test:_module:
    internal: true
    requires:
      vars: [MODULE]
    vars:
      RACE: '{{default "" .RACE}}'
      TEST_GOWORK: '{{default "off" .TEST_GOWORK}}'
    preconditions:
      - sh: '{{if has .MODULE .GO_MODULES}}true{{else}}false{{end}}'
        msg: 'MODULE must be one of: {{join ", " .GO_MODULES}}'
    cmds:
      # Go's default 10m per-package budget is too tight for cmd/mecatui/ui under
      # -race (about 400-600s on CI runners); the job-level timeout still bounds the run.
      - cd {{.MODULE | shellQuote}} && GOWORK={{.TEST_GOWORK | shellQuote}} go test -mod=readonly -timeout=20m {{.RACE}} ./...

  test:_suite:
    internal: true
    requires:
      vars: [RACE]
    vars:
      TEST_GOWORK: '{{default "" .TEST_GOWORK}}'
    deps:
      - for: {var: GO_MODULES}
        task: test:_module
        vars: {MODULE: '{{.ITEM}}', RACE: '{{.RACE}}', TEST_GOWORK: '{{.TEST_GOWORK}}'}
      - task: test:microvm-dev-tag
        vars: {RACE: '{{.RACE}}', TEST_GOWORK: '{{.TEST_GOWORK}}'}

  microvm:build:
    desc: Build the opt-in microvmd and Linux guest-agent artifacts without widening standard binaries.
    cmds:
      - mkdir -p bin/microvm
      - cd environment/microvm && GOWORK=off go build -o ../../bin/microvm/mecatl-microvmd ./cmd/mecatl-microvmd
      - cd environment/microvm && GOWORK=off CGO_ENABLED=0 GOOS=linux go build -o ../../bin/microvm/mecatl-guest-agent ./cmd/mecatl-guest-agent

  microvm:package:
    desc: Package the independently admitted guest-agent artifact.
    deps: [microvm:build]
    cmds:
      - mkdir -p bin/microvm/guest-agent-artifact
      - cp bin/microvm/mecatl-guest-agent bin/microvm/guest-agent-artifact/mecatl-guest-agent
      - tar -C bin/microvm/guest-agent-artifact -cf bin/microvm/mecatl-guest-agent-artifact.tar mecatl-guest-agent

  microvm:dev:prepare:
    desc: Prepare an unsupported signed local development release under .scratch for the current supported host (network/tooling required).
    cmds:
      - .github/scripts/prepare-microvm-development-release.sh "{{.BUILD_ID}}"
      - |
          case "$(uname -s)-$(uname -m)" in
            Linux-x86_64) platform=linux-amd64 ;;
            Darwin-arm64) platform=darwin-arm64 ;;
            *) echo "unsupported microVM development platform: $(uname -s)/$(uname -m)" >&2; exit 1 ;;
          esac
          MECATL_MICROVM_DEV_RELEASE_DESCRIPTOR="$(pwd)/.scratch/microvm-dev/${platform}/release.json" go test -tags=microvm_dev -run '^TestPreparedDevelopmentReleaseBundleIsImportable$' ./internal/adapter/microvmmanager

  microvm:dev:build:
    desc: Build microvm_dev-tagged mecated and mecatui binaries under .scratch; ordinary task build is unchanged.
    cmds:
      - mkdir -p .scratch/microvm-dev/bin
      - go build -tags=microvm_dev -ldflags "{{.BUILD_LDFLAGS}}" -o .scratch/microvm-dev/bin/mecated ./cmd/mecated
      - go build -tags=microvm_dev -ldflags "{{.BUILD_LDFLAGS}}" -o .scratch/microvm-dev/bin/mecatui ./cmd/mecatui

  microvm:dev:e2e:
    desc: Run the local-development descriptor/tag gate, then the current-host Linux KVM or Darwin HVF journey (network and hypervisor required).
    deps: [microvm:dev:prepare, microvm:dev:build]
    cmds:
      - task: test:microvm-dev-tag
      - task: e2e:microvm

  microvm:e2e:mecatui-build:
    desc: Build the production mecatui command with one generated E2E release-default projection.
    requires:
      vars: [MECATL_MICROVM_E2E_MECATUI_BIN, MECATL_MICROVM_E2E_VERSION, MECATL_MICROVM_E2E_DEFAULTS_B64]
    cmds:
      - mkdir -p "$(dirname \"{{.MECATL_MICROVM_E2E_MECATUI_BIN}}\")" .scratch/go-build
      - GOTMPDIR="$(pwd)/.scratch/go-build" go build -trimpath -o "{{.MECATL_MICROVM_E2E_MECATUI_BIN}}" -ldflags "-X main.version={{.MECATL_MICROVM_E2E_VERSION}} -X main.microVMReleaseDefaultsB64={{.MECATL_MICROVM_E2E_DEFAULTS_B64}}" ./cmd/mecatui

  e2e:microvm:
    desc: Run the deterministic mock-provider Linux amd64 KVM or Darwin arm64 HVF production-composed journey (artifact network required; no live LLM; never part of task test).
    cmds:
      - cmd: |
          set -eu
          if [ "${MECATL_MICROVM_E2E_PREPARED:-}" != "1" ]; then
            ./environment/microvm/e2e/prepare.sh
          fi
          case "$(uname -s)-$(uname -m)" in
            Linux-x86_64) PLATFORM=linux-amd64 ;;
            Darwin-arm64) PLATFORM=darwin-arm64 ;;
            *) echo "microVM production E2E requires Linux amd64 KVM or Darwin arm64 macOS 15+ HVF; got $(uname -s)/$(uname -m)" >&2; exit 1 ;;
          esac
          E2E_ROOT="$(pwd)/.scratch/microvm-e2e/${PLATFORM}"
          RUN_ROOT_BASE="$(pwd)/.scratch/microvm-e2e/run"
          rm -rf "${RUN_ROOT_BASE}"
          mkdir -p "${RUN_ROOT_BASE}"
          case "$(uname -s)" in
            Linux) E2E_STATE_ROOT=/dev/shm ;;
            Darwin) E2E_STATE_ROOT=/private/tmp ;;
          esac
          MICROVMD_BIN="${E2E_ROOT}/mecatl-microvmd"
          INSTALL_ROOT="${E2E_STATE_ROOT}/mecatl-release-install-${PLATFORM}-$$"
          rm -rf "${INSTALL_ROOT}"
          trap 'rm -rf "${INSTALL_ROOT}"' EXIT
          (cd environment/microvm && GOWORK=off go build -o "${MICROVMD_BIN}" ./cmd/mecatl-microvmd)
          # The focused live test crosses ordinary first-use readiness and the
          # production UDS through the server-owned microVM default. It drives
          # filesystem Read/Write/Shell, source and host-path isolation, logical-child
          # merge/conflict behavior, graceful daemon restart, and exact reattachment.
          DEFAULT_LIVE_TEST_NAMES='TestMicroVMDefaultPlacementDailyHarnessJourney'
          run_live_tests() {
            LIVE_TESTS=$1
            RUN_ROOT=$2
            EXPECTED_TEST=${3:-}
            rm -rf "${RUN_ROOT}"
            mkdir -p "${RUN_ROOT}/artifact-cache"
            if ! TEST_OUTPUT=$( \
              MECATL_MICROVMD_BIN="${MICROVMD_BIN}" \
              MECATL_MICROVM_E2E_ROOT="${RUN_ROOT}" \
              MECATL_MICROVM_E2E_SOCKET_ROOT="${E2E_STATE_ROOT}" \
              MECATL_MICROVM_ARTIFACT_CACHE="${RUN_ROOT}/artifact-cache" \
              MECATL_MICROVM_RELEASE_MANIFEST="${E2E_ROOT}/package/microvm-release-${PLATFORM}.json" \
              MECATL_MICROVM_RELEASE_ASSETS="${E2E_ROOT}/package" \
              MECATL_MICROVM_RELEASE_PUBLIC_KEY="${E2E_ROOT}/release-fixture/publisher.pub" \
              MECATL_MICROVM_INSTALLER="$(pwd)/.github/scripts/install-microvm-release.sh" \
              MECATL_MICROVM_INSTALL_ROOT="${INSTALL_ROOT}" \
              MECATL_MICROVM_RUNTIME_DIR="${E2E_ROOT}/runtime" \
              MECATL_MICROVM_FIRMWARE_DIR="${E2E_ROOT}/firmware" \
              MECATL_MICROVM_ROOTFS_DIR="${E2E_ROOT}/rootfs" \
              MECATL_MICROVM_GUEST_AGENT_DIR="${E2E_ROOT}/guest-agent" \
              go test -v -count=1 -timeout=40m -tags=microvm_e2e -run "${LIVE_TESTS}" ./internal/adapter/microvm 2>&1
            ); then
              printf '%s\n' "${TEST_OUTPUT}"
              return 1
            fi
            printf '%s\n' "${TEST_OUTPUT}"
            if ! printf '%s\n' "${TEST_OUTPUT}" | grep -Eq '^=== RUN   '; then
              echo "microVM E2E regex discovered no tests: ${LIVE_TESTS}" >&2
              return 1
            fi
            if [ -n "${EXPECTED_TEST}" ] && ! printf '%s\n' "${TEST_OUTPUT}" | grep -Fq -- "=== RUN   ${EXPECTED_TEST}"; then
              echo "named microVM E2E test was not executed: ${EXPECTED_TEST}" >&2
              return 1
            fi
          }
          if [ -n "${MECATL_MICROVM_E2E_TESTS:-}" ]; then
            # An operator-provided regex remains one ordinary go test invocation,
            # but a no-match is an error rather than a false-green run.
            run_live_tests "${MECATL_MICROVM_E2E_TESTS}" "${RUN_ROOT_BASE}"
          else
            # Each default journey gets a fresh cache. Successful state is removed
            # before the next journey; a failure remains available for diagnosis.
            for LIVE_TEST in ${DEFAULT_LIVE_TEST_NAMES}; do
              TEST_RUN_ROOT="${RUN_ROOT_BASE}/${LIVE_TEST}"
              run_live_tests "^${LIVE_TEST}$" "${TEST_RUN_ROOT}" "${LIVE_TEST}"
              rm -rf "${TEST_RUN_ROOT}"
            done
          fi
          # Keep the deterministic production-composition contract beside the live
          # journey: exact reattach plus lazy/no-fs allocation, multi-session
          # isolation, harness restart continuity, fail-closed daemon-state loss,
          # and direct-write versus isolated-child routing.
          go test -count=1 -run '^Test(MicroVMDefaultPlacementRetainsOneExactAttachmentUntilCloseSession|MicroVMOperatorJourneyIsLazyIsolatedAndRestartExact)$' ./internal/app

  test:
    desc: Run the complete offline test suite without the race detector
    cmds:
      - task: test:_suite
        vars: {RACE: '', TEST_GOWORK: ''}

  test:non-race:
    desc: Compatibility alias for the complete offline test suite
    cmds:
      - task: test

  test:race:
    desc: Run the complete offline test suite with the race detector
    cmds:
      - task: test:_suite
        vars: {RACE: '-race', TEST_GOWORK: ''}

  test:workspace:
    desc: Run the complete offline test suite against this checkout's workspace
    # Resolve in Task's checkout directory; ROOT_DIR is CLI-overridable.
    cmds:
      - task: test:_suite
        vars: {RACE: '', TEST_GOWORK: {sh: 'printf "%s/go.work" "$(pwd -P)"'}}

  test:workspace:race:
    desc: Run the complete offline workspace test suite with the race detector
    cmds:
      - task: test:_suite
        vars: {RACE: '-race', TEST_GOWORK: {sh: 'printf "%s/go.work" "$(pwd -P)"'}}

  test:module:
    desc: Run one module's tests with GOWORK=off (MODULE=. for root)
    cmds:
      - task: test:_module
        vars: {MODULE: '{{.MODULE}}', RACE: '', TEST_GOWORK: 'off'}

  test:module:race:
    desc: Run one module's tests with GOWORK=off and the race detector
    cmds:
      - task: test:_module
        vars: {MODULE: '{{.MODULE}}', RACE: '-race', TEST_GOWORK: 'off'}

  test:workspace:module:
    desc: Run one module's tests against this checkout's workspace
    cmds:
      - task: test:_module
        vars: {MODULE: '{{.MODULE}}', RACE: '', TEST_GOWORK: {sh: 'printf "%s/go.work" "$(pwd -P)"'}}

  test:workspace:module:race:
    desc: Run one module's tests against this checkout's workspace with the race detector
    cmds:
      - task: test:_module
        vars: {MODULE: '{{.MODULE}}', RACE: '-race', TEST_GOWORK: {sh: 'printf "%s/go.work" "$(pwd -P)"'}}

  test:module-metadata:
    desc: Verify Go module metadata is tracked and clean without modifying the checkout
    cmds:
      - sh .github/scripts/module-metadata.sh

  test:workspace-infrastructure:
    desc: Run offline workspace and module-metadata task regression tests
    cmds:
      - python3 .github/scripts/module-metadata_test.py
      - PATH="$(go env GOROOT)/bin:$PATH" python3 .github/scripts/workspace-tests_test.py

  test:module-publication:
    desc: Check releaseable module pins against main and compile the published adapters tag through the public Go proxy without workspace replacements.
    vars:
      VERSION: '{{.VERSION | default ""}}'
    env:
      MODULE_PUBLICATION_VERSION: '{{.VERSION}}'
    cmds:
      - sh .github/scripts/check-module-publication_test.sh
      - sh .github/scripts/check-module-publication.sh

  test:authn-standalone:
    desc: Prove the opt-in OIDC module builds and tests with GOWORK=off.
    cmds:
      - cd authn/oidc && GOWORK=off go build ./...
      - cd authn/oidc && GOWORK=off go test ./...

  test:microvm-dev-tag:
    desc: Compile and run the offline developer-only MicroVM activation gates.
    vars:
      RACE: '{{default "" .RACE}}'
      TEST_GOWORK: '{{default "" .TEST_GOWORK}}'
    cmds:
      - '{{if .TEST_GOWORK}}GOWORK={{.TEST_GOWORK | shellQuote}} {{end}}go test -mod=readonly {{if .TEST_GOWORK}}-timeout=20m {{end}}{{.RACE}} -tags=microvm_dev ./internal/adapter/microvmmanager ./cmd/mecated ./cmd/mecatui'

  test:microvm-standalone:
    desc: Prove the opt-in microVM module builds and tests with GOWORK=off.
    cmds:
      - cd environment/microvm && GOWORK=off go build ./...
      - cd environment/microvm && GOWORK=off go test ./...

  test:microvm-integration-standalone:
    desc: Prove the test-only microVM integration module tests with GOWORK=off.
    cmds:
      - cd integration/microvm && GOWORK=off go test ./...

  test:engine-standalone:
    desc: |
      Prove the engine module builds + tests with NO workspace and NO host-repo
      deps (GOWORK=off): the importable core's small dependency closure is
      self-contained. This is the hygiene gate that an external consumer's
      `go get github.com/stacklok/mecatl/engine` experience depends on.
    cmds:
      - cd engine && GOWORK=off go build ./...
      - cd engine && GOWORK=off go test ./...

  test:provider-standalone:
    desc: |
      Prove the opt-in provider/ submodules build + test with NO workspace
      (GOWORK=off), the same hygiene gate as test:engine-standalone. All four
      provider modules are checked with their own published dependency closures.
      CI covers this through `task test:race`, which tests every module with
      GOWORK=off. To prove the closure needs no network over a warmed module
      cache, run `task test:provider-standalone GOPROXY=off`.
    vars:
      GOPROXY: '{{.GOPROXY | default ""}}'
    cmds:
      - cd provider/ssefilter && GOWORK=off GOPROXY='{{.GOPROXY}}' go build ./...
      - cd provider/ssefilter && GOWORK=off GOPROXY='{{.GOPROXY}}' go test ./...
      - cd provider/anthropic && GOWORK=off GOPROXY='{{.GOPROXY}}' go build ./...
      - cd provider/anthropic && GOWORK=off GOPROXY='{{.GOPROXY}}' go test ./...
      - cd provider/openai && GOWORK=off GOPROXY='{{.GOPROXY}}' go build ./...
      - cd provider/openai && GOWORK=off GOPROXY='{{.GOPROXY}}' go test ./...
      - cd provider/openaichat && GOWORK=off GOPROXY='{{.GOPROXY}}' go build ./...
      - cd provider/openaichat && GOWORK=off GOPROXY='{{.GOPROXY}}' go test ./...

  test:actions:
    desc: |
      Run the OFFLINE shell tests for the mecatequi composite-action glue scripts
      (extract-prompt.sh, publish.sh) — plain bash, no bats, with fake gh/git stubs.
      They assert the SECURITY logic: extract-prompt never interpolates the untrusted
      issue body (a $(...) / backtick payload is written verbatim, never executed), and
      publish.sh's protected-paths gate rejects a .github/ patch (incl. a path-quoting bypass
      via `git apply --numstat -z`), its template-confinement rejects a ../ traversal, its
      PR-body render is literal + single-pass, and the no-change / failure / empty-exit-class
      branches comment without opening a PR. The action-wrappers test pins the composite
      action.yml env-mapping contract (actionlint can't lint composite actions). NOT part of
      `task test` (shell, not Go).
    cmds:
      - bash .github/actions/mecatequi-extract-prompt/extract-prompt_test.sh
      - bash .github/actions/mecatequi-publish/publish_test.sh
      - bash .github/actions/action-wrappers_test.sh

  e2e:
    desc: |
      Run the LIVE end-to-end suite (e2e/, build tag e2e) against OpenRouter.
      Spawns ./bin/mecated with ephemeral state under .scratch/ and drives real
      model runs — it costs (a little) real money and needs the network.
      Requires OPENROUTER_API_KEY in the environment (export it in-shell; this
      Taskfile never reads a key file). Point MECATL_E2E_TARGET=host:port at an
      existing server to skip the local spawn. See e2e/README.md.
    deps: [build]
    preconditions:
      - sh: test -n "$OPENROUTER_API_KEY" -o -n "$MECATL_E2E_TARGET"
        msg: |-
          OPENROUTER_API_KEY is not set (and no MECATL_E2E_TARGET given).
          Export OPENROUTER_API_KEY in your shell first (e.g. from your key
          file — see e2e/README.md), then re-run `task e2e`.
    cmds:
      # 60m is the OUTER bound only; every expensive spec carries its own ginkgo
      # SpecTimeout (driver timeout + 30s), so the CLEAN failure path (TIMEOUT
      # classification + transcript + AfterSuite teardown + cost ledger) always
      # fires long before go test's panic path. The per-spec driver timeouts ×
      # flake attempts sum to ~50m worst-case (see e2e/suite_test.go).
      - go test -tags e2e -count=1 -timeout 60m ./e2e/...

  e2e:k8s:
    desc: |
      Run the kind-based k8s e2e suite (e2e/k8s/, build tag kind_e2e).
      Spins a real kind cluster with a Redis StatefulSet + two storage-free
      mecak8s agent replicas and asserts lease exclusion, graceful failover,
      session persistence, and OIDC caller identity against an in-cluster Dex.
      Export OPENROUTER_API_KEY to ALSO run the LIVE variant (real LLM turns
      through the pods proving the plumbing under load; the live specs Skip
      without the key). Uses Docker by default, or rootless Podman with
      `CONTAINER_ENGINE=podman` (Kind's `k8s-file` Podman log driver is required;
      see https://kind.sigs.k8s.io/docs/user/rootless/). NOT part of `task test`
      (slow ~5-8 min mock-only, ~10-15 min with live).
    deps: [build]
    preconditions:
      - sh: command -v kind >/dev/null 2>&1
        msg: "kind is not installed (https://kind.sigs.k8s.io/docs/user/quick-start/#installation)"
      - sh: command -v ko >/dev/null 2>&1
        msg: "ko is not installed (https://ko.build/install/)"
      - sh: command -v helm >/dev/null 2>&1
        msg: "helm is not installed (https://helm.sh/docs/intro/install/)"
      - sh: command -v kubectl >/dev/null 2>&1
        msg: "kubectl is not installed"
      - sh: |
          runtime="${CONTAINER_ENGINE:-${KIND_EXPERIMENTAL_PROVIDER:-docker}}"
          case "$runtime" in docker|podman) command -v "$runtime" >/dev/null 2>&1 ;; *) exit 1 ;; esac
        msg: "CONTAINER_ENGINE must be docker (default) or podman, and the selected runtime must be on PATH"
      - sh: |
          runtime="${CONTAINER_ENGINE:-${KIND_EXPERIMENTAL_PROVIDER:-docker}}"
          test "$runtime" != podman || podman info --format json | grep -Eq '"rootless"[[:space:]]*:[[:space:]]*true'
        msg: "e2e:k8s:podman supports rootless Podman only"
      - sh: |
          runtime="${CONTAINER_ENGINE:-${KIND_EXPERIMENTAL_PROVIDER:-docker}}"
          test "$runtime" != podman || podman info --format json | grep -Eq '"logDriver"[[:space:]]*:[[:space:]]*"k8s-file"'
        msg: "rootless Podman requires log_driver = \"k8s-file\"; see https://kind.sigs.k8s.io/docs/user/rootless/"
    cmds:
      # 30m accommodates the LIVE specs when OPENROUTER_API_KEY is exported: a
      # real haiku turn takes 10-30s, the live lease/persistence specs each drive
      # 2-3 turns with FlakeAttempts(2), and the provider patch + rollout adds
      # ~1-2 min. Without the key the live specs Skip and the suite fits in 15m;
      # the outer bound only matters when the live variant runs. GOWORK=off proves
      # the image uses tagged external dependencies rather than workspace overlays.
      - cmd: |
          runtime="${CONTAINER_ENGINE:-${KIND_EXPERIMENTAL_PROVIDER:-docker}}"
          case "$runtime:${KIND_EXPERIMENTAL_PROVIDER:-}" in
            docker:|podman:podman) ;;
            podman:) export KIND_EXPERIMENTAL_PROVIDER=podman ;;
            *) echo "CONTAINER_ENGINE and KIND_EXPERIMENTAL_PROVIDER disagree" >&2; exit 2 ;;
          esac
          GOWORK=off go test -tags kind_e2e -count=1 -timeout 30m ./e2e/k8s/...

  e2e:k8s:execution:
    desc: |
      Run the focused mock-only Kind qualification for the optional Kubernetes
      execution provider. It uses a unique cluster and explicit kubeconfig under
      .scratch, builds/loads immutable local images, and never reads a provider
      credential. Docker is the default; set CONTAINER_ENGINE=podman for rootless
      Podman. The owned cluster is intentionally retained; the command prints the
      exact human-confirmed cleanup command. NOT part of task test.
    preconditions:
      - sh: command -v kind >/dev/null 2>&1
        msg: "kind is required"
      - sh: |
          runtime="${CONTAINER_ENGINE:-docker}"
          case "$runtime" in docker|podman) command -v "$runtime" >/dev/null 2>&1 ;; *) exit 1 ;; esac
        msg: "CONTAINER_ENGINE must be docker or podman and available on PATH"
    cmds:
      - deploy/mecatl-execution-kind/run.sh

  e2e:k8s:execution:production:
    desc: |
      Run the deterministic production-network and lifecycle execution-provider
      qualification. CI sets MECATL_EXECUTION_QUAL_CI=1 so its uniquely owned Kind
      cluster is removed automatically; local runs retain it for inspection and
      print the human-confirmed cleanup command. No model credential is used.
    cmds:
      - MECATL_EXECUTION_QUAL_PROFILE=production task e2e:k8s:execution

  e2e:k8s:execution:live:
    desc: |
      EXPLICIT OPT-IN: run mock qualification followed by one bounded real-provider
      coding smoke on the approved retained Kind cluster. Requires absolute
      MECATL_EXECUTION_CREDENTIAL_FILE and MECATL_EXECUTION_QUAL_STATE paths. A
      trusted loader stages a run-scoped Secret without exposing its value, the
      test independently verifies files and go test through typed gRPC, then the
      mock profile is restored and only that run-scoped Secret is removed. NOT
      part of task test.
    preconditions:
      - sh: test -n "${MECATL_EXECUTION_CREDENTIAL_FILE:-}"
        msg: "MECATL_EXECUTION_CREDENTIAL_FILE is required"
      - sh: test -n "${MECATL_EXECUTION_QUAL_STATE:-}"
        msg: "MECATL_EXECUTION_QUAL_STATE is required"
    cmds:
      - deploy/mecatl-execution-kind/live.sh

  e2e:k8s:podman:
    desc: Run e2e:k8s with rootless Podman (requires the k8s-file Podman log driver)
    cmds:
      - CONTAINER_ENGINE=podman task e2e:k8s

  deploy:helm-unittest:
    desc: Run the Helm-native mecak8s and mecatl-studio chart unit tests without a cluster
    vars:
      # Pinned version — bump deliberately. CI has no separate pin; the k8s-e2e
      # workflow runs this task directly. v1.1.x requires newer Helm plugin
      # manifest fields than the Helm 3.16 development floor supports.
      HELM_UNITTEST_VERSION: v1.0.3
    cmds:
      # Match ToolHive's cross-Helm install path: Helm 4 verifies plugin
      # signatures by default, while Helm 3 does not expose --verify.
      - cmd: |
          set -eu
          expected="{{.HELM_UNITTEST_VERSION}}"
          expected="${expected#v}"
          installed=$(helm plugin list | awk '$1 == "unittest" { print $2 }')
          if [ -n "$installed" ] && [ "$installed" != "$expected" ]; then
            echo "helm-unittest $installed is installed; version $expected is required" >&2
            echo "run 'helm plugin uninstall unittest' and retry" >&2
            exit 1
          fi
          if [ -z "$installed" ]; then
            helm plugin install https://github.com/helm-unittest/helm-unittest \
              --version {{.HELM_UNITTEST_VERSION}} \
              $(helm plugin install --help | grep -qE '^[[:space:]]+--verify([=[:space:]]|$)' && echo --verify=false)
          fi
      - helm unittest --strict deploy/helm/mecak8s
      - helm unittest --strict deploy/helm/mecatl-studio

  deploy:check:
    desc: |
      Validate the deploy/helm/mecak8s and deploy/helm/mecatl-studio charts
      WITHOUT a cluster: render every deploy/helm/{mecak8s,mecatl-studio}/ci/*-values.yaml fixture,
      schema-check the rendered manifests (mecak8s default + oidc.enabled=true),
      and assert the caller-identity boundaries. Needs helm + kubeconform; needs
      NO cluster, so it runs in CI and on a laptop.
    vars:
      PROD_SET: redis.endpoint=redis.example.internal:6379,redis.credentialsSecret=redis-credentials,security.allowUnsafeRealProvider=true,guardrails.fromSettings=true
      SAFE_SET: redis.endpoint=redis.example.internal:6379,redis.credentialsSecret=redis-credentials,tls.enabled=true,tls.secretName=mecak8s-tls,oidc.enabled=true,oidc.issuer=https://idp.example.com,oidc.audience=mecatl,guardrails.fromSettings=true
    preconditions:
      - sh: command -v helm >/dev/null 2>&1
        msg: "helm is not installed (https://helm.sh/docs/intro/install/)"
      - sh: command -v kubeconform >/dev/null 2>&1
        msg: "kubeconform is not installed (go install github.com/yannh/kubeconform/cmd/kubeconform@latest)"
    cmds:
      # `helm template | kubeconform` against every
      # deploy/helm/mecak8s/ci/*-values.yaml fixture — a discoverable,
      # `-f`-based example of a full production install, checked the same way
      # as the --set-based PROD_SET/OIDC_SET renders below. Deliberately NOT
      # `helm lint`: it does not fail on a template execution error (a
      # `fail`/`required` violation prints as an INFO line and still exits 0),
      # so it wouldn't catch the class of error this exists to catch. This is
      # chart-testing's (`ct lint`) fixture-directory convention without the
      # `ct` binary itself: `ct` shells out to Python yamale/yamllint even with
      # its other validations disabled, a real toolchain dependency this
      # repo's otherwise-all-Go tool chain (kind/ko/kubeconform/kustomize)
      # doesn't carry — not worth it for value `helm template`+kubeconform
      # already cover.
      - cmd: |
          set -eu -o pipefail
          for f in deploy/helm/mecak8s/ci/*-values.yaml; do
            helm template deploy/helm/mecak8s -f "$f" | kubeconform -strict -summary -
          done
        silent: true
      # kubeconform ships no Gateway API schemas, so HTTPRoute is skipped here;
      # the chart's helm-unittest suites assert its key fields.
      - cmd: |
          set -eu -o pipefail
          for f in deploy/helm/mecatl-studio/ci/*-values.yaml; do
            helm template mecatl-studio deploy/helm/mecatl-studio -f "$f" | kubeconform -strict -summary -skip HTTPRoute -
          done
        silent: true
      # Schema validation is kubeconform, NOT `kubectl apply --dry-run=client`:
      # kubectl maps kinds against the API server even with --validate=false, so
      # it needs a reachable cluster and cannot run here.
      - cmd: |
          set -eu -o pipefail
          helm template production deploy/helm/mecak8s --set '{{.PROD_SET}}' | kubeconform -strict -summary -
          helm template production deploy/helm/mecak8s --set '{{.SAFE_SET}}' | kubeconform -strict -summary -
        silent: true
      # The oidc-enabled render must carry every base arg alongside the oidc
      # args: Helm composes ONE args: list template-side rather than
      # JSON6902-patching an existing one, so the specific "did the patch drop
      # args" failure mode is structurally less likely here — kept anyway, it's
      # cheap and still guards a future refactor of the args block.
      - cmd: |
          set -eu -o pipefail
          missing=""
          rendered=$(helm template production deploy/helm/mecak8s --set '{{.SAFE_SET}}')
          for arg in --grpc-addr --http-addr --redis-url --session-lease-k8s-namespace --headless --permission-mode --oidc-issuer --oidc-audience --oidc-max-jwks-staleness=1h; do
            echo "$rendered" | grep -q -- "$arg" || missing="$missing $arg"
          done
          if [ -n "$missing" ]; then
            echo "oidc-enabled chart render is missing base args:$missing"; exit 1
          fi
        silent: true

  fuzz:
    desc: |
      Run the native Go fuzzers against the security-critical parsers for a
      bounded time each (manual / CI-nightly target — NOT part of `task test`).
      Each FuzzXxx also runs its seed corpus under plain `go test`, so the
      regression cases are already covered by `task test`; this task is the
      coverage-guided exploration pass. Override the per-target budget with
      FUZZTIME, e.g. `FUZZTIME=2m task fuzz`. FUZZTIME also accepts an
      iteration count (`Nx`, e.g. `FUZZTIME=300000x`) instead of a duration —
      CI's fuzz-smoke job uses that form so it can't race go test's own fuzz
      coordinator deadline.
    vars:
      FUZZTIME: '{{.FUZZTIME | default "30s"}}'
    cmds:
      # `go test` fuzzes only ONE target per invocation, so run them in sequence.
      # The governance fuzzers live in the engine MODULE, so they run from engine/.
      - cd engine && go test ./governance/ -run='^$' -fuzz='^FuzzSplitCommands$' -fuzztime={{.FUZZTIME}}
      - cd engine && go test ./governance/ -run='^$' -fuzz='^FuzzCanonicalize$' -fuzztime={{.FUZZTIME}}
      - cd engine && go test ./governance/ -run='^$' -fuzz='^FuzzReadOnlyShell$' -fuzztime={{.FUZZTIME}}
      - cd engine && go test ./governance/ -run='^$' -fuzz='^FuzzAuthorityOperationsAreMonotone$' -fuzztime={{.FUZZTIME}}
      - cd provider/openai && go test ./ -run='^$' -fuzz='^FuzzDecodeSSE$' -fuzztime={{.FUZZTIME}}

  bench:
    desc: |
      Run the hot-path testing.B microbenchmarks on the engine packages
      (manual / CI target — NOT part of `task test`). This is the microbenchmark
      half of perf-regression tracking (docs/perf-tracking.md): it fills the
      allocs/op baseline and is the source a `benchstat` comparison runs over.
      Capture two runs and diff them with benchstat
      (go install golang.org/x/perf/cmd/benchstat@latest), e.g.:
        BENCHCOUNT=10 task bench | tee new.txt
        git stash && BENCHCOUNT=10 task bench | tee old.txt && git stash pop
        benchstat old.txt new.txt
      allocs/op is the deterministic, gate-hard signal; treat ns/op as advisory
      on shared CI. The BenchmarkRun*Turn benchmarks measure startup-inclusive
      first-session/first-prompt work; BenchmarkSteadyState*Turn prewarms that
      lifecycle then measures one recurring continuation turn. Both families are
      hard-gated independently. Override the sample count with BENCHCOUNT (default
      10).
    vars:
      BENCHCOUNT: '{{.BENCHCOUNT | default "10"}}'
    cmds:
      # -run='^$' skips the unit tests (cuts noise); -benchmem reports B/op and
      # allocs/op; -count gives benchstat the samples it needs for a confidence
      # interval. Offline only — every benchmark uses mockllm + memfs. The hot-path
      # benchmarks live in the engine MODULE, so they run from engine/.
      - cd engine && go test -bench=. -benchmem -count={{.BENCHCOUNT}} -run='^$' ./prompt/ ./governance/ ./agent/

  perf:scenarios:
    desc: |
      Run the OFFLINE, deterministic scenario benchmarks (manual / CI target —
      NOT part of `task test`). This is the scenario half of perf-regression
      tracking (docs/perf-tracking.md): whole-loop runs through the real engine over
      mockllm + memfs/memstore that catch the failure modes the
      microbenchmarks miss — long-session allocation budget, goroutine hygiene
      under delegation, token/cache regressions, compaction churn — PLUS the
      mecatui scrollback render path.

      Two metric families, two `go test` invocations:
        - ./perf/scenarios/      — single-session-long, team-fanout,
                                   background-subagents, compaction-cycle.
        - ./cmd/mecatui/ui/      — BenchmarkScrollbackView (the SetContent
                                   O(scrollback) class) and
                                   BenchmarkSpinnerTickVPView (the spinner-tick
                                   vp.View() memo class).

      Override the sample count with BENCHCOUNT (default 6). Set MECATL_PERF_JSON
      to a path to also emit the per-scenario JSON KPIs (tokens, cache-hit-rate,
      RSS-over-time) the trend store ingests; both families MERGE into the one
      file. Default below: .scratch/perf-scenarios.json (gitignored). Leave it
      empty (MECATL_PERF_JSON= task perf:scenarios) for benchstat lines only.
      MECATL_PERF_SHA stamps the git SHA into each JSON row; it defaults to the
      current HEAD (override with MECATL_PERF_SHA=... for a tagged/CI ref).
    vars:
      BENCHCOUNT: '{{.BENCHCOUNT | default "6"}}'
      # The raw path (default .scratch/perf-scenarios.json; overridable via the
      # MECATL_PERF_JSON env/var). It is resolved to an ABSOLUTE path below because
      # `go test` sets the working dir to the PACKAGE dir, so a relative path would
      # otherwise resolve under perf/scenarios/ rather than the repo root.
      PERF_JSON_RAW: '{{.MECATL_PERF_JSON | default ".scratch/perf-scenarios.json"}}'
      # realpath -m resolves a (possibly relative, possibly not-yet-existing) path
      # against the repo root to an absolute path, robust to where `go test` runs.
      PERF_JSON_ABS:
        sh: 'cd {{.ROOT_DIR}} && realpath -m "{{.PERF_JSON_RAW}}"'
      # The git SHA stamped into every row: an explicit MECATL_PERF_SHA override
      # wins; otherwise resolve HEAD (empty string if not a git checkout, so the
      # rows just carry "" rather than failing the run). Resolved in ONE shell so
      # the override is honoured without a var-references-var template.
      PERF_SHA:
        sh: 'if [ -n "{{.MECATL_PERF_SHA}}" ]; then printf %s "{{.MECATL_PERF_SHA}}"; else git -C {{.ROOT_DIR}} rev-parse HEAD 2>/dev/null || true; fi'
    cmds:
      - mkdir -p "$(dirname '{{.PERF_JSON_ABS}}')"
      # perf/scenarios writes the file first (truncating); the mecatui bench then
      # MERGES its rows into it. Offline only — mockllm + memfs/memstore. Both runs
      # get the SAME MECATL_PERF_SHA so the two metric families share a SHA.
      - MECATL_PERF_JSON='{{.PERF_JSON_ABS}}' MECATL_PERF_SHA='{{.PERF_SHA}}' go test -bench=. -benchmem -count={{.BENCHCOUNT}} -run='^$' ./perf/scenarios/
      - MECATL_PERF_JSON='{{.PERF_JSON_ABS}}' MECATL_PERF_SHA='{{.PERF_SHA}}' go test -bench='BenchmarkScrollbackView|BenchmarkSpinnerTickVPView' -benchmem -count={{.BENCHCOUNT}} -run='^$' ./cmd/mecatui/ui/

  pgo:collect:
    desc: |
      Collect a PROVISIONAL OFFLINE CPU profile for Profile-Guided Optimization
      (docs/perf-tracking.md, "Profile-guided optimization").
      Manual target — NOT part of `task build`/`task test`.

      It runs the offline scenario + engine-agent benchmarks under CPU profiling
      with a FIXED iteration count, then merges the captures into a single pprof
      profile with `go tool pprof -proto`. Output lands under .scratch/pgo/
      (gitignored): scenarios.cpu, agent.cpu, and the merged default.pgo.

      Override the per-bench iteration count with PGOITERS (default 200x). Fewer
      iterations = a faster, noisier capture; more = a steadier profile.

      CAVEAT — this profile is OFFLINE-ONLY: it trains the compiler on the
      mockllm + memfs/memstore path that ships in NO production binary. There is
      no real provider, SSE, or network coverage in it. It is a MECHANISM check
      and a local experiment, NOT the profile to commit as cmd/mecated/default.pgo.
      The production refresh path (curl mecated's loopback pprof endpoint, merge,
      drop in cmd/mecated/default.pgo) is documented in perf-tracking.md "Profile-guided optimization".

      The merge is SAMPLE-WEIGHTED: -benchtime=Nx fixes the ITERATION count, not
      wall-time, and the whole-loop scenarios run ~100x longer per op than the
      agent micro-benches, so the scenario samples dominate the merged profile.
      That is fine here — the scenarios are the more production-representative
      workload, and this is a throwaway provisional artifact, so balance is a
      non-goal. (The PRODUCTION path is different: a fixed `?seconds=N` on every
      capture DOES equalize wall-time there — see perf-tracking.md "Profile-guided optimization".)
    vars:
      PGOITERS: '{{.PGOITERS | default "200x"}}'
    cmds:
      - mkdir -p .scratch/pgo
      # -run='^$' skips unit tests; -benchtime=Nx pins the iteration count (NOT
      # wall-time). Offline only — mockllm + memfs/memstore. -o writes the compiled
      # test binary pprof needs to symbolize the .cpu sample. The scenario capture
      # dominates the sample-weighted merge below (see desc).
      - go test -run='^$' -bench=. -benchtime={{.PGOITERS}} -cpuprofile=.scratch/pgo/scenarios.cpu -o .scratch/pgo/scenarios.test ./perf/scenarios/
      # Also capture the engine-agent micro-benches — a minor secondary contributor
      # (~5% of the merged samples given the ~100x/op gap), since they're a subset
      # of the dispatch/build-request hot path the scenarios already exercise.
      - go test -run='^$' -bench=. -benchtime={{.PGOITERS}} -cpuprofile=.scratch/pgo/agent.cpu -o .scratch/pgo/agent.test ./engine/agent/
      # Merge the captures into one profile. -proto emits the protobuf pprof format
      # the Go toolchain reads as a PGO profile; the merge is sample-weighted, so
      # the longer-running scenario samples dominate (the desired bias here).
      - go tool pprof -proto .scratch/pgo/scenarios.cpu .scratch/pgo/agent.cpu > .scratch/pgo/default.pgo
      - cmd: |
          echo
          echo "============================================================"
          echo "  PROVISIONAL OFFLINE PGO PROFILE — .scratch/pgo/default.pgo"
          echo "  Trained on the mockllm path only: NO real provider / SSE /"
          echo "  network coverage. This is NOT the production profile."
          echo "  Do NOT commit it as cmd/mecated/default.pgo."
          echo "  Production refresh path: docs/perf-tracking.md, Profile-guided optimization."
          echo "============================================================"
        silent: true

  test:cover:
    desc: Run tests with coverage and write coverage/coverage.{out,html} (root module + engine module)
    cmds:
      - mkdir -p coverage
      - go test -race -coverprofile=coverage/coverage.out -covermode=atomic ./...
      - go tool cover -func=coverage/coverage.out
      - go tool cover -html=coverage/coverage.out -o coverage/coverage.html
      - 'echo "HTML coverage report: coverage/coverage.html"'
      # engine/ is a separate module — cover it in its own pass (sibling profile).
      - cd engine && go test -race -coverprofile=../coverage/engine.out -covermode=atomic ./...
      - go tool cover -func=coverage/engine.out
      - go tool cover -html=coverage/engine.out -o coverage/engine.html
      - 'echo "HTML engine coverage report: coverage/engine.html"'
      - cd authn/oidc && go test -race -coverprofile=../../coverage/authn-oidc.out -covermode=atomic ./...
      - go tool cover -func=coverage/authn-oidc.out
      - go tool cover -html=coverage/authn-oidc.out -o coverage/authn-oidc.html
      - cd environment/microvm && go test -race -coverprofile=../../coverage/environment-microvm.out -covermode=atomic ./...
      - go tool cover -func=coverage/environment-microvm.out
      - go tool cover -html=coverage/environment-microvm.out -o coverage/environment-microvm.html
      # provider/ submodules — sibling profiles per module.
      - cd provider/ssefilter && go test -race -coverprofile=../../coverage/provider-ssefilter.out -covermode=atomic ./...
      - cd provider/anthropic && go test -race -coverprofile=../../coverage/provider-anthropic.out -covermode=atomic ./...
      - cd provider/openai && go test -race -coverprofile=../../coverage/provider-openai.out -covermode=atomic ./...
      - cd provider/openaichat && go test -race -coverprofile=../../coverage/provider-openaichat.out -covermode=atomic ./...

  tools:golangci-lint:
    desc: Install the CI-matching golangci-lint release into .tools/bin
    cmds:
      - sh scripts/install-golangci-lint.sh

  lint:
    desc: Run pinned golangci-lint (parallel-safe) over the root, engine, authn/oidc, and provider modules
    deps: [tools:golangci-lint]
    env:
      GOLANGCI_LINT: "{{.ROOT_DIR}}/.tools/bin/golangci-lint"
    preconditions:
      - sh: test -x "$GOLANGCI_LINT"
        msg: "missing pinned golangci-lint; run: task tools:golangci-lint"
    cmds:
      - '"$GOLANGCI_LINT" run --allow-parallel-runners ./...'
      # engine/ is its own module — it shares the ROOT golangci config (no
      # engine-local .golangci.yml) so the depguard layering allowlists stay the
      # single source of truth across the module boundary.
      - 'cd engine && "$GOLANGCI_LINT" run --config ../.golangci.yml --allow-parallel-runners ./...'
      - 'cd internal/adaptersupport && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners ./...'
      - 'cd contracts/gen/go/mecatl/driver && "$GOLANGCI_LINT" run --config ../../../../../.golangci.yml --allow-parallel-runners ./...'
      - 'cd adapters && "$GOLANGCI_LINT" run --config ../.golangci.yml --allow-parallel-runners ./...'
      # authn/oidc and environment/microvm are separate opt-in adapter modules,
      # sharing the root config.
      - 'cd authn/oidc && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners ./...'
      - 'cd environment/microvm && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners ./...'
      - 'cd integration/microvm && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners ./...'
      # provider/ submodules — each its own module; sharing the ROOT
      # golangci config so the depguard allowlists stay the single source of truth.
      - 'cd provider/ssefilter && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners ./...'
      - 'cd provider/anthropic && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners ./...'
      - 'cd provider/openai && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners ./...'
      - 'cd provider/openaichat && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners ./...'

  vuln:
    desc: |
      Run govulncheck over the root module + the engine module (manual / CI
      target — NOT part of `task test`: it needs the network to fetch the Go
      vulnerability database, like `task e2e`/`task bench` are excluded). It
      reports only REACHABLE vulnerabilities (call-graph analysis). Pinned via
      `go run` (not a require), the same pin as the `vuln` CI job.

      govulncheck has no native allowlist, so the JSON stream is filtered through
      .github/scripts/govulncheck-gate.go (a `go run` filter — no jq/external
      tool): it fails on any NEW reachable vuln while accepting a documented
      allowlist. The ROOT module allowlist is EMPTY (the toolhive v0.31.0 bump
      pulled a fixed docker/docker, clearing GO-2026-4887/4883/5617/5668/5746);
      the ENGINE module is STRICT (no allowlist). `pipefail` + the gate's
      fail-closed checks make a govulncheck error a hard fail, never a vacuous
      pass. Supply-chain hygiene that travels with the engine library when
      the downstream consumer pins it. See issue #118.
    cmds:
      # `set -o pipefail` per cmd: go-task does NOT enable it, so without it a
      # mid-scan govulncheck crash (after the JSON `config` preamble) would let
      # the gate see zero findings and pass green. pipefail propagates the
      # govulncheck failure, matching the CI job.
      - cmd: set -o pipefail; go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 -format json ./... | go run .github/scripts/govulncheck-gate.go # v1.8.0 — no allowlist (toolhive v0.31.0 cleared the docker/docker vulns)
      # engine/ is a separate module — `./...` from the root does NOT cross the
      # module boundary, so its scan is a second invocation against engine/go.mod.
      # No allowlist: the engine library's closure is clean and must stay clean.
      - cmd: set -o pipefail; cd engine && go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 -format json ./... | go run ../.github/scripts/govulncheck-gate.go # v1.8.0
      # Opt-in OIDC and microVM modules: independently scan their sensitive closures.
      - cmd: set -o pipefail; cd authn/oidc && go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 -format json ./... | go run ../../.github/scripts/govulncheck-gate.go # v1.8.0
      - cmd: set -o pipefail; cd environment/microvm && go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 -format json ./... | go run ../../.github/scripts/govulncheck-gate.go # v1.8.0
      # provider/ submodules — each its own module; scan against its
      # own go.mod so the provider library's closure is checked independently.
      - cmd: set -o pipefail; cd provider/ssefilter && go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 -format json ./... | go run ../../.github/scripts/govulncheck-gate.go # v1.8.0
      - cmd: set -o pipefail; cd provider/anthropic && go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 -format json ./... | go run ../../.github/scripts/govulncheck-gate.go # v1.8.0
      - cmd: set -o pipefail; cd provider/openai && go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 -format json ./... | go run ../../.github/scripts/govulncheck-gate.go # v1.8.0
      - cmd: set -o pipefail; cd provider/openaichat && go run golang.org/x/vuln/cmd/govulncheck@v1.8.0 -format json ./... | go run ../../.github/scripts/govulncheck-gate.go # v1.8.0

  lint:fix:
    desc: Run pinned golangci-lint with autofix (parallel-safe) over the root, engine, authn/oidc, and provider modules
    deps: [tools:golangci-lint]
    env:
      GOLANGCI_LINT: "{{.ROOT_DIR}}/.tools/bin/golangci-lint"
    preconditions:
      - sh: test -x "$GOLANGCI_LINT"
        msg: "missing pinned golangci-lint; run: task tools:golangci-lint"
    cmds:
      - '"$GOLANGCI_LINT" run --allow-parallel-runners --fix ./...'
      - 'cd engine && "$GOLANGCI_LINT" run --config ../.golangci.yml --allow-parallel-runners --fix ./...'
      - 'cd authn/oidc && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners --fix ./...'
      - 'cd environment/microvm && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners --fix ./...'
      - 'cd provider/ssefilter && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners --fix ./...'
      - 'cd provider/anthropic && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners --fix ./...'
      - 'cd provider/openai && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners --fix ./...'
      - 'cd provider/openaichat && "$GOLANGCI_LINT" run --config ../../.golangci.yml --allow-parallel-runners --fix ./...'

  test:docs-only-classifier:
    desc: Run the offline CI path-classifier and workflow-wiring tests
    cmds:
      - bash .github/scripts/docs-only-changes_test.sh
      - bash .github/scripts/docs-only-workflow_test.sh
      - bash .github/scripts/relevant-changes_test.sh
      - bash .github/scripts/relevant-changes-workflow_test.sh

  lint:actions:
    desc: |
      Lint all GitHub Actions workflows with actionlint (pinned via `go run`, so no
      preinstalled binary is needed). Catches expression-context errors, bad `uses:`
      refs, and shell issues in `run:` blocks. Runs the empty-expression template guard
      and the performance-dashboard noindex guard plus the Deslop advisory-workflow
      contract test, so a single `task lint:actions` covers the whole Actions surface.
    cmds:
      # -ignore: actionlint's latest release (v1.7.12, 2026-03) predates the `$/`
      # self-repository `uses:` syntax GitHub shipped in 2026-07, so it rejects a valid
      # ref as "invalid format". Upstream request: rhysd/actionlint#711. Drop the flag
      # when it lands — it is scoped to that one message, so every other `uses:` error
      # still fails the build.
      - go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12 -ignore 'specifying action "\$/.*" in invalid format'
      - task: lint:action-templates
      - task: test:workspace-infrastructure
      - bash .github/scripts/ensure-perf-dashboard-noindex_test.sh
      - bash .github/scripts/deslop-workflow_test.sh
      - bash .github/scripts/microvm-ci-release_test.sh
      - sh .github/scripts/release-tag-guard_test.sh
      - sh .github/scripts/resolve-main-build_test.sh
      - python3 .github/scripts/instruction-files_test.py
      - python3 .github/scripts/playwright-ci_test.py
      - python3 .github/scripts/ci-gate_test.py

  lint:action-templates:
    desc: |
      Reject a LIVE empty GitHub-expression placeholder in a PARSED field of any
      workflow/action manifest under .github/ — the self-inflicted-parse-error guard
      (issue #70). GitHub EVALUATES expression placeholders inside parsed action.yml /
      workflow scalars (name, description, input defaults, output values), and an EMPTY
      one is a hard parse error ("An expression was expected") that makes the action fail
      to LOAD and aborts every run referencing it. It excludes YAML comment lines (never
      evaluated) and ignores valid non-empty expressions.
    cmds:
      - bash .github/actions/check-action-templates.sh

  fmt:
    desc: Format Go code (gofmt + goimports if available)
    cmds:
      - gofmt -w .
      - cmd: command -v goimports >/dev/null 2>&1 && goimports -w -local {{.PKG}} . || echo "goimports not found; skipping (install:go install golang.org/x/tools/cmd/goimports@latest)"
        silent: true

  fmt:check:
    desc: Fail if any Go file is not gofmt-clean
    cmds:
      - cmd: test -z "$(gofmt -l .)" || { echo "gofmt needs to run on:"; gofmt -l .; exit 1; }

  tidy:module:
    desc: Tidy one module with GOWORK=off, without workspace synchronization
    requires:
      vars: [MODULE]
    preconditions:
      - sh: '{{if has .MODULE .GO_MODULES}}true{{else}}false{{end}}'
        msg: 'MODULE must be one of: {{join ", " .GO_MODULES}}'
    cmds:
      - cd {{.MODULE | shellQuote}} && GOWORK=off go mod tidy

  tidy:
    desc: Tidy root and every nested module, including standalone adapters
    cmds:
      - go mod tidy
      - go work sync
      - cd engine && GOWORK=off go mod tidy
      - cd internal/adaptersupport && GOWORK=off go mod tidy
      - cd contracts/gen/go/mecatl/driver && GOWORK=off go mod tidy
      - cd adapters && GOWORK=off go mod tidy
      # OIDC resolves its published engine baseline independently of the workspace.
      - cd authn/oidc && GOWORK=off go mod tidy
      # The microVM runtime is isolated in its own module; its tools-tag anchor
      # retains the future runtime dependency without linking it by default.
      - cd environment/microvm && GOWORK=off go mod tidy
      - cd integration/microvm && GOWORK=off go mod tidy
      # All provider modules now use resolvable standalone dependencies. The
      # OpenAI-family modules pin the ssefilter module to an immutable revision
      # until the provider module release tags are cut.
      - cd provider/ssefilter && GOWORK=off go mod tidy
      - cd provider/anthropic && GOWORK=off go mod tidy
      - cd provider/openai && GOWORK=off go mod tidy
      - cd provider/openaichat && GOWORK=off go mod tidy

  generate:timezones:
    desc: Refresh the client timezone catalog from the active Go toolchain
    cmds:
      # Explicit maintenance only: compiler upgrades do not require a catalog refresh.
      # Record the active Go version/archive checksum as provenance, not a toolchain pin.
      # The catalog contains names, not the runtime's DST rules.
      - GOWORK=off go run ./internal/timezonegen/cmd/timezonegen --output cmd/mecatui/internal/timezones/zones.json

  generate:
    desc: Regenerate Go and TypeScript contracts and configuration reference
    cmds:
      # Regenerates the gRPC contracts — the harness API (contracts/proto/
      # mecatl/v1) AND the store-driver protocol (contracts/proto/mecatl/
      # driver/v1) — into contracts/gen (never hand-edit the output). The buf
      # invocation mirrors the downstream consumer's house setup (buf generate against the
      # repo-root buf.gen.yaml writing into contracts/gen); the existence
      # guard keeps `task ci` working on a partial checkout.
      - cmd: |
          if [ -f buf.gen.yaml ] && [ -d contracts/proto ]; then
            command -v buf >/dev/null 2>&1 || { echo "buf not found; install: https://buf.build/docs/installation"; exit 1; }
            buf generate
            buf generate --template buf.gen.ts.yaml
          else
            echo "skip generate: buf.gen.yaml and/or contracts/proto not present"
          fi
        silent: true
      # Regenerate the committed configuration-reference + settings.yaml skeleton
      # from the permconfig schema (the CI freshness gate enforces this).
      - task: docs:configref

  docs:configref:
    desc: Regenerate the committed config-init skeleton + rendered configuration reference from the permconfig schema
    cmds:
      # The generator harvests the permconfig schema's field doc-comments (go/ast) and
      # reflects over the *Section structs, emitting the TWO committed artifacts both
      # surfaces (config init + the reference page) read. go/ast stays in this
      # build-time program — the shipped mecated binary embeds the skeleton. The CI
      # docs job diffs the regenerated artifacts against these committed files and
      # fails on drift. Never hand-edit either output.
      - go run ./internal/configgen/cmd/configref --skeleton internal/configgen/settings.skeleton.yaml --reference user-docs/reference/configuration.md

  docs:grpc-ref:
    desc: Regenerate the committed gRPC schema reference from the public Harness and Schedule protobuf contracts
    cmds:
      - cmd: |
          command -v buf >/dev/null 2>&1 || { echo "buf not found; install: https://buf.build/docs/installation"; exit 1; }
          buf generate --template buf.gen.grpc-docs.yaml \
            --path contracts/proto/mecatl/v1/harness.proto \
            --path contracts/proto/mecatl/v1/schedule.proto
        silent: true

  docs:server-cli:
    desc: Generate the server CLI reference from trusted help with operator environment overrides removed
    cmds:
      - python3 scripts/server-cli-reference.py

  docs:server-cli:check:
    desc: Check server CLI reference freshness without modifying its output
    cmds:
      - python3 scripts/server-cli-reference.py --check

  docs:check:
    desc: Gate instruction-file hygiene, executable operations examples, and doc link health with matlatl (strict — broken links/anchors, orphans, unreachable)
    cmds:
      - python3 .github/scripts/instruction-files.py
      - go test ./cmd/mecated -run '^TestSessionStorageContinuity_Scenario9_ServiceExamplesExecuteConfiguredArgs$'
      - go run github.com/stacklok/matlatl/cmd/matlatl@v0.0.11 check . --strict

  docs:model:
    desc: Re-render & validate the modelith domain model (edit the .yaml, never the .md)
    cmds:
      # modelith renders docs/architecture/mecatl.modelith.md from its .yaml source
      # and lints the model. Pinned to the release the CI domain-model gate runs
      # (the stacklok/modelith action's default `version` in
      # .github/workflows/ci.yml); completeness=error mirrors CI exactly.
      - go run github.com/stacklok/modelith/cmd/modelith@v0.4.0 render docs/architecture/mecatl.modelith.yaml
      - go run github.com/stacklok/modelith/cmd/modelith@v0.4.0 lint --completeness error docs/architecture/mecatl.modelith.yaml

  docs:
    desc: Refresh generated references and gate doc links (matlatl) — run before committing doc changes
    cmds:
      - task: docs:configref
      - task: docs:grpc-ref
      - task: docs:server-cli
      - task: sdk:docs
      - task: docs:check

  ci:
    desc: Full local CI gate (tidy, fmt, lint, race test, build)
    cmds:
      - task: tidy
      - task: fmt
      - task: lint
      - task: test:race
      - task: build

  all:
    desc: Alias for the ci task
    cmds:
      - task: ci