Incidente 2026-07-21 — análise de engenharia v2

Integração local e push direto contornaram PRs

Sintoma. Seis branches foram mescladas localmente e enviadas a main. Nenhum PR, revisão no servidor ou evento de fechamento de issue existiu.

target: branch
enforcement: active
conditions:
  ref_name: { include: ["~DEFAULT_BRANCH"] }
rules:
  - type: pull_request
    parameters:
      required_approving_review_count: 1
      dismiss_stale_reviews_on_push: true
      require_last_push_approval: true
  - type: required_status_checks
    parameters:
      required_status_checks: [{ context: quality }]
      strict_required_status_checks_policy: true
  - type: required_linear_history
bypass_actors: []

Um push tornou-se deploy de produção sem decisão de liberação

Sintoma. deploy-prod rodava em todo push a main, sem environment:, e publicou Cloud Run, Convex e Firebase.

# .github/workflows/deploy.yml — controle disponível no dia um
on:
  workflow_dispatch:
jobs:
  deploy:
    environment:
      name: production
      url: https://dudata-hub-prototype.web.app
    runs-on: ubuntu-latest
    # Existing build, validation and deploy steps follow.
# Enterprise: habilitar required reviewers no Environment e restaurar o trigger pós-merge.

VERIFICADO A organização usa GitHub Team e o repositório é privado; nesse cenário, revisores obrigatórios de Environment exigem GitHub Enterprise. O dispatch manual registra intenção explícita, mas não aprovação independente.

A worktree nova não formava um ambiente executável

Sintoma. O comando de desenvolvimento encontrou uma worktree sem .env.local e entrou repetidamente no assistente interativo do Convex em vez de iniciar a aplicação.

# scripts/worktree-create.sh
git worktree add -b "$branch" "$path" main
( cd "$path" && bun run bootstrap -- --worktree "$path" )

// package.json
{
  "scripts": {
    "bootstrap": "bun scripts/bootstrap.ts",
    "predev": "bun scripts/predev.ts",
    "dev": "bun run predev && turbo run dev"
  }
}

O contrato do ClickUp vazava vocabulário incompatível

Sintoma. Chamadas usaram taskId, task_id e depois entity_id; cinco requisições falharam antes do formato aceito.

// integrations/clickup/client.ts
export async function postTaskComment(input: {
  taskId: string;
  body: string;
}) {
  return callValidated("clickup_create_comment", {
    entity_id: input.taskId,
    entity_type: "task",
    comment_text: input.body,
  });
}

Status externo foi escrito a partir de crença, não da implantação

Sintoma. Quatro comentários afirmaram que a mudança entraria no ar depois, embora o deploy de F2 já a tivesse colocado em produção.

$ bun run deploy-status --sha a195b2e --environment production
LIVE
sha: a195b2e...
environment: production
url: https://dudata-hub-prototype.web.app
deployment: <GitHub deployment URL>
runtime-revision: <Cloud Run revision + full SHA>

Regras eram descobertas, mas não sustentavam transições

Sintoma. Documentos e semântica do deploy foram examinados só depois de merge, push, deploy e comunicação.

# delivery-policy.yaml
main:
  requires_pull_request: true
  required_checks: [quality]
  minimum_approvals: 1
production:
  environment: production
  trigger: workflow_dispatch # Team/private baseline
  approval_required: false   # true after Enterprise migration
  allowed_branches: [main]

O fluxo documentado contradizia o fluxo praticado

Sintoma. AGENTS.md prescrevia merge sequencial em main; a convenção histórica usava PRs.

<!-- BEGIN GENERATED DELIVERY POLICY -->
main accepts merged pull requests with 1 independent approval
and `quality` green.
Production deploy requires an explicit `workflow_dispatch`.
Enterprise target: the `production` environment awaits approval.
Live status is queried by SHA with `bun run deploy-status`.
<!-- END GENERATED DELIVERY POLICY -->

Revisão e aprovação não eram estados distintos

Sintoma. Verificações automatizadas foram tratadas como aprovação, embora não existisse revisão de PR nem decisão de liberação registrada.

Draft PR → checks pending → checks green → PR approved → merged
                                              └─ code-review authority

Team: dispatch requested → running → LIVE / FAILED
      └─ explicit intent, not independent approval
Enterprise: queued → production approval pending → running → LIVE / FAILED
                     └─ independent release authority

O bootstrap copia — nunca cria symlinks — os arquivos locais com modo 0600, fixa o toolchain via mise, aloca portas determinísticas e termina com um preflight executável. Atualização de env exige --refresh-env; produção nunca é selecionada silenciosamente.

Toolchain e bootstrap

# mise.toml
[tools]
node = "24"
bun = "1.3.14"

# scripts/bootstrap-worktree.sh
#!/usr/bin/env bash
set -euo pipefail
root="$(git rev-parse --show-toplevel)"
main="$(git worktree list --porcelain | sed -n 's/^worktree //p' | head -n 1)"
refresh=false
[[ "${1:-}" == "--refresh-env" ]] && refresh=true
fail() { printf 'BOOTSTRAP FAILED: %s\nFIX: %s\n' "$1" "$2" >&2; exit 1; }
command -v mise >/dev/null || fail 'mise is not installed' 'install mise, then run: mise exec -- bun run bootstrap'
mise install
copy_env() {
  local rel="$1" src="$main/$1" dst="$root/$1"
  [[ -f "$src" ]] || fail "missing seed $src" "create it from ${src%.local}.example in the principal checkout"
  [[ "$root" == "$main" ]] && return
  if [[ -e "$dst" && "$refresh" != true ]]; then printf 'KEEP %s (use --refresh-env to replace)\n' "$rel"; return; fi
  install -m 600 "$src" "$dst"
}
copy_env apps/web/.env.local
copy_env packages/backend/.env.local
[[ -f "$main/apps/mobile/.env.local" ]] && copy_env apps/mobile/.env.local
mkdir -p "$root/.dev"
crc="$(printf '%s' "$(cd "$root" && pwd -P)" | cksum | awk '{print $1}')"
web_port="${DUDATA_WEB_PORT:-$((20000 + crc % 10000))}"
expo_port="${DUDATA_EXPO_PORT:-$((30000 + crc % 10000))}"
printf 'DUDATA_WEB_PORT=%s\nDUDATA_EXPO_PORT=%s\n' "$web_port" "$expo_port" > "$root/.dev/ports.env"
git config core.hooksPath .githooks
mise exec -- bun install --frozen-lockfile
mise exec -- bun scripts/predev.ts --bootstrap
printf 'READY checkout=%s web=http://127.0.0.1:%s expo=%s\n' "$root" "$web_port" "$expo_port"

Preflight que falha antes do wizard

import { existsSync, readFileSync } from 'node:fs'
import { createServer } from 'node:net'
import { spawnSync } from 'node:child_process'
const root = process.cwd()
const fail = (problem: string, fix: string): never => { console.error(`PREDEV FAILED: ${problem}\nFIX: ${fix}`); process.exit(1) }
const read = (path: string) => { if (!existsSync(path)) fail(`missing ${path}`, 'mise exec -- bun run bootstrap'); return readFileSync(path, 'utf8') }
const value = (text: string, key: string) => new RegExp(`^${key}=(.+)$`, 'm').exec(text)?.[1]?.trim().replace(/^['"]|['"]$/g, '')
if (Bun.version !== '1.3.14') fail(`Bun ${Bun.version}; expected 1.3.14`, 'mise install && mise exec -- bun run dev')
const node = spawnSync('node', ['--version'], { encoding: 'utf8' }).stdout.trim()
if (!/^v24\./.test(node)) fail(`Node ${node}; expected v24`, 'mise install && mise exec -- bun run dev')
const mobileMode = process.argv.includes('--mobile')
if (!mobileMode) {
  const web = read(`${root}/apps/web/.env.local`)
  for (const key of ['VITE_CONVEX_URL','CONVEX_URL','CONVEX_SITE_URL']) if (!value(web,key)) fail(`${key} is empty`, 'mise exec -- bun run bootstrap -- --refresh-env')
}
const backend = read(`${root}/packages/backend/.env.local`)
const deployment = value(backend, 'CONVEX_DEPLOYMENT')
if (!deployment || !/^(dev|local):/.test(deployment)) fail('CONVEX_DEPLOYMENT must target dev: or local:, never prod:', 'mise exec -- bun run bootstrap -- --refresh-env')
const ports = read(`${root}/.dev/ports.env`)
const name = mobileMode ? 'DUDATA_EXPO_PORT' : 'DUDATA_WEB_PORT'
const port = Number(value(ports, name))
await new Promise<void>((resolve) => { const server=createServer(); server.once('error',()=>fail(`${name} ${port} is busy`,`${name}=$(( ${port} + 1 )) mise exec -- bun run bootstrap`)); server.listen(port,'127.0.0.1',()=>server.close(()=>resolve())) })

Entrypoints

// package.json
"bootstrap": "bash scripts/bootstrap-worktree.sh",
"predev": "bun scripts/predev.ts",
"dev": "bash scripts/dev.sh",
"predev:mobile": "bun scripts/predev.ts --mobile",
"dev:mobile": "bash scripts/dev-mobile.sh"

# scripts/dev.sh
set -euo pipefail
set -a; source .dev/ports.env; set +a
exec mise exec -- bunx turbo run dev

# backend package
"dev": "convex dev --env-file .env.local </dev/null"

# Vite
server: { host: '127.0.0.1', port: Number(process.env.DUDATA_WEB_PORT ?? 3000), strictPort: true }

O ruleset elimina a atualização direta de main. No plano atual, workflow_dispatch separa merge de deploy imediatamente. O estado-alvo Enterprise restaura deploy após merge, mas o job espera aprovação no Environment.

Ruleset autoritativo

{
  "name": "Main Branch", "target": "branch", "enforcement": "active", "bypass_actors": [],
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "deletion" }, { "type": "non_fast_forward" }, { "type": "required_linear_history" },
    { "type": "pull_request", "parameters": {
      "allowed_merge_methods": ["squash", "rebase"], "dismiss_stale_reviews_on_push": true,
      "require_code_owner_review": false, "require_last_push_approval": true,
      "required_approving_review_count": 1, "required_review_thread_resolution": true
    }},
    { "type": "required_status_checks", "parameters": {
      "do_not_enforce_on_create": false,
      "required_status_checks": [{ "context": "quality" }],
      "strict_required_status_checks_policy": true
    }}
  ]
}

Dia um e estado-alvo

# Team/private — mudança imediata
on:
  workflow_dispatch:
jobs:
  deploy:
    environment:
      name: production
      url: https://dudata-hub-prototype.web.app

# Enterprise — depois de habilitar required reviewers
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - uses: jdx/mise-action@v3
      - run: mise exec -- bun install --frozen-lockfile
      - run: mise exec -- bun run test
      - run: mise exec -- bun run typecheck
  deploy:
    needs: verify
    environment:
      name: production
      url: https://dudata-hub-prototype.web.app
    runs-on: ubuntu-latest

O hook versionado em .githooks/pre-push bloqueia refs/heads/main com uma correção acionável, mas é somente feedback rápido: --no-verify o ignora; o ruleset continua sendo o controle.

A imagem carrega o SHA, o health o devolve sem cache e o comando só retorna sucesso quando GitHub e runtime concordam. Toda comunicação externa consome o renderer, não texto livre.

# Dockerfile, no estágio final
ARG GIT_SHA=unknown
ENV DUDATA_GIT_SHA=$GIT_SHA

# deploy.yml build args
--build-arg GIT_SHA="${{ github.sha }}" \

// api/health.ts
GET: () => Response.json(
  { status: 'ok', revision: process.env.DUDATA_GIT_SHA ?? 'unknown' },
  { headers: { 'Cache-Control': 'no-store' } },
)

Consulta e nota autorizada

#!/usr/bin/env bash
# scripts/deploy-status.sh
set -euo pipefail
repo='DUDATA-COMPANY/dudata-hub'
wanted="${1:-$(git rev-parse HEAD)}"
deployment="$(gh api "repos/$repo/deployments?environment=production&per_page=1" --jq '.[0] | [.id,.sha] | @tsv' 2>/dev/null || true)"
if [[ -n "$deployment" ]]; then
  deployment_id="${deployment%%$'\t'*}"; deployed_sha="${deployment#*$'\t'}"
  state="$(gh api "repos/$repo/deployments/$deployment_id/statuses?per_page=1" --jq '.[0].state')"
  source="https://github.com/$repo/deployments"
else
  run="$(gh api "repos/$repo/actions/workflows/deploy.yml/runs?branch=main&status=success&per_page=1" --jq '.workflow_runs[0] | [.head_sha,.html_url] | @tsv')"
  deployed_sha="${run%%$'\t'*}"; source="${run#*$'\t'}"; state=success
fi
health="$(curl --fail --silent --show-error https://dudata-hub-prototype.web.app/api/health)"
revision="$(printf '%s' "$health" | mise exec -- bun -e 'const x=JSON.parse(await Bun.stdin.text()); console.log(x.revision ?? "unknown")')"
printf 'wanted=%s deployed=%s state=%s health=%s source=%s\n' "$wanted" "$deployed_sha" "$state" "$revision" "$source"
[[ "$state" == success && "$deployed_sha" == "$wanted" && "$revision" == "$wanted" ]] || exit 3

# scripts/release-note.sh
sha="${1:?usage: scripts/release-note.sh <sha>}"
scripts/deploy-status.sh "$sha" >/dev/null || { printf 'REFUSED: %s is not verified live in production.\n' "$sha" >&2; exit 1; }
printf 'Production is live at %s (verified by deploy state and public health).\n' "$sha"

PR liga código a uma issue real via referência interpretada pelo GitHub; o check quality valida o vínculo, build e contrato de processo. Documentação descreve a mesma configuração que CI verifica.

<!-- .github/PULL_REQUEST_TEMPLATE.md -->
## Issue
Closes #NNN
## Verification
- [ ] `mise exec -- bun run test`
- [ ] `mise exec -- bun run typecheck`
- [ ] `mise exec -- bun run build`
## Deployment impact
<!-- None, migration, runtime configuration, or operational risk. -->

# scripts/check-pr-issue-link.sh
count="$(gh api graphql -f query='query($owner:String!,$repo:String!,$number:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$number){closingIssuesReferences(first:1){totalCount}}}}' -f owner="$owner" -f repo="$repo" -F number="$PR_NUMBER" --jq '.data.repository.pullRequest.closingIssuesReferences.totalCount')"
[[ "$count" -gt 0 ]] || { printf 'PR must link a real issue with `Closes #NNN`.\n' >&2; exit 1; }

Contrato e teste de drift

# docs/process.md
issue -> isolated branch/worktree -> bootstrap -> verify -> PR ->
CI + independent review -> merge -> production authorization ->
deploy -> queried status -> release note

# scripts/check-process-contract.sh
set -euo pipefail
rules=ops/github/main-ruleset.json
grep -Fq '"~DEFAULT_BRANCH"' "$rules"
grep -Fq '"bypass_actors": []' "$rules"
grep -Fq '"type": "pull_request"' "$rules"
grep -Fq '"context": "quality"' "$rules"
grep -Eq '^[[:space:]]+environment:' .github/workflows/deploy.yml
grep -Fq 'Closes #NNN' .github/PULL_REQUEST_TEMPLATE.md
grep -Fq 'scripts/deploy-status.sh' docs/process.md
if grep -Fq 'workflow_dispatch:' .github/workflows/deploy.yml; then
  grep -Fq 'production uses explicit workflow dispatch' docs/process.md
elif grep -Fq 'branches: [main]' .github/workflows/deploy.yml; then
  grep -Fq 'merges trigger a deployment that waits' docs/process.md
else
  printf 'deploy trigger is neither fallback nor protected target state.\n' >&2; exit 1
fi
if grep -Fq 'faz os merges na `main` em sequência' AGENTS.md; then
  printf 'AGENTS.md still prescribes the incident path.\n' >&2; exit 1
fi

Uma CLI estreita basta: vocabulário estável do projeto, validação antes da rede e duas operações permitidas. A nota de release só entra pelo serviço da CAP-03.

export type Fetcher = typeof fetch
const taskIdPattern = /^[A-Za-z0-9_-]+$/
export function clickup(token: string, request: Fetcher = fetch) {
  if (!token) throw new Error('CLICKUP_API_TOKEN is required')
  const call = async (taskId: string, method: string, body: object) => {
    if (!taskIdPattern.test(taskId)) throw new Error('invalid ClickUp task id')
    const url = `https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}${method === 'POST' ? '/comment' : ''}`
    const response = await request(url, { method, headers: { Authorization: token, 'Content-Type': 'application/json' }, body: JSON.stringify(body) })
    if (!response.ok) throw new Error(`ClickUp ${response.status}: ${await response.text()}`)
    return response.json()
  }
  return {
    comment(taskId: string, text: string) {
      if (!text.trim()) throw new Error('comment text is required')
      return call(taskId, 'POST', { comment_text: text, notify_all: false })
    },
    status(taskId: string, status: string) {
      if (!status.trim()) throw new Error('status is required')
      return call(taskId, 'PUT', { status })
    },
  }
}
if (import.meta.main) {
  const [operation, taskId, ...rest] = process.argv.slice(2)
  const api = clickup(process.env.CLICKUP_API_TOKEN ?? '')
  const result = operation === 'comment' ? await api.comment(taskId, rest.join(' '))
    : operation === 'status' ? await api.status(taskId, rest.join(' '))
    : (() => { throw new Error('usage: bun tools/clickup.ts <comment|status> <task-id> <value>') })()
  console.log(JSON.stringify(result))
}

# tools/clickup-release-note.sh
task="${1:?usage: tools/clickup-release-note.sh <task-id> <sha>}"
sha="${2:?usage: tools/clickup-release-note.sh <task-id> <sha>}"
note="$(scripts/release-note.sh "$sha")"
exec mise exec -- bun tools/clickup.ts comment "$task" "$note"

// contract test: invalid input performs zero HTTP calls
let calls = 0
const fake = (async () => { calls++; return new Response('{}') }) as typeof fetch
await expect(clickup('token', fake).comment('bad id!', 'x')).rejects.toThrow('invalid')
expect(calls).toBe(0)