agentic-team 0.0.0-stage → 6.1.0

package/template/.orchestra/stacks/_repo/setup.sh

@@ -0,0 +1,1109 @@
+#!/usr/bin/env bash
+# Repo-level configuration, shared by every stack. Run once, after the app
+# scaffolds, with the app directory names as arguments.
+#
+# These files are what turn the conventions from advice into enforcement.
+# Without them the rules are prose an agent may or may not follow.
+set -euo pipefail
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)"
+# shellcheck source=../_lib/common.sh
+source "$LIB/common.sh"
+
+MODE="standalone"
+case "${1:-}" in
+  --standalone) MODE="standalone"; shift ;;
+  --workspace)  MODE="workspace";  shift ;;
+esac
+STANDALONE=0
+[ "$MODE" = "standalone" ] && STANDALONE=1
+
+# Everything below writes repo-relative paths, and `git config core.hooksPath`
+# resolves from the repo root. Running from a subdirectory would scatter config
+# where git never looks — hooks configured, hooks never fire, no error.
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || die "not inside a git repository"
+cd "$REPO_ROOT"
+
+APPS=("$@")
+[ ${#APPS[@]} -gt 0 ] || die "usage: setup.sh [--standalone|--workspace] <app-dir> [app-dir...]"
+
+mkdir -p .github/workflows
+
+# ── CI ────────────────────────────────────────────────────────────────────
+# The verification gate only means something if it also runs on the PR.
+# Locally it can be skipped; here it cannot.
+#
+# Not uniform: an app with verify.sh runs that (native toolchains), and iOS
+# needs a macOS runner. A single npm matrix would leave native apps
+# permanently red on the check we ask you to make required.
+{
+  cat <<'YML'
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+YML
+  for a in "${APPS[@]}"; do
+    os="ubuntu-latest"
+    kind="node"
+    browser="no"
+    if [ -f "$a/verify.sh" ]; then
+      kind="script"
+      case "$a" in *ios*|*Ios*|*iOS*) os="macos-latest" ;; esac
+      [ -f "$a/project.yml" ] && os="macos-latest"
+    elif [ -f "$a/package.json" ] && grep -q '@vitest/browser' "$a/package.json"; then
+      # Vitest browser mode launches a real browser, which the runner image
+      # does not ship.
+      browser="yes"
+    fi
+    printf '          - { app: %s, os: %s, kind: %s, browser: %s }\n' "$a" "$os" "$kind" "$browser"
+  done
+  cat <<'YML'
+    name: ${{ matrix.app }}
+    defaults:
+      run:
+        working-directory: ${{ matrix.app }}
+    env:
+      # Matches the app's docker-compose.yml. Harmless where there is no
+      # database — it is one unused variable.
+      DATABASE_URL: postgres://postgres:postgres@localhost:55432/app
+    steps:
+      - uses: actions/checkout@__CHECKOUT_REF__
+        with:
+          # The diff-coverage and mutation gates diff against the PR base.
+          # A shallow clone has no base commit to diff against. gitleaks
+          # needs the full history for the same reason — a secret committed
+          # and then removed is still in the history, and still leaked.
+          fetch-depth: 0
+
+      # corepack must come first: setup-node's yarn cache shells out to yarn,
+      # and without corepack that resolves to the runner's global yarn 1.x,
+      # which refuses a project pinned to yarn 4.
+      - name: Enable corepack
+        if: matrix.kind == 'node'
+        run: corepack enable
+
+      - uses: actions/setup-node@__SETUP_NODE_REF__
+        if: matrix.kind == 'node'
+        with:
+          node-version-file: ${{ matrix.app }}/.node-version
+          cache: yarn
+          # setup-node resolves this from the repo root, not from
+          # working-directory. Listing both covers a lockfile per app
+          # (standalone) and a single root lockfile (workspace); it only
+          # errors when neither matches.
+          cache-dependency-path: |
+            yarn.lock
+            ${{ matrix.app }}/yarn.lock
+
+      # --immutable is the point: CI fails rather than silently resolving a
+      # dependency the lockfile does not describe. A workspace keeps its one
+      # lockfile at the root, so install where it actually lives.
+      - name: Install
+        if: matrix.kind == 'node'
+        run: |
+          if [ -f yarn.lock ]; then yarn install --immutable
+          else (cd "$GITHUB_WORKSPACE" && yarn install --immutable); fi
+
+      - name: Install browser
+        if: matrix.browser == 'yes'
+        run: yarn playwright install --with-deps chromium
+
+      # The app's own compose file rather than a job-level `services:` block:
+      # services cannot be made conditional, and this job's matrix includes
+      # macOS runners for the native apps, where service containers do not
+      # exist. Reusing compose also means the postgres version is pinned in
+      # one place and CI runs the same path a developer does.
+      - name: Database
+        if: matrix.kind == 'node'
+        run: |
+          if [ -f docker-compose.yml ]; then
+            docker compose up -d --wait
+          else
+            echo "no docker-compose.yml in this app — skipped"
+          fi
+
+      - name: Verify
+        if: matrix.kind == 'node'
+        run: |
+          yarn typecheck
+          yarn test
+          yarn lint
+          yarn test:coverage
+          # A typecheck is not a build. tsc accepts an app that fails to
+          # bundle, and nothing else here loads the bundler.
+          if yarn run --silent 2>/dev/null | grep -qx 'build'; then yarn build; fi
+          # A known critical vulnerability blocks the merge.
+          yarn npm audit --severity critical
+
+      # The built app, driven in a real browser. Component tests mount one
+      # component in isolation and a typecheck never loads the bundler, so a
+      # broken route or a bundle that throws on load reaches this step and
+      # nothing before it. Guarded on the script being playwright's — an Expo
+      # app's test:e2e is maestro, and belongs in mobile-e2e.yml.
+      - name: End-to-end
+        if: matrix.kind == 'node'
+        run: |
+          if node -e 'const s=require("./package.json").scripts||{};process.exit(/playwright/.test(s["test:e2e"]||"")?0:1)'; then
+            yarn test:e2e
+          else
+            echo "no playwright e2e in this app — skipped"
+          fi
+
+      - uses: actions/upload-artifact@__UPLOAD_REF__
+        if: failure() && matrix.kind == 'node'
+        with:
+          name: playwright-${{ matrix.app }}
+          path: |
+            ${{ matrix.app }}/playwright-report/
+            ${{ matrix.app }}/test-results/
+          if-no-files-found: ignore
+
+      # Two commands that see what typecheck, lint and jest cannot: a native
+      # module off its SDK's compatibility table. Cheap, and the only thing in
+      # CI that catches the defect class that passes every JS test and then
+      # fails on a device.
+      - name: Native dependency check
+        if: matrix.kind == 'node'
+        run: |
+          if yarn run --silent 2>/dev/null | grep -qx 'doctor'; then
+            yarn doctor
+          else
+            echo "no doctor script in this app — skipped"
+          fi
+
+      # The gate that asks about this change rather than the repo's history:
+      # branch coverage of the lines this PR touched. Only meaningful on a PR,
+      # because only a PR has a base to diff against.
+      - name: Coverage of changed lines
+        if: matrix.kind == 'node' && github.event_name == 'pull_request'
+        env:
+          DIFF_COVERAGE_BASE: origin/${{ github.base_ref }}
+        run: |
+          if yarn run --silent 2>/dev/null | grep -q 'test:coverage:diff'; then
+            yarn test:coverage:diff
+          else
+            echo "no test:coverage:diff script in this app — skipped"
+          fi
+
+      # Stryker caches its results here; without the cache every PR pays for
+      # a cold run.
+      - name: Restore mutation cache
+        if: matrix.kind == 'node' && github.event_name == 'pull_request'
+        uses: actions/cache@__CACHE_REF__
+        with:
+          path: ${{ matrix.app }}/reports
+          key: stryker-${{ matrix.app }}-${{ github.sha }}
+          restore-keys: stryker-${{ matrix.app }}-
+
+      # Coverage says the line ran. This says it was checked.
+      - name: Mutation testing (changed files)
+        if: matrix.kind == 'node' && github.event_name == 'pull_request'
+        env:
+          MUTATION_BASE: origin/${{ github.base_ref }}
+        run: |
+          if yarn run --silent 2>/dev/null | grep -q 'test:mutation:diff'; then
+            yarn test:mutation:diff
+          else
+            echo "no test:mutation:diff script in this app — skipped"
+          fi
+
+      - name: Verify (native)
+        if: matrix.kind == 'script'
+        run: ./verify.sh
+YML
+} > .github/workflows/ci.yml
+
+# Resolved now, not written from memory. The tokens above exist because the
+# workflow heredoc is quoted — it has to be, ${{ ... }} is GitHub's syntax,
+# not bash's — so the refs are substituted after the file is written.
+CHECKOUT_REF="$(latest_action_ref actions/checkout v5)"
+SETUP_NODE_REF="$(latest_action_ref actions/setup-node v5)"
+CACHE_REF="$(latest_action_ref actions/cache v4)"
+UPLOAD_ARTIFACT_REF="$(latest_action_ref actions/upload-artifact v4)"
+sed -i.bak \
+  -e "s|@__CHECKOUT_REF__|@${CHECKOUT_REF}|" \
+  -e "s|@__SETUP_NODE_REF__|@${SETUP_NODE_REF}|" \
+  -e "s|@__CACHE_REF__|@${CACHE_REF}|" \
+  -e "s|@__UPLOAD_REF__|@${UPLOAD_ARTIFACT_REF}|" \
+  .github/workflows/ci.yml
+rm -f .github/workflows/ci.yml.bak
+log "ci workflow (${#APPS[@]} apps) — checkout@${CHECKOUT_REF}, setup-node@${SETUP_NODE_REF}, cache@${CACHE_REF}"
+
+# ── Secret scanning ───────────────────────────────────────────────────────
+# The one control on the list that nothing enforced. A committed secret is
+# compromised the moment it is pushed — removing the commit is not the fix,
+# rotating the credential is — so this has to fail before the merge, not
+# after someone notices.
+GITLEAKS_REF="$(latest_action_ref gitleaks/gitleaks-action v2)"
+cat > .github/workflows/secrets.yml <<YML
+name: secrets
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@${CHECKOUT_REF}
+        with:
+          # A secret that was committed and later deleted is still leaked.
+          # Scanning only the tip would miss every one of those.
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@${GITLEAKS_REF}
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+YML
+log "secret scanning workflow (gitleaks@${GITLEAKS_REF}, full history)"
+
+# ── Dependabot ────────────────────────────────────────────────────────────
+# This is the mechanism the whole testing rule exists to serve: a bump
+# arrives as a PR, CI runs the suite, green means safe to merge.
+{
+  cat <<'YML'
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: chore
+YML
+  for a in "${APPS[@]}"; do
+    if [ -f "$a/package.json" ]; then
+      eco="npm"
+    elif [ -f "$a/build.gradle.kts" ] || [ -f "$a/settings.gradle.kts" ]; then
+      eco="gradle"
+    elif [ -f "$a/Package.swift" ]; then
+      # Only real SwiftPM manifests. An XcodeGen project.yml is not one, and
+      # dependabot's swift ecosystem errors on every run without it.
+      eco="swift"
+    else
+      warn "no recognised ecosystem in $a — skipping dependabot entry"
+      continue
+    fi
+    # "." must map to "/", not "/."
+    dir="/${a}"; [ "$a" = "." ] && dir="/"
+    cat <<YML
+
+  - package-ecosystem: ${eco}
+    directory: ${dir}
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      minor-and-patch:
+        update-types: [minor, patch]
+YML
+    # Expo is the exception to "green CI means merge". The SDK pins react,
+    # react-native and every native module, and `expo install` resolves
+    # against that table — so a bump to the registry's latest installs a
+    # version the SDK rejects. Dependabot cannot know that, would file the
+    # same PR every week, and merging one breaks the build. The SDK upgrade
+    # itself is the event that moves these, via `expo install --fix`.
+    if [ "$eco" = "npm" ] && node -e 'const p=require(process.argv[1]);const d={...p.dependencies,...p.devDependencies};process.exit(d.expo?0:1)' "$PWD/$a/package.json" 2>/dev/null; then
+      cat <<'YML'
+    ignore:
+      # Managed by the Expo SDK — move these with `expo install --fix`.
+      - dependency-name: expo
+      - dependency-name: expo-*
+      - dependency-name: react
+      - dependency-name: react-dom
+      - dependency-name: react-native
+      - dependency-name: react-native-*
+      - dependency-name: "@react-native/*"
+      - dependency-name: "@react-native-*/*"
+      - dependency-name: "@sentry/react-native"
+      # jest-expo depends on the jest 29 packages throughout; jest 30 splits
+      # jest-runtime from jest-mock and every suite fails.
+      - dependency-name: jest
+      - dependency-name: jest-expo
+      - dependency-name: "@types/jest"
+      - dependency-name: typescript
+YML
+      # This whole block redirects stdout into dependabot.yml — log to stderr.
+      log "dependabot: expo app in $a — SDK-managed packages ignored" >&2
+    fi
+  done
+} > .github/dependabot.yml
+log "dependabot config"
+
+# ── Mobile e2e ────────────────────────────────────────────────────────────
+# Separate from ci.yml on purpose. This one builds a native app and boots an
+# emulator; it takes fifteen minutes where the rest of CI takes two, and it
+# only has anything to say when the mobile app changed.
+#
+# It is the layer that is not optional on mobile: jest-expo renders components
+# in Node against mocked native modules, so a missing native dependency or an
+# SDK mismatch passes the entire JS suite and fails on a device.
+EXPO_APP=""
+for a in "${APPS[@]}"; do
+  if [ -f "$a/package.json" ] && node -e 'const p=require(process.argv[1]);const d={...p.dependencies,...p.devDependencies};process.exit(d.expo?0:1)' "$PWD/$a/package.json" 2>/dev/null; then
+    EXPO_APP="$a"
+    break
+  fi
+done
+
+if [ -n "$EXPO_APP" ]; then
+  SETUP_JAVA_REF="$(latest_action_ref actions/setup-java v5)"
+  EMULATOR_REF="$(latest_action_ref reactivecircus/android-emulator-runner v2)"
+  UPLOAD_REF="$(latest_action_ref actions/upload-artifact v4)"
+  {
+    cat <<YML
+name: mobile e2e
+
+# Android on every pull request that touches the app — an ubuntu runner is
+# cheap. iOS on main, because a macOS runner costs roughly ten times as much
+# per minute and the two rarely diverge on the same day.
+on:
+  pull_request:
+    paths: ["${EXPO_APP}/**"]
+  push:
+    branches: [main]
+
+concurrency:
+  group: mobile-e2e-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  android:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    defaults:
+      run:
+        working-directory: ${EXPO_APP}
+    env:
+      # A debug e2e build has no Sentry credentials and must not fail for
+      # want of them. Sentry's Xcode phase gates on this exact variable and
+      # kills the build with exit 65 otherwise.
+      SENTRY_DISABLE_AUTO_UPLOAD: "true"
+    steps:
+      - uses: actions/checkout@${CHECKOUT_REF}
+
+      - run: corepack enable
+        working-directory: .
+
+      - uses: actions/setup-node@${SETUP_NODE_REF}
+        with:
+          node-version-file: ${EXPO_APP}/.node-version
+          cache: yarn
+          cache-dependency-path: |
+            yarn.lock
+            ${EXPO_APP}/yarn.lock
+
+      - uses: actions/setup-java@${SETUP_JAVA_REF}
+        with:
+          distribution: temurin
+          # 21, not AGP's minimum of 17: robolectric's stubbed jar for a
+          # recent API level refuses to start on 17 with "Android SDK 36
+          # requires Java 21". AGP accepts anything at or above 17.
+          java-version: "21"
+
+      - name: Install
+        run: |
+          if [ -f yarn.lock ]; then yarn install --immutable
+          else (cd "\$GITHUB_WORKSPACE" && yarn install --immutable); fi
+
+      # Cheap, and it fails before a fifteen-minute build when a native
+      # One script, not a second copy of these steps — the same reasoning as
+      # the ios job below. Two phases because the emulator is the action's to
+      # own: the build happens before it boots, the test inside it.
+      - name: Build
+        run: ./e2e-android.sh build
+
+      - name: Install maestro
+        run: |
+          curl -fsSL https://get.maestro.mobile.dev | bash
+          echo "\$HOME/.maestro/bin" >> "\$GITHUB_PATH"
+
+      - uses: reactivecircus/android-emulator-runner@${EMULATOR_REF}
+        with:
+          api-level: 34
+          arch: x86_64
+          working-directory: ${EXPO_APP}
+          script: ./e2e-android.sh test
+
+      # Maestro writes its failure output here, and reading it is the only
+      # way to tell a broken flow from a broken app.
+      - uses: actions/upload-artifact@${UPLOAD_REF}
+        if: failure()
+        with:
+          name: maestro-android
+          path: ~/.maestro/tests/
+          if-no-files-found: ignore
+
+  ios:
+    # macOS minutes are expensive; main only.
+    if: github.event_name == 'push'
+    runs-on: macos-latest
+    timeout-minutes: 60
+    defaults:
+      run:
+        working-directory: ${EXPO_APP}
+    env:
+      # A debug e2e build has no Sentry credentials and must not fail for
+      # want of them. Sentry's Xcode phase gates on this exact variable and
+      # kills the build with exit 65 otherwise.
+      SENTRY_DISABLE_AUTO_UPLOAD: "true"
+      # CocoaPods reads the Podfile through ruby's default external encoding.
+      # With no locale set that is US-ASCII, and `pod install` dies inside
+      # String#unicode_normalize with "Unicode Normalization not appropriate
+      # for ASCII-8BIT" — then xcodebuild fails with the far less helpful
+      # "sandbox is not in sync with the Podfile.lock". Reproduced on a real
+      # machine; a runner image that happens to set a locale is the image's
+      # choice, not ours.
+      LANG: en_US.UTF-8
+    steps:
+      - uses: actions/checkout@${CHECKOUT_REF}
+
+      - run: corepack enable
+        working-directory: .
+
+      - uses: actions/setup-node@${SETUP_NODE_REF}
+        with:
+          node-version-file: ${EXPO_APP}/.node-version
+          cache: yarn
+          cache-dependency-path: |
+            yarn.lock
+            ${EXPO_APP}/yarn.lock
+
+      # maestro is a JVM application. The android job gets a JDK incidentally,
+      # because gradle needs one; here nothing else does, so without this step
+      # `maestro test` dies on "Unable to locate a Java Runtime" after the
+      # build has already been paid for. A macOS runner image happens to ship
+      # a JDK today — that is the image's choice, not ours.
+      - uses: actions/setup-java@${SETUP_JAVA_REF}
+        with:
+          distribution: temurin
+          java-version: "21"
+
+      - name: Install
+        run: |
+          if [ -f yarn.lock ]; then yarn install --immutable
+          else (cd "\$GITHUB_WORKSPACE" && yarn install --immutable); fi
+
+      # One script, not a second copy of these steps. It carries the
+      # locale, the Sentry opt-out, the JDK check maestro needs and the
+      # Release/--no-bundler reasoning — see the file. Anyone can reproduce a
+      # red e2e by running it, and the orchestrator's own CI runs the same
+      # thing rather than a paraphrase of it.
+      - name: e2e
+        run: ./e2e-ios.sh
+
+
+      # Same reason as the android job: without the run output there is no
+      # way to tell a broken flow from a broken app.
+      - uses: actions/upload-artifact@${UPLOAD_REF}
+        if: failure()
+        with:
+          name: maestro-ios
+          path: ~/.maestro/tests/
+          if-no-files-found: ignore
+YML
+  } > .github/workflows/mobile-e2e.yml
+  log "mobile e2e workflow (android per PR, ios on main) for ${EXPO_APP}"
+  warn "mobile-e2e.yml has never run here — it needs a real emulator and a"
+  warn "native build. Expect to tune signing and the emulator image on its"
+  warn "first run, and fill in .maestro/core-flow.yaml before trusting it."
+fi
+
+# ── Dependency policy, as automation ──────────────────────────────────────
+# The rule says: minor and patch green is a merge, a major gets a human. That
+# only holds if something does the merging — otherwise the PRs pile up and
+# get merged in a batch without anyone reading the majors either.
+#
+# And the other half of the rule — never loosen a test to make a dependency
+# PR green — is exactly what a bot cannot be trusted with, so it is checked
+# rather than asked for.
+# `|| true`: with pipefail, a missing config.yml makes the whole pipeline
+# fail and set -e takes the script down with it. Absent config means the
+# default, not an error.
+# awk, not `grep -A<n>`: the shipped config.yml carries three comment lines
+# between `dependencies:` and `automerge:`, so a fixed window missed the key
+# entirely and every repo silently got "none" while its config said otherwise.
+# This reads to the next top-level key instead, so comments cannot defeat it.
+AUTOMERGE="$(awk '/^  dependencies:/{f=1;next} f && /^[a-z]/{exit} f && /^[[:space:]]*automerge:/{print $2;exit}' "$(git rev-parse --show-toplevel)/.orchestra/config.yml" 2>/dev/null || true)"
+AUTOMERGE="${AUTOMERGE:-none}"
+METADATA_REF="$(latest_action_ref dependabot/fetch-metadata v2)"
+
+cat > .github/workflows/dependabot.yml <<YML
+name: dependabot
+
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  # The half a bot must not decide for itself. A dependency bump that needed a
+  # test changed is a behaviour change wearing a version number — the test was
+  # doing its job, and the fix belongs in our code or the upgrade waits.
+  no-loosened-tests:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@${CHECKOUT_REF}
+        with:
+          fetch-depth: 0
+
+      - name: A dependency PR must not touch tests
+        run: |
+          changed="\$(git diff --name-only "origin/\${{ github.base_ref }}...HEAD" \
+            | grep -E '(\.(test|spec)\.[jt]sx?|/__tests__/|/e2e/|Tests?/.*\.(swift|kt))' || true)"
+          if [ -n "\$changed" ]; then
+            echo "::error::this dependency PR changes tests:"
+            echo "\$changed"
+            echo "Fix our code to match the new behaviour, or hold the upgrade."
+            exit 1
+          fi
+          echo "no test files touched"
+
+  automerge:
+    if: github.actor == 'dependabot[bot]'
+    needs: no-loosened-tests
+    runs-on: ubuntu-latest
+    steps:
+      - id: meta
+        uses: dependabot/fetch-metadata@${METADATA_REF}
+
+      # A major version is the maintainer stating the contract changed, and
+      # some of what changed — default timeouts, retry behaviour, performance
+      # — is invisible to every test. Green means "nothing we assert broke".
+      - name: Flag a major for a human
+        if: steps.meta.outputs.update-type == 'version-update:semver-major'
+        run: |
+          gh pr edit "\$PR" --add-label "needs-human"
+          gh pr comment "\$PR" --body "Major version bump — a human reads the changelog before this merges. Green CI means nothing we assert broke, not that nothing broke."
+        env:
+          PR: \${{ github.event.pull_request.html_url }}
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+
+      # --auto, so it lands only once every required check has passed.
+      - name: Auto-merge minor and patch
+        if: |
+          $([ "$AUTOMERGE" = "minor-and-patch" ] && echo true || echo false) &&
+          (steps.meta.outputs.update-type == 'version-update:semver-minor' ||
+           steps.meta.outputs.update-type == 'version-update:semver-patch')
+        run: gh pr merge --auto --squash "\$PR"
+        env:
+          PR: \${{ github.event.pull_request.html_url }}
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+YML
+log "dependabot policy (automerge: ${AUTOMERGE}, tests protected)"
+[ "$AUTOMERGE" = "none" ] || warn "auto-merge needs 'Allow auto-merge' enabled in repo settings"
+
+# ── Deploy ────────────────────────────────────────────────────────────────
+# Generated for any app that carries a railway.json.
+#
+# The honest shape of safety on Railway: there is no percentage canary. What
+# protects a release is that the previous deployment keeps serving until the
+# new one answers its healthcheck, plus a smoke test against the real URL
+# afterwards, plus putting the last good commit back quickly when it fails.
+#
+# Confidence comes from being able to undo, not from being sure.
+RAILWAY_APPS=()
+for a in "${APPS[@]}"; do
+  [ -f "$a/railway.json" ] && RAILWAY_APPS+=("$a")
+done
+
+if [ ${#RAILWAY_APPS[@]} -gt 0 ]; then
+  DEPLOY_APP="${RAILWAY_APPS[0]}"
+  write_smoke_script
+  cat > .github/workflows/deploy.yml <<YML
+name: deploy
+
+# Only after CI has gone green on main. Deploying on push instead would ship
+# the commit that broke the suite, which is the one moment it matters most.
+on:
+  workflow_run:
+    workflows: [ci]
+    types: [completed]
+    branches: [main]
+
+concurrency:
+  group: deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    if: \${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    environment: production
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@${CHECKOUT_REF}
+        with:
+          ref: \${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      # What to put back if this release turns out bad. Read before
+      # deploying, because afterwards the tag has already moved.
+      - name: Remember the last good deploy
+        id: last
+        run: |
+          git fetch --tags --force
+          prev="\$(git rev-parse -q --verify refs/tags/last-good-deploy || true)"
+          echo "sha=\$prev" >> "\$GITHUB_OUTPUT"
+          echo "previous good deploy: \${prev:-none yet}"
+
+      - run: npm i -g @railway/cli
+
+      - name: Deploy
+        working-directory: ${DEPLOY_APP}
+        run: railway up --service "\$RAILWAY_SERVICE" --ci
+        env:
+          RAILWAY_TOKEN: \${{ secrets.RAILWAY_TOKEN }}
+          RAILWAY_SERVICE: \${{ vars.RAILWAY_SERVICE }}
+
+      # Railway's healthcheck already gates promotion on /ready. This catches
+      # what a readiness probe cannot: a route answering 500, an asset that
+      # 404s, a migration that half-applied.
+      - name: Smoke the deployed URL
+        run: node scripts/smoke.mjs "\$DEPLOY_URL"
+        env:
+          DEPLOY_URL: \${{ vars.DEPLOY_URL }}
+
+      # Railway has no rollback command, so putting the previous commit back
+      # is the rollback. Same path as a normal deploy on purpose — an
+      # untested recovery path is not a recovery path.
+      - name: Roll back
+        if: failure() && steps.last.outputs.sha != ''
+        run: |
+          echo "::error::deploy or smoke failed — restoring \${{ steps.last.outputs.sha }}"
+          git checkout "\${{ steps.last.outputs.sha }}"
+          cd ${DEPLOY_APP} && railway up --service "\$RAILWAY_SERVICE" --ci
+        env:
+          RAILWAY_TOKEN: \${{ secrets.RAILWAY_TOKEN }}
+          RAILWAY_SERVICE: \${{ vars.RAILWAY_SERVICE }}
+
+      # Moved only after the smoke passed, so it always names a release that
+      # was observed working rather than one that merely deployed.
+      - name: Mark this deploy good
+        if: success()
+        run: |
+          git tag -f last-good-deploy "\${{ github.event.workflow_run.head_sha }}"
+          git push -f origin last-good-deploy
+YML
+  log "deploy workflow for ${DEPLOY_APP} (railway, smoke-gated, rollback on failure)"
+  warn "deploy needs: secret RAILWAY_TOKEN, vars RAILWAY_SERVICE and DEPLOY_URL"
+fi
+
+# ── Review labels ─────────────────────────────────────────────────────────
+#
+# The reviewer and the engineer hand a pull request back and forth, and the
+# verdict has to live somewhere GitHub lets the author write. It is not the
+# review state: the same account opens the PR and reviews it, and GitHub
+# refuses to let an author approve their own. A label it will allow, and
+# everything else can read one — a filter, a board, a human scanning the list,
+# and a run picking up after a crash.
+#
+# --force so a re-run updates rather than failing on "already exists". Not
+# fatal without a remote: a repo that has not been pushed yet has nowhere to
+# put a label, and that is not a reason to fail a scaffold.
+if gh auth status >/dev/null 2>&1 && gh repo view >/dev/null 2>&1; then
+  gh label create review:changes-requested -c D93F0B \
+    -d "Reviewer found blocking issues" -f >/dev/null 2>&1 || true
+  gh label create review:approved -c 0E8A16 \
+    -d "Reviewer found nothing blocking" -f >/dev/null 2>&1 || true
+  log "review labels created"
+else
+  warn "no gh remote yet — create the review labels after the first push:"
+  warn "  gh label create review:changes-requested -c D93F0B -f"
+  warn "  gh label create review:approved -c 0E8A16 -f"
+fi
+
+# ── PR template ───────────────────────────────────────────────────────────
+cat > .github/pull_request_template.md <<'MD'
+## What
+
+<!-- One or two sentences. What changed, not how. -->
+
+## Why
+
+<!-- Link the milestone or task. What problem does this close? -->
+
+## Design
+
+<!-- Required for any UI change. Both columns, side by side. -->
+
+| Expected | Implemented |
+|---|---|
+| <!-- designs/<screen>.png --> | <!-- designs/.captures/<phase>.png --> |
+
+<!-- gh cannot upload an image, so both files have to be committed in this
+     branch for the cells to render. If the screen could not be captured, put
+     the reason in the cell — "not captured: no simulator in the session". An
+     empty cell reads as a pass nobody observed. -->
+
+<!-- Any deliberate difference from the design goes here, with the reason.
+     "Close enough" is not a reason. A spacing or a colour that is close is
+     not a difference, it is a defect — see
+     .claude/rules/design-parity.orchestra.md. -->
+
+## Verification
+
+- [ ] typecheck, test, and lint pass locally
+- [ ] tests cover the change, including the failure paths
+- [ ] a11y checklist done for any new or changed component
+- [ ] no hardcoded design values — tokens only
+MD
+log "pr template"
+
+# ── Commit message enforcement ────────────────────────────────────────────
+# Pure bash on purpose: the standalone strategy has no root package.json to
+# hang commitlint off, and this needs to work in every strategy.
+mkdir -p .githooks
+cat > .githooks/commit-msg <<'HOOK'
+#!/usr/bin/env sh
+# Conventional commits. Matches .claude/rules/commit-format.orchestra.md.
+msg_file="$1"
+first_line=$(head -n1 "$msg_file")
+
+case "$first_line" in
+  "Merge "*|"Revert "*|fixup!*|squash!*) exit 0 ;;
+esac
+
+# Accepts both `feat(scope)!:` (Conventional Commits spec, what release-please
+# parses) and `feat!(scope):` (the form in commit-format.orchestra.md).
+pattern='^(feat|fix|refactor|perf|test|chore|docs|style|ci|build|revert)!?(\([a-z0-9./-]+\))?!?: .{1,}$'
+
+# A squash-merge takes its message from the pull request title, and a task PR
+# is titled `#<task-id> - <subject>` so the tracker links it. Without this the
+# repo would reject the commit its own delivery flow produces — see
+# .claude/rules/pull-request.orchestra.md.
+#
+# Deliberately narrow: a task id and a subject, nothing else. It is not a way
+# to opt an ordinary commit out of the convention.
+squashed='^#[A-Za-z0-9_-]+ - .{1,}$'
+
+if ! printf '%s' "$first_line" | grep -qE "$pattern" \
+   && ! printf '%s' "$first_line" | grep -qE "$squashed"; then
+  echo "commit rejected: subject must be <type>(<scope>): <description>" >&2
+  echo "  got: $first_line" >&2
+  echo "  types: feat fix refactor perf test chore docs style ci build revert" >&2
+  echo "  (a squashed task PR may instead be '#<task-id> - <subject>')" >&2
+  exit 1
+fi
+
+if [ ${#first_line} -gt 72 ]; then
+  echo "commit rejected: subject is ${#first_line} chars, max 72" >&2
+  exit 1
+fi
+
+if printf '%s' "$(cat "$msg_file")" | grep -qi '^Co-Authored-By:'; then
+  echo "commit rejected: no Co-Authored-By trailers" >&2
+  exit 1
+fi
+HOOK
+chmod +x .githooks/commit-msg
+
+# Where the hook goes depends on what is already installed.
+#
+# husky owns `.husky/_` and regenerates it on every install (its own
+# `prepare` script), and ships a `.gitignore` inside it — so a hook written
+# there is neither committed nor durable. `.husky/` itself is the supported
+# place for user hooks.
+existing_hooks="$(git config --get core.hooksPath || true)"
+case "$existing_hooks" in
+  ""|".githooks")
+    git config core.hooksPath .githooks
+    log "commit-msg hook installed (.githooks)"
+    ;;
+  .husky/_|.husky)
+    mkdir -p .husky
+    cp .githooks/commit-msg .husky/commit-msg
+    chmod +x .husky/commit-msg
+    rm -f .githooks/commit-msg
+    rmdir .githooks 2>/dev/null || true
+    log "commit-msg hook installed (.husky/commit-msg, husky present)"
+    ;;
+  *)
+    # Someone else's hooks directory. Add to it, never replace it, and never
+    # delete a directory this script did not create.
+    mkdir -p "$existing_hooks"
+    if [ -e "$existing_hooks/commit-msg" ]; then
+      warn "$existing_hooks/commit-msg already exists — left untouched, commit format NOT enforced"
+    else
+      cp .githooks/commit-msg "$existing_hooks/commit-msg"
+      chmod +x "$existing_hooks/commit-msg"
+      log "commit-msg hook added to existing $existing_hooks"
+    fi
+    rm -f .githooks/commit-msg
+    rmdir .githooks 2>/dev/null || true
+    ;;
+esac
+
+# Yarn 4 pins its own release under .yarn/releases, which must be committed or
+# CI has no yarn binary. Everything else under .yarn is a cache.
+if ! grep -q '^\.yarn/' .gitignore 2>/dev/null; then
+  cat >> .gitignore <<'YG'
+
+# yarn — keep the pinned release, ignore the caches
+.yarn/*
+!.yarn/releases
+.pnp.*
+YG
+  log "gitignore: yarn caches ignored, pinned release kept"
+fi
+
+# node_modules at the repo root. Each create tool ignores it inside its own
+# app directory, which is enough for `single` and `standalone` — but a yarn
+# workspace hoists the whole tree to the root, where nothing covered it, and
+# the first `git add -A` stages sixty thousand files.
+if ! grep -q '^node_modules/' .gitignore 2>/dev/null; then
+  cat >> .gitignore <<'NMG'
+
+# dependencies — hoisted here by a workspace, per-app otherwise
+node_modules/
+NMG
+  log "gitignore: node_modules ignored"
+fi
+
+# `.env` is gitignored in every project, always — the security rule says so
+# and, until now, nothing did it. A create tool ignores .env inside its own
+# app directory; nothing covered the repo root or a hand-made app.
+#
+# .env.example is the exception, and it is committed on purpose: it is the
+# only record of what a new machine needs in order to boot.
+if ! grep -q '^\.env$' .gitignore 2>/dev/null; then
+  cat >> .gitignore <<'ENVG'
+
+# secrets never get committed; the example of what is needed always does
+.env
+.env.*
+!.env.example
+ENVG
+  log "gitignore: .env ignored, .env.example kept"
+fi
+
+cat > .editorconfig <<'EC'
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.{kt,kts,swift}]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+EC
+log "editorconfig"
+
+
+# ── Workspace (Turborepo) ─────────────────────────────────────────────────
+# One lockfile at the root, turbo for task orchestration and caching. The
+# per-app yarn setup each stack performs is undone here — a workspace has a
+# single resolution root, and leaving per-app lockfiles behind produces two
+# competing dependency trees.
+if [ "$MODE" = "workspace" ]; then
+  for a in "${APPS[@]}"; do
+    rm -f "$a/yarn.lock" "$a/.yarnrc.yml"
+    rm -rf "$a/.yarn"
+  done
+
+  printf 'nodeLinker: node-modules\n' > .yarnrc.yml
+
+  node -e '
+    const fs = require("fs");
+    const apps = process.argv.slice(1);
+    const pkg = {
+      name: "workspace-root",
+      private: true,
+      workspaces: apps,
+      scripts: {
+        dev: "turbo run dev",
+        build: "turbo run build",
+        test: "turbo run test",
+        lint: "turbo run lint",
+        typecheck: "turbo run typecheck",
+        "test:coverage": "turbo run test:coverage",
+        verify: "turbo run typecheck test lint test:coverage",
+      },
+    };
+    fs.writeFileSync("package.json", JSON.stringify(pkg, null, 2) + "\n");
+  ' "${APPS[@]}"
+
+  cat > turbo.json <<'TURBO'
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**", "!.next/cache/**"] },
+    "typecheck": { "dependsOn": ["^build"] },
+    "lint": {},
+    "test": { "dependsOn": ["^build"] },
+    "test:coverage": { "dependsOn": ["^build"], "outputs": ["coverage/**"] },
+    "dev": { "cache": false, "persistent": true }
+  }
+}
+TURBO
+
+  # turbo writes a cache and a per-task log into .turbo/, at the root and
+  # inside every package. Nothing ignored it, so the first commit carried
+  # turbo-lint.log and a tar.zst cache blob, and every run after it churned
+  # them.
+  if ! grep -q '^\.turbo/' .gitignore 2>/dev/null; then
+    printf '\n# turbo cache and task logs, root and per-package\n.turbo/\n' >> .gitignore
+    log "gitignore: .turbo ignored"
+  fi
+
+  corepack enable >/dev/null 2>&1 || true
+  yarn set version stable >/dev/null 2>&1 || warn "could not pin yarn at the root"
+  yarn add -D turbo@latest >/dev/null 2>&1 || warn "turbo install failed — run 'yarn add -D turbo' at the root"
+  log "workspace wired: yarn workspaces + turborepo (${#APPS[@]} apps)"
+fi
+
+# ── Standalone task runner ────────────────────────────────────────────────
+# The standalone strategy has no root package.json on purpose, so this
+# script takes the place of `npm run`.
+if [ "$STANDALONE" -eq 1 ]; then
+  {
+    cat <<'RUNNER'
+#!/usr/bin/env bash
+# Root task runner. No root package.json by design — each app owns its own.
+#
+#   ./run.sh install            install every app
+#   ./run.sh dev <app>          start one app
+#   ./run.sh test [app]         test one app, or all
+#   ./run.sh lint [app]
+#   ./run.sh typecheck [app]
+#   ./run.sh build [app]
+#   ./run.sh verify [app]       typecheck + test + lint + coverage
+set -euo pipefail
+
+RUNNER
+    printf 'APPS=('
+    for a in "${APPS[@]}"; do printf '"%s" ' "$a"; done
+    printf ')\n'
+    cat <<'RUNNER'
+
+cmd="${1:-}"; shift || true
+target="${1:-}"
+
+# Apps are not all npm. Native mobile forces this strategy, so dispatch on
+# what is actually in the directory. verify.sh is the normalised gate a
+# non-npm app exposes.
+__run() { # task, run from inside the app dir
+  local task="$1"
+  if [ -f verify.sh ]; then
+    case "$task" in
+      install|dev|build) echo "(skipped: $task not defined for a verify.sh app)" ;;
+      *) ./verify.sh ;;
+    esac
+  elif [ -f package.json ]; then
+    case "$task" in
+      install) yarn install ;;
+      *)       yarn "$task" ;;
+    esac
+  else
+    echo "no package.json and no verify.sh — cannot $task" >&2
+    return 1
+  fi
+}
+
+run_in() { # dir, __run, task
+  local dir="$1"; shift
+  [ -d "$dir" ] || { echo "no such app: $dir" >&2; exit 1; }
+  echo "──> $dir: $*"
+  ( cd "$dir" && "$@" )
+}
+
+each() { # script...
+  local failed=()
+  for a in "${APPS[@]}"; do
+    run_in "$a" "$@" || failed+=("$a")
+  done
+  [ ${#failed[@]} -eq 0 ] || { echo "failed: ${failed[*]}" >&2; exit 1; }
+}
+
+# `a && b || c` runs c when b FAILS, not only when a is false — which would
+# run every app's suite because one app's suite went red. Always if/else.
+one_or_all() { # script...
+  if [ -n "$target" ]; then run_in "$target" "$@"; else each "$@"; fi
+}
+
+case "$cmd" in
+  install)   each __run install ;;
+  dev)       [ -n "$target" ] || { echo "usage: ./run.sh dev <app>" >&2; exit 1; }
+             run_in "$target" __run dev ;;
+  test)      one_or_all __run test ;;
+  lint)      one_or_all __run lint ;;
+  typecheck) one_or_all __run typecheck ;;
+  build)     one_or_all __run build ;;
+  verify)
+    for s in typecheck test lint test:coverage; do
+      one_or_all __run "$s"
+    done ;;
+  *)
+    sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//'
+    exit 1 ;;
+esac
+RUNNER
+  } > run.sh
+  chmod +x run.sh
+  log "root run.sh task runner (${#APPS[@]} apps)"
+fi
+
+# Where a design lives, from the first commit rather than from the first
+# argument about it. A phase's `design:` field points in here, lead fetches a
+# URL design into .fetched/, and the capture the PR shows lands in .captures/.
+# Committed, both of them: gh cannot upload an image, so a screenshot that is
+# not in the branch cannot appear in a pull request.
+mkdir -p designs/.captures designs/.fetched
+# git does not track an empty directory, so without these the two folders
+# vanish on the next clone and the first phase with a design has to invent a
+# location — which is how two of them end up disagreeing.
+: > designs/.captures/.gitkeep
+: > designs/.fetched/.gitkeep
+cat > designs/README.md <<'MD'
+# designs
+
+The source of truth for any screen this repo builds.
+
+```
+designs/
+├── <screen>.png     the design. mirrors the screen structure.
+├── .fetched/        a design given as a URL, fetched once when the phase starts
+└── .captures/       what was actually built, so a pull request can show both
+```
+
+A phase points at one with `design:` in its frontmatter — a path in here, or a
+URL. No field means no design, and nothing may infer one from a phase title: a
+check against a guessed design reports a pass nobody earned.
+
+What counts as matching, and what blocks, is in
+`.claude/rules/design-parity.orchestra.md`.
+MD
+log "designs/ (source, fetched, captures) — a design has a home before it is needed"
+
+log "repo config done — CI, dependabot, PR template, commit hook"
+warn "branch protection cannot be set from here. Require the CI check on main in repo settings."