docs(plan): plan V8 service base and ADR-019 (proposed)

.envrc

@@ -10,13 +10,23 @@
 strict_env
 watch_file .mise.toml
 watch_file pyproject.toml
+watch_file mise.version
+watch_file mise.lock
 # End SECTION: strict evaluation and watched inputs
 
 # === SECTION: repository environment (managed) ===
 # Source: computed:nearest-pyproject-via-direnv-find_up + template
 PROJECT_ROOT="$(find_up pyproject.toml)"
 PROJECT_ROOT="${PROJECT_ROOT%/*}"
-VENV_DIR="${PROJECT_ROOT}/.venv"
+# A nested standalone checkout never inherits an enclosing repository's tools.
+# A member checked out as a submodule shares its Git superproject runtime, the
+# same root its Makefile resolves (flext-x8gn6).
+RUNTIME_ROOT="$(git -C "${PROJECT_ROOT}" rev-parse --show-superproject-working-tree)"
+RUNTIME_ROOT="${RUNTIME_ROOT:-${PROJECT_ROOT}}"
+runtime_parent="$(cd "${RUNTIME_ROOT}/.." && pwd -P)"
+export GIT_CEILING_DIRECTORIES="${runtime_parent}"
+export MISE_CEILING_PATHS="${runtime_parent}"
+VENV_DIR="${RUNTIME_ROOT}/.venv"
 PROJECT_STATE_ROOT="${PROJECT_ROOT%/*}/.flext-runtime/${PROJECT_ROOT##*/}"
 # Scratch never lives inside a versioned tree: the home scratch root mirrors
 # the absolute checkout path so a sandbox is never a tracked scope of any
@@ -64,8 +74,134 @@ case "${MISE_STORAGE_ROOT}" in
   *) log_error "MISE_DATA_DIR must be absolute"; return 1 ;;
 esac
 export MISE_DATA_DIR="${MISE_STORAGE_ROOT}"
+mise_pin_file="${PROJECT_ROOT}/mise.version"
+if [[ ! -s "${mise_pin_file}" ]]; then
+  log_error "missing or empty ${mise_pin_file}; make upg records the Mise release"
+  return 1
+fi
+mise_release="$(<"${mise_pin_file}")"
+if [[ ! "${mise_release}" =~ ^[0-9]+(\.[0-9]+){2}$ ]]; then
+  log_error "${mise_pin_file} must contain a resolved Mise release"
+  return 1
+fi
+mise_runtime="${MISE_STORAGE_ROOT}/bootstrap/mise-${mise_release}"
+if [[ "${OS:-}" == "Windows_NT" ]]; then
+  mise_runtime="${mise_runtime}.exe"
+fi
+if [[ ! -x "${mise_runtime}" ]]; then
+  log_error "missing pinned Mise runtime ${mise_runtime}; run make setup"
+  return 1
+fi
+# Read installed tool paths through the pinned runtime. Shared shims can belong
+# to an older host Mise that cannot read this repository's lockfile version.
+# Reuse setup's isolated environment; activation never installs or resolves.
+if mise_bin_paths="$(
+  scratch="$(mktemp -d "${PROJECT_SCRATCH}/mise-activation.XXXXXX")" || exit $?
+  trap 'find "${scratch}" -depth -delete' EXIT
+  mkdir -p "${scratch}/home" "${scratch}/home" "${scratch}/appdata" "${scratch}/appdata" "${scratch}/xdg-config" "${scratch}/xdg-data" "${scratch}/xdg-cache" "${scratch}/xdg-state" "${scratch}/config" "${scratch}/tmp" "${scratch}/." "${scratch}/system-config" "${scratch}/system-data" "${scratch}/system-installs" "${scratch}/system-shims" "${scratch}/tmp" "${scratch}/tmp" "${scratch}/tmp" || exit $?
+: > "${scratch}/global-config.toml" || exit $?
+: > "${scratch}/system-config/config.toml" || exit $?
+: > "${scratch}/gitconfig" || exit $?
+: > "${scratch}/netrc" || exit $?
+if env -i \
+'GIT_CONFIG_NOSYSTEM=1' \
+'GIT_TERMINAL_PROMPT=0' \
+'LANG=C' \
+'LC_ALL=C' \
+'MISE_SAFE=1' \
+'MISE_PARANOID=true' \
+'MISE_QUIET=1' \
+'MISE_NO_ENV=1' \
+'MISE_NO_HOOKS=1' \
+'MISE_AUTO_ENV=false' \
+'MISE_AUTO_INSTALL=false' \
+'MISE_EXEC_AUTO_INSTALL=false' \
+'MISE_TASK_RUN_AUTO_INSTALL=false' \
+'MISE_AUTO_UPDATE=false' \
+'MISE_HTTP_RETRIES=0' \
+'MISE_NETRC=false' \
+'MISE_NOT_FOUND_AUTO_INSTALL=false' \
+'MISE_NOT_FOUND_SYSTEM_FALLBACK=false' \
+'MISE_OVERRIDE_CONFIG_FILENAMES=.mise.toml' \
+'MISE_OVERRIDE_TOOL_VERSIONS_FILENAMES=none' \
+'MISE_GITHUB_GH_CLI_TOKENS=false' \
+'MISE_GITHUB_USE_GIT_CREDENTIALS=false' \
+'MISE_GITHUB_OAUTH_CLIENT_ID=' \
+'MISE_GITHUB_OAUTH_EXPORT_ENV=' \
+'MISE_GITHUB_OAUTH_OPEN_BROWSER=false' \
+'MISE_LOCKFILE=true' \
+'MISE_LOCKED=true' \
+'MISE_LOCKFILE_PLATFORMS=linux-x64,linux-arm64,macos-x64,macos-arm64,windows-x64' \
+"HOME=${scratch}/home" \
+"USERPROFILE=${scratch}/home" \
+"APPDATA=${scratch}/appdata" \
+"LOCALAPPDATA=${scratch}/appdata" \
+"XDG_CONFIG_HOME=${scratch}/xdg-config" \
+"XDG_DATA_HOME=${scratch}/xdg-data" \
+"XDG_CACHE_HOME=${scratch}/xdg-cache" \
+"XDG_STATE_HOME=${scratch}/xdg-state" \
+"NETRC=${scratch}/netrc" \
+"GIT_CONFIG_GLOBAL=${scratch}/gitconfig" \
+"MISE_NETRC_FILE=${scratch}/netrc" \
+"MISE_GLOBAL_CONFIG_FILE=${scratch}/global-config.toml" \
+"MISE_CONFIG_DIR=${scratch}/config" \
+"MISE_TMP_DIR=${scratch}/tmp" \
+"MISE_GLOBAL_CONFIG_ROOT=${scratch}/." \
+"MISE_SYSTEM_CONFIG_DIR=${scratch}/system-config" \
+"MISE_SYSTEM_CONFIG_FILE=${scratch}/system-config/config.toml" \
+"MISE_SYSTEM_DATA_DIR=${scratch}/system-data" \
+"MISE_SYSTEM_INSTALLS_DIR=${scratch}/system-installs" \
+"MISE_SYSTEM_SHIMS_DIR=${scratch}/system-shims" \
+"TMPDIR=${scratch}/tmp" \
+"TMP=${scratch}/tmp" \
+"TEMP=${scratch}/tmp" \
+"MISE_DATA_DIR=${MISE_STORAGE_ROOT}" \
+"MISE_CACHE_DIR=${MISE_STORAGE_ROOT}/cache" \
+"MISE_STATE_DIR=${MISE_STORAGE_ROOT}/state" \
+"MISE_INSTALLS_DIR=${MISE_STORAGE_ROOT}/installs" \
+"MISE_SHIMS_DIR=${MISE_STORAGE_ROOT}/shims" \
+"UV_CACHE_DIR=${MISE_STORAGE_ROOT}/uv-cache" \
+"PATH=${PATH}" \
+    "GIT_CEILING_DIRECTORIES=${runtime_parent}" \
+    "MISE_CEILING_PATHS=${runtime_parent}" \
+    "MISE_TRUSTED_CONFIG_PATHS=${PROJECT_ROOT}" \
+    "MISE_OFFLINE=true" \
+    "${mise_runtime}" bin-paths >"${scratch}/paths" 2>"${scratch}/stderr"; then
+    cat "${scratch}/stderr" >&2
+  else
+    mise_status=$?
+    cat "${scratch}/stderr" >&2
+    cat "${scratch}/paths" >&2
+    exit "${mise_status}"
+  fi
+  if [[ -s "${scratch}/stderr" ]]; then
+    log_error "Mise emitted diagnostics during activation; run make setup"
+    exit 1
+  fi
+  cat "${scratch}/paths"
+)"; then
+  :
+else
+  mise_status=$?
+  return "${mise_status}"
+fi
+if [[ -z "${mise_bin_paths}" ]]; then
+  log_error "Mise returned no installed tool paths; run make setup"
+  return 1
+fi
+mise_paths=()
+while IFS= read -r runtime_bin; do
+  if [[ "${runtime_bin}" != /* || ! -d "${runtime_bin}" ]]; then
+    log_error "Mise returned an unavailable tool directory ${runtime_bin}; run make setup"
+    return 1
+  fi
+  mise_paths+=("${runtime_bin}")
+done <<< "${mise_bin_paths}"
 export MISE_SHIMS_DIR="${MISE_STORAGE_ROOT}/shims"
 PATH_add "${MISE_SHIMS_DIR}"
+for ((index=${#mise_paths[@]}-1; index>=0; index--)); do
+  PATH_add "${mise_paths[index]}"
+done
 # End SECTION: mise activation
 
 # === SECTION: configured paths (managed) ===

.github/workflows/ci-matrix.yml

@@ -42,6 +42,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       CI: Y
+      GITHUB_TOKEN: ${{ github.token }}
     strategy:
       fail-fast: false
       matrix:
@@ -54,8 +55,6 @@ jobs:
           # token into .git/config would expose it to every later command.
           persist-credentials: false
       - name: Build ${{ matrix.distro }} image
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: >-
           docker build
           -f tests/fixtures/ci/docker/${{ matrix.distro }}.Dockerfile
@@ -66,8 +65,8 @@ jobs:
         env:
           CI: Y
         run: |
-          docker run --rm -e CI=Y ci-matrix-${{ matrix.distro }} make help
-          docker run --rm -e CI=Y ci-matrix-${{ matrix.distro }} make check
+          docker run --rm -e CI=Y -e GITHUB_TOKEN ci-matrix-${{ matrix.distro }} make help
+          docker run --rm -e CI=Y -e GITHUB_TOKEN ci-matrix-${{ matrix.distro }} make check
           # ci-matrix proves bootstrap + check across distros; it never runs make test.
   # End SECTION: distro-matrix
 
@@ -77,6 +76,7 @@ jobs:
     runs-on: macos-latest
     env:
       CI: Y
+      GITHUB_TOKEN: ${{ github.token }}
     steps:
       - uses: actions/checkout@v7
         with:
@@ -101,6 +101,7 @@ jobs:
     runs-on: windows-latest
     env:
       CI: Y
+      GITHUB_TOKEN: ${{ github.token }}
     steps:
       - uses: actions/checkout@v7
         with:

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ name: CI
       - main
       - 0.12.0-dev
       - 0.20.0-dev
-    types: [opened, synchronize, reopened, ready_for_review]
+    types: [opened, synchronize, reopened, ready_for_review, edited]
   workflow_call:
     secrets:
       CI_DEPENDENCIES_APP_ID:
@@ -56,6 +56,7 @@ jobs:
     timeout-minutes: 60
     env:
       CI: Y
+      GITHUB_TOKEN: ${{ github.token }}
     steps:
       - name: Checkout
         uses: actions/checkout@v7
@@ -127,18 +128,12 @@ jobs:
       # once, before any gate runs.
       - name: Normalize checkout modes
         run: chmod -R go-w .
-      # make setup is the only toolchain installer. It bootstraps the newest
-      # released Mise, installs the committed fleet toolchain, publishes that
-      # environment through GITHUB_PATH, and prepares the project runtime.
+      # make setup is the frozen installer. It bootstraps the committed Mise
+      # release and installs the fleet toolchain from the committed
+      # mise.lock and the dependencies frozen from the committed uv.lock,
+      # publishes that environment through GITHUB_PATH, and prepares the
+      # project runtime. CI never runs `make upg`: it never re-resolves.
       - name: setup (blocking)
-        # Why (resumption-f1 2026-09-11): GitHub-hosted runners share egress
-        # IPs, so the unauthenticated 60 req/h REST budget is exhausted before
-        # mise finishes resolving the moving @latest backends (observed 403 on
-        # beads/waza: setup died before any gate). The job token authenticates
-        # resolution without changing the moving-release toolchain contract.
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          MISE_GITHUB_TOKEN: ${{ github.token }}
         # Why (flext-v4p5): explicit CI=Y on every make invocation (job env is not enough for matrix/docker parity).
         run: CI=Y make setup
       - name: gen fixed point (blocking)
@@ -147,33 +142,24 @@ jobs:
         # sibling repos — unauthenticated fetches fail with "docs generation
         # source state is absent or unauthenticated". The job token
         # authenticates those reads without changing the toolchain contract.
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          MISE_GITHUB_TOKEN: ${{ github.token }}
         run: |
           CI=Y make gen
           git status --short
-          test -z "$(git status --porcelain --untracked-files=all)"
+          test -z "$(git status --porcelain --untracked-files=all --ignore-submodules=none)"
 
-      # Setup syncs against the committed lock and refreshes it in place (`uv
-      # sync`); the fleet runs unlocked, so the deps audit proves the resolved
-      # graph instead of preserving a frozen snapshot.
+      # Setup installs frozen from the committed uv.lock (`uv sync --locked`)
+      # and never rewrites it; the deps audit proves that locked graph.
       - name: deps check (blocking)
         run: CI=Y make audit
 
       - name: check (blocking)
         # Why (flext-v4p5): explicit CI=Y on every make invocation (job env is not enough for matrix/docker parity).
         run: CI=Y make check
 
-      # Why (aihub-v01jg): CI=Y runs ONE HALF of the gate set
-      # (lint pyright silent-failure deferred-self-reference security markdown loc-cap boundary runtime-census namespace tier-whitelist index-declarations smells codemod layout canonical-alias direnv duplication); the complement
-      # (pyrefly mypy) is owned by
-      # CI=N and, without this step, ran on developer
-      # machines only. That split let real defects reach main twice: five
-      # missing-attribute errors and an inconsistent-inheritance error, each
-      # green in CI and red locally. The two contexts are strict complements by
-      # construction, so running both here costs one extra pass and closes the
-      # hole rather than trusting everyone to run the other half by hand.
+      # Both blocking steps derive from the same active default universe.
+      # CI=Y runs lint pyright silent-failure deferred-self-reference security markdown loc-cap tier-whitelist index-declarations smells layout canonical-alias direnv.
+      # CI=N runs pyrefly mypy.
+      # The partitions are disjoint and together execute every active gate.
       - name: check complement (blocking)
         run: CI=N make check
 
@@ -182,7 +168,7 @@ jobs:
       - name: Candidate cleanliness (blocking)
         run: |
           git status --short
-          test -z "$(git status --porcelain --untracked-files=all)"
+          test -z "$(git status --porcelain --untracked-files=all --ignore-submodules=none)"
   # End SECTION: ci job
 
   # === SECTION: release-plan job (managed) ===
@@ -199,6 +185,7 @@ jobs:
     timeout-minutes: 30
     env:
       CI: Y
+      GITHUB_TOKEN: ${{ github.token }}
     steps:
       - name: Checkout
         uses: actions/checkout@v7
@@ -264,10 +251,6 @@ jobs:
           rm -f "$key_path"
 
       - name: Boot
-        # Toolchain resolution needs the same authenticated API budget as ci.
-        env:
-          GITHUB_TOKEN: ${{ github.token }}
-          MISE_GITHUB_TOKEN: ${{ github.token }}
         run: CI=Y make setup
       - name: Release plan and guard
         env:

.gitignore

@@ -26,11 +26,9 @@
 !.opencode/**
 !/config/
 !.claude/CLAUDE.md
-!.claude/settings.json
 !.agents/
 !.agents/**
 .agents/skills/*/report.json
-!.claude/settings.local.json
 
 # Dispatcher-based command surface (Make SSOT)
 !scripts/
@@ -56,19 +54,24 @@ scripts/maintenance/
 !.taplo.toml
 !pyrefly.toml
 !poetry.lock
+!uv.lock
 !ruff-shared.toml
 
-# uv lockfile is never tracked
-uv.lock
-**/uv.lock
-
 # mise toolchain pinning
 !.mise.toml
+!mise.lock
+!mise.version
+!.mise.lock
 !.python-version
-mise.lock
-.mise.lock
-**/mise.lock
-**/.mise.lock
+
+# mise native dependency graphs
+!/.mise/
+/.mise/*
+!/.mise/locks/
+!/.mise/locks/**
+/.mise/locks/*.local/
+/mise*.local.lock
+/.mise*.local.lock
 
 # Docker configuration
 !.dockerignore
@@ -140,7 +143,9 @@ mise.lock
 */.hooks.json.agents-governance.json
 .claude/*.agents-governance.json
 .gemini/*.agents-governance.json
+.claude/settings.json
 .claude/settings.local.json
+.gemini/settings.json
 
 # Operator-private local config overrides
 /config/codegen-overrides.local.yaml
@@ -388,9 +393,6 @@ legado/
 *.tpl.rej
 
 # --- codegen conform: generated runtime ignores ---
-mise.lock
-.mise.lock
-**/.mise.lock
 .direnv/
 .reports/
 .venv
@@ -464,7 +466,6 @@ CLAUDE.local.md
 !.github/scripts/
 !.github/scripts/check-beads-policy.sh
 !.github/scripts/check-cqrs-compliance.sh
-!.github/scripts/install-git-hooks.sh
 !.github/scripts/flext-law-loop.sh
 !tests/fixtures/
 !tests/fixtures/ci/