Esteira de Entregas — Manual de Operação

O que é a Esteira de Entregas

A Esteira é o processo industrial do MakeStudio: um conjunto de fases, portões e regras — todos aplicados em código, pelo harness — que transforma uma ideia num sistema entregue, com preço auditável antes de começar e calibração depois de terminar. Nenhuma etapa depende de o agente "se comportar": o sistema bloqueia o erro antes dele acontecer.

Custear o sistema antes de entrar na esteira

A Fase 0 acontece antes de qualquer linha de código — o cliente precisa saber quanto o sistema custa antes de autorizar o desenvolvimento. O método: classificar atributos qualitativos e deixar a fórmula derivar o número. O estimador não chuta horas; ele classifica.

A moeda: o que é (e o que NÃO é) uma Unidade de Entrega

Toda a Esteira negocia em Unidades de Entrega (UE) — e entender esta moeda é pré-requisito para tudo que segue. Quando algum comando imprimir DU (Delivery Unit), é o mesmo número sob o nome interno do motor: leia sempre como UE. A definição formal: UE é a unidade que mede o ESCOPO DE RESULTADO de um trabalho de entrega. Ela não mede tempo, não mede esforço, não mede linhas de código — mede quanto de resultado aquele trabalho carrega.

Por que não as unidades que você já conhece

Como uma UE nasce — o pipeline do número, estágio a estágio

Cinco estágios, cada um respondendo UMA pergunta. Os números em azul acompanham a story-exemplo do motor (Medium + High, R3, Incerteza M, Governança M, Urgência Normal) do início ao fim.

A âncora — e por que justamente 28

28 UE é o tamanho de uma tarefa mediana bem-fatida — a régua de sanidade da decomposição. Story calculada muito acima da âncora (3×, 4×) é story grande demais: quebre em duas. Muito abaixo (0,2×, 0,3×) é poeira: junte com a vizinha. Estimativas muito distantes da âncora exigem justificativa escrita. E o 28 não é dogma: é o pivô de calibração — quando a medição real de um repo mostra desvio sistemático, a âncora ajustada (âncora × fator do repo) corrige as estimativas seguintes. A moeda aprende.

Da UE ao real — três números, três papéis

story classificada: Size Medium (1,0) + Complexity High (1,9), R3, Incerteza M,
Governança M, Urgência Normal → 164 UE
custo    = 164 UE              × R$ 130         = R$ 21.320   (escopo × rate)
preço    = R$ 21.320           × (1 + 20%)       = R$ 25.584   (custo × margem)
proposta = 164 UE com buffer já embutido, tabela fator a fator — auditável

As cinco propriedades que fazem a UE funcionar como moeda

Como uma UE "morre" — o consumo medido

Estimada, a story é executada e o /mks-meter grava o custo real (normalizado em UE) como actual no ledger, junto com o footprint do diff. Estimado e medido se confrontam: a razão entre eles é o fator de calibração do repo. É assim que a moeda fecha o ciclo — nasce de classificação, morre de medição, e a diferença entre as duas ensina a próxima estimativa.

O modelo de 6 fatores — a matéria-prima do número

Cada story é classificada por 6 fatores. Size e Complexity (aditivos) medem o trabalho em si; os outros 4 (multiplicativos) ajustam pelo contexto. Todos os valores abaixo vêm do motor (src/delivery/estimation/factors.ts) — não são ilustração.

A fórmula — do fator ao número

exemplo real (Story de exemplo do motor):
  Size Medium (1,00) + Complexity High (1,90)      = esforço 2,90
  × R3 (1,45) × Incerteza Medium (1,15)
  × Governança Medium (1,10) × Urgência Normal (1,0) = ajustado 5,30
  × 28 UE por ponto de score                        = 148,4
  × (1 + 10% buffer)                                = 163,3 → ceil = 164 UE

Fallback por contagem — quando os fatores não são classificados

Se a entrevista não classifica os 6 fatores, a engine usa o modelo de contagem, baseado em sinais objetivos da spec: UE = base 8 + critérios×4 + repos×6 + seções×3. Defensável, mas perde a sensibilidade de contexto (R4 × R1 = 75% de diferença que a contagem não enxerga).

Os parâmetros — a assinatura dos comandos da Fase 0

O gate humano — o fim da Fase 0

A Fase 0 termina com um documento de estimativa apresentado ao cliente: marcos, entregáveis, UE por entregável, total em R$, validade e fora-de-escopo. Nada entra na Esteira sem aprovação explícita — e a aprovação fica registrada. O custo de estimar (5–10% do projeto) economiza os 50% de imprevisto do "chuta que é mais ou menos 2 semanas".

Plan — o nascimento do sistema

A Fase Plan é onde uma ideia vira um contrato executável. Cada decisão tomada aqui propaga por todo o ciclo: o overview define o que o cliente compra, o breakdown define o que será testado e quanto custa, a arquitetura define como o código se organiza, e os critérios de aceite definem quando algo está "pronto". É o momento de maior alavanca do projeto — um erro de escopo aqui custa 10× mais para corrigir no Build, e 100× mais se chegar ao cliente em produção.

Antes de operar: o território — um workspace, N repositórios

A Esteira separa o mundo em dois: o workspace (o repositório da análise, onde a Esteira vive e todo o processo é versionado) e os repositórios de código (o código-fonte real do sistema, registrado dentro do workspace, em delivery/repos/). Entender esta separação é pré-requisito para operar qualquer comando — é o mapa do território.

Como fica no disco — a anatomia completa

meu-projeto/                          ← WORKSPACE (o repositório da análise)
├── delivery/
│   ├── delivery.json                 ← parâmetros: UE, rate, margem, pesos, REPOS REGISTRADOS
│   ├── rules/                        ← plan.md · build.md · harden.md (+ overlays do projeto)
│   ├── context/                      ← knowledge store: DDLs, contratos, PDFs, glossário
│   ├── templates/                    ← overview, estimate, integration-test, bug
│   ├── calibration.json              ← ledger estimado vs. real (o que o board e o motor leem)
│   ├── workstreams/
│   │   ├── active/20260920-system-contrata/
│   │   │   ├── overview.md           ← o que o cliente compra (blueprint)
│   │   │   ├── architecture.md       ← a fundação (arquiteto)
│   │   │   ├── track-1-fundacao/
│   │   │   │   ├── functional/story-0001-*.md          ← spec + critérios (breakdown)
│   │   │   │   └── build-plans/story-0001-*-build-plan.md  ← plano técnico (techplan)
│   │   │   └── validation-reports/   ← evidência do validate + bugs/ (harden)
│   │   ├── completed/ · archived/    ← ciclo de vida da entrega
│   ├── repos/                        ← O CÓDIGO-FONTE REAL VIVE AQUI (dentro do workspace)
│   │   ├── backend/                  ← repo registrado no init (clone git OU symlink local)
│   │   └── web/                      ← segundo repo — a Esteira orquestra vários de uma vez
│   └── pentest-audits/               ← configs/shannon.yaml + runs/YYYYMMDD-NNNN/
└── (NUNCA código de aplicação na raiz — o workspace é control plane)

Como os repositórios entram no workspace

Como você opera — a Esteira é uma conversa em comandos

Não existe botão, formulário nem "fluxo contínuo": você opera a Esteira digitando um comando por vez no chat. O especialista daquele comando assume (Consultor, Arquiteto, Dev Team…), faz o trabalho, e devolve o controle apontando o próximo passo. Um comando = um passo do processo — nunca um "faça tudo".

Como saber qual é o próximo comando — três formas

A sequência do Plan — quatro comandos, uma ordem

Os parâmetros — a assinatura dos comandos do Plan

Quem escreve onde — a fronteira por comando

Executar de novo — o que acontece com cada comando

Nada na Esteira explode com re-execução — mas cada comando tem uma política diferente. Esta é a tabela de bolso:

Escrever critérios de aceite que prestam

Build — onde o código nasce (com supervisão)

O Build é um ciclo por story: plano técnico antes, implementação em branch própria, revisão de 4 lentes com auto-correção depois. O agente executa; o harness confere cada afirmação. Nada aqui depende de confiança — tudo depende de evidência.

O ciclo de cada story

Os parâmetros — a assinatura completa de cada comando

Esta é a tabela de consulta: o que cada comando aceita, o default, e por que o parâmetro existe. Nenhum comando silencia flag desconhecida — erra o nome e ele aborta avisando (errar é seguro, digitar errado sem saber não).

Techplan — a ponte do escopo pro código, com regras próprias

O Tech Lead pega UMA story e produz o build-plan: o documento de intenção que o /mks-build vai executar. Ele entra em plan mode, lê a cadeia de contexto inteira, entrevista você sobre as decisões técnicas, e escreve exatamente um arquivo. Guardrails absolutos: nunca implementa código, nunca roda build/teste, nunca escreve fora do build-plan.

As duas precondições duras — e o que o abort ensina

A cadeia de contexto — o que ele lê (e o que recusa ler)

Dois detalhes que surpreendem: (1) a arquitetura é precondição SOFT — sem architecture.md ele recomenda rodar /mks-architecture primeiro e só prossegue se você pedir pra pular (derivando decisões conservadoramente e anotando no plano que não havia fundação); (2) ele NÃO lê os critérios de aceite — são reservados ao /mks-validate. O planejador técnico não conhece os critérios de aprovação: cada papel vê o que precisa, nada além.

A entrevista técnica — decisões, não impressões

Múltiplas rodadas, começando no nível arquitetural e descendo ao específico: escolhas de tecnologia, padrões a seguir, edge cases, tratamento de erro, performance. Resposta vaga não passa — ele pede decisão concreta. E ele desafia: vê alternativa melhor, propõe. O plano só é escrito depois que as dúvidas técnicas acabam e você aprova a estrutura proposta.

Anatomia do build-plan — o que o arquivo contém

entity Contract: id UUID pk · tenant_id FK · status enum(draft,active,closed)
                · starts_on DATE · ends_on DATE · version INT
endpoint POST /api/v1/contracts — auth: bearer + tenant scope
DTO ContractCreate: customer_id, plan_id, starts_on, ends_on, notes?

Terminou? O Tech Lead sai do plan mode, chama AdvancePhase com o stage correspondente (justificativa nomeando a story/plano) e aponta o próximo passo: /mks-build <workstream> <story> — que não roda sem este arquivo.

Build — a execução com estado durável

O build executa o plano item a item do checklist, validando antes de commitar — em branch própria por repo, com o disco como memória. É o único comando da Esteira desenhado para ser interrompido e retomado quantas vezes o mundo precisar.

O protocolo, passo a passo

Os settings que mudam o comportamento

Review — 4 lentes que CORRIGEM, não só apontam

O review roda 4 subagentes paralelos e consolida os findings — e aqui está o que quase todo mundo erra ao ler esta seção: Critical e High são auto-corrigidos por default. Cada correção é validada por build + testes e commitada atomicamente antes de ir pro relatório. O review não te entrega uma lista de tarefas — entrega os problemas graves já resolvidos, com o SHA do commit de cada fix.

O relatório vive em reviews/<branch>/CURRENT.md (por branch, sobrescrito a cada run — o git é o histórico). Stories em completed/ ou archived/ são recusadas: "Completed stories are read-only" — pós-release vira story nova.

Quando uma story está "done" — o gate completo

Os guardas do harness — o que roda em cada turno

Harden — a última linha de defesa antes do cliente

Harden é onde você descobre se o que foi construído realmente funciona — não se o código compila (isso o Build já garantiu), mas se o usuário consegue usar o sistema como especificado. E se um atacante consegue entrar onde não devia. É a diferença entre "funciona na minha máquina" e "funciona para quem paga a conta".

Os dois portões — o que cada um protege

Portão 1: Validação — como o browser agent funciona

O /mks-validate não é um teste unitário nem um teste de integração. É um teste de aceitação comportamental: um agente abre um browser de verdade, navega no sistema como um humano faria, e verifica se cada critério escrito no Plan se cumpre.

O ciclo interno do validador — o que acontece em cada critério:

Como um relatório de validação se parece:

Os modos de invocação — story, tool ou track inteira

O <workstream> aceita match parcial (se bater mais de um, lista e pergunta). O <story> aceita número (0003) ou slug (monthly-hour-calculation) — a busca varre todos os track-*/functional/ atrás do *-acceptance-criteria.md correspondente.

O contrato declarativo — a skill não conhece sua stack

Primeira execução — o wizard de configuração

Pré-flight — verificado ANTES de abrir qualquer browser

Classificação de critérios — api / ui / manual

Autenticação — uma vez por execução, declarativa

O login roda uma única vez por execução (curl com method/path/headers/body do delivery.json, placeholders {{env.VAR}} do .env). Os artefatos que as tools compartilham ficam em .auth/ (sempre gitignored): api-token.json, storage-state.json (o browser "nasce logado") e cookies.txt.

As duas ferramentas — e por que são duas

O fix loop — 3 tentativas, depois delega para humano

Rubrica de severidade — e como bugs nascem numerados

O que não se conserta em 3 tentativas vira bug estruturado: validation-reports/bugs/bug-NNN-<slug>.md, com numeração monotônica POR TRACK. Diretórios são criados lazy — bugs/ e evidence/ só nascem no primeiro artefato real: pasta vazia pareceria trabalho delegado que não existe.

Reconciliação entre ferramentas — as 4 situações possíveis

Modo track — retry que protege contra regressão de correção

As 6 regras "NUNCA" do validador

Portão 2: Pentest — a auditoria ofensiva com Shannon

O /mks-pentest executa uma auditoria white-box (com acesso ao código-fonte em delivery/repos/) usando a ferramenta Shannon. Shannon é uma ferramenta de pentest autônomo que recebe a URL do alvo + o código-fonte + regras de autenticação, e tenta invadir o sistema da mesma forma que um atacante real tentaria — navegando, injetando, explorando, escalando privilégios. Tudo que ela encontra fica em delivery/pentest-audits/runs/.

Pré-flight: 8 verificações obrigatórias antes de rodar

Fluxo de execução — o que acontece quando você confirma

O que Shannon ataca — com vetor real de cada categoria

O diretório da run — o que fica em disco

delivery/pentest-audits/
├── configs/
│   └── shannon.yaml              # Auth, rules, pipeline — editado manualmente
└── runs/
    ├── 20260920-0001/            # Uma run: YYYYMMDD + sequência global
    │   ├── workstream.txt        # Link de rastreabilidade (se passado)
    │   └── [output do Shannon]   # Reports, screenshots, logs
    └── 20260921-0002/            # Sequência NUNCA reseta

As 6 regras "NUNCA" do pentest

Como um finding se parece

Como findings viram trabalho — o pipeline de correção

Release — o protocolo de versionamento que fecha a entrega

O /mks-release <new-version> é o último comando da Esteira — e é deliberadamente pequeno: ele versiona, documenta e publica a versão. Só isso, feito com rigor total.

Pré-flight — 3 verificações, qualquer uma falha aborta

Mode detection — template ou delivery unit

Os 9 passos — o que acontece depois do pré-flight

Anatomia do changelog funcional — a transformação que o passo 6 faz

$ git log v0.1.0..HEAD --oneline
a3f9c21 fix: guard null token in refresh flow
8b2e440 refactor: extract auth middleware
c7d1155 fix: refresh crash when token expired
d4a8812 feat: monthly revenue report page
e5f3320 chore: bump version to v0.1.0
f6b2199 fix: chart re-render on filter change
a1c7780 feat: revenue report export to CSV

• Corrigido: erro ao renovar sessão expirada (três commits técnicos, UM defeito de usuário)
• Novo: relatório de receita mensal com exportação CSV
• Corrigido: gráfico não atualizava ao trocar o filtro

As regras do protocolo

Critérios de saída do Harden — checklist completo

Erros comuns do Harden — e como a Esteira protege

As regras que mantêm a esteira honesta

Regras (P1–P8) extraídas de falhas reais — cada uma existe porque alguém já pagou o preço de ignorá-la. O detalhe de cada regra está na seção 13; aqui você entende como elas são aplicadas — e por que não dependem de o agente "lembrar".

As oito regras P1–P8 — com a motivação de cada uma e o mecanismo que aplica — estão detalhadas no capítulo 13. O que é específico do Harden está abaixo.

A Esteira como runtime — o board que gateia por si

Além das regras aplicadas ao agente, o MOTOR tem gate própria: a dashboard não é um visor passivo, ela segura a fase até haver aceite humano registrado (e há um protocolo para concluir e para desconfiar de si mesma).

A esteira aprende: calibração da estimativa

Cada entrega concluída alimenta a calibração: UEs estimadas vs esforço real medido. Desvios sistemáticos corrigem a âncora — por repositório, com o ajuste registrado, nunca silencioso. É o que faz a Fase 0 do próximo projeto nascer melhor que a do anterior.

O ledger — onde a verdade vive

{ "story": "20260920-system-contrata/track-1-fundacao/story-0001",
  "repo": "backend",
  "factors": { "size": "Medium", "complexity": "High", ... },   ← os 6 fatores classificados
  "scope":  { "acceptanceCriteria": 6, "repos": 1, "sections": 5 },  ← counts (fonte da verdade do DU)
  "estimatedDU": 53,                                             ← DU calculado na estimativa
  "actual": null,                                                ← custo MEDIDO (o meter preenche)
  "footprint": ... }                                             ← diff real entregue (segundo sinal)

O loop — como estimado encontra real

O /mks-calibration lê o ledger e resume por repositório. A mecânica é determinística: o fator de um repo é a média de actual / estimatedDU das stories que já têm custo real; a âncora ajustada é a âncora base multiplicada por esse fator. Estimativas seguintes daquele repo já nascem corrigidas — cada repo aprende separado, porque um backend legado e um frontend novo erram de formas diferentes.

Os quatro vereditos — o que o relatório diz

O segundo sinal — footprint do diff

Custo sozinho mente: retrabalho e volta-atrás parecem esforço legítimo. Por isso o build grava também o footprint — o diff objetivo entregue (arquivos tocados, linhas +/−) por story no ledger. São dois sinais medidos que se confrontam: pagou 53 DU para entregar quantas linhas? A relação custo/footprint por repo, ao longo do tempo, expõe onde o trabalho escoa sem produzir entrega.

ContrataCRM — a esteira inteira sobre o saas-starter

O ContrataCRM é o exemplo que ancora este manual: um sistema fictício de gestão de contratos B2B para uma pequena consultoria, construído sobre o boilerplate saas-starter. Aqui você vê o método inteiro funcionando — a Fase 0 com classificação de verdade, o preço nascendo da fórmula, a execução fase a fase e a calibração fechando o ciclo com desvio de +4,5%.

O ponto de partida — o que o boilerplate já entrega

Toda estimativa parte do que JÁ existe. O saas-starter é um monorepo NestJS + React de produção — e é por isso que o Marco 1 tem incerteza Low: a fundação técnica não é promessa, é fato verificado no disco.

A Fase 0 do ContrataCRM — a classificação de verdade

O contexto da intenção

Os marcos com incerteza JUSTIFICADA

O que a Esteira fez com o número aprovado

Cada etapa deixou seu artefato no workspace: o overview.md que o cliente aprovou, os ADRs numerados que TODOS os build-plans herdaram (decisão de persistência e auth tomada UMA vez), 11 build-plans com checklist, branches workstream/contrata/story-NNNN por repo, relatórios de validação com screenshot por critério, e o pentest concentrado no Marco 2 — onde o dinheiro circula, é lá que a auditoria ofensiva paga mais. O walkthrough passo a passo desta execução está na seção 11.

O resultado medido — a calibração nasce

Cada story concluída gravou seu actual (consumo medido em DU) no ledger. A soma deu 163 contra 156 estimadas: +4,5% — dentro da faixa de 5% que o motor chama de calibrated. A âncora não precisou de ajuste, e a próxima estimativa desta dupla de repos nasce com o fator real por trás. Zero push sem gate, zero commit na main, 100% dos critérios com evidência — e uma tag v1.0.0 cujo git show exibe o changelog funcional até hoje.

Simule o custo do seu sistema

A mesma fórmula da Fase 0, exposta: arraste os parâmetros e veja o preço. Os valores iniciais reproduzem o caso-base do ContrataCRM.

Como operar a Esteira — comando por comando

Este é o manual de operação: qual comando rodar, quando, e o que esperar. Primeiro o mapa operacional com o porquê de cada comando; depois a referência comando-por-comando, agrupada por fase.

Como a Esteira funciona — a jornada de operação completa

Este é o mapa operacional: seis estações, cada uma com o que acontece, os comandos e o gate que libera a próxima. Nenhuma fase termina "no feeling" — cada gate é verificável no board ou no disco. As seções 02–05 trazem o treinamento completo de cada fase; a referência comando-por-comando vem logo depois do mapa.

Comando por comando — a referência de operação

Cada comando abaixo tem quatro campos: Quando rodar (o gatilho), O que faz (o mecanismo), Como usar (a sintaxe exata) e O que esperar (o resultado verificável no disco ou no board) — mais o Por que este comando: a dependência que justifica ele existir separado e nesta posição. Os módulos com portões próprios — Plan, Build, Harden — têm treinamento completo nas seções 03–05.

ContrataCRM — o roteiro de execução, com o que aparece em cada passo

Este é o roteiro do exemplo, montado sobre o que o sistema realmente imprime e produz (handlers, skills e artefatos verificados). Cada passo mostra: o comando exato, o que o agente faz, o que VOCÊ decide, e o que aparece — o output literal ou o artefato no disco. Seguindo-o, você sabe reconhecer sucesso e desvio em cada etapa. A ordem canônica das estações, com o porquê de cada posição, está no mapa da seção 10 — aqui a mesma jornada é vista por dentro, com os números do ContrataCRM (156 UE estimadas · R$ 26.770 aprovados · 163 UE medidas).

FASE 0 — custear (4 comandos + 1 gate)

delivery/
├── delivery.json        ← { estimation: {...}, pricing: {...}, repositories: [backend, frontend] }
├── rules/               ← plan.md · build.md · harden.md
├── workstreams/{active,completed,archived}/
└── repos/{backend→, frontend→}   ← symlinks para o boilerplate

  Proposta  rate R$ 130,00 · margem 20%
  contrata (system)
     156 DU  →  R$ 26.770
      T1 fundacao        64 DU
      T2 contratos       76 DU
      T3 relatorios      16 DU
  Total: 156 DU → R$ 26.770  (subtotal R$ 22.308 + margem 20%)

FASE 1 — plan (4 comandos)

## Plan Status
### Active (1 workstream)
| Workstream     | Brainstorm | Tracks        | Tasks Done | Presentation |
|----------------|------------|---------------|------------|--------------|
| 20260920-system-contrata | Yes | 3/3 documented | 0/11 | Yes |

FASE 2 — build (o ciclo por story, 11×)

FASE 3 — harden (3 comandos + merge)

O resultado final — os entregáveis verificáveis do teste

A motivação — cada fase resolve um problema real

Antes de aprender os comandos, entenda por que cada peça existe. Uma ferramenta sem motivação é burocracia; com motivação, é processo.

P1–P8 — cada regra com motivação e consequência

Estas regras existem porque alguém já pagou o preço de ignorá-las. Cada uma é aplicada em código pelo harness — o agente não pode "esquecer".

Quem faz o quê na Esteira

A Esteira não substitui pessoas — ela amplifica. Cada papel tem responsabilidade clara e o agente é a ferramenta, não o dono.

O especialista por trás de cada comando

Cada skill da Esteira opera como um especialista com personalidade própria — não um chat genérico. A voz é parte do design: ela molda COMO o agente pensa e responde naquele comando. E ela se identifica: toda resposta vem assinada com o papel (ex.: [Arquiteto]) — se a assinatura não bate com o comando, algo saiu do trilho.

Artifacts produzidos em cada fase

Armadilhas que todo iniciante cai — e como a Esteira protege

Cada erro abaixo é real, já aconteceu, e tem uma proteção estrutural na Esteira. Conhecer as armadilhas é metade da certificação.

Vocabulário formal da Esteira

Termos que você precisa dominar para operar com confiança.

Teste seu entendimento

Se você responde estas 8 perguntas com confiança, você domina a Esteira.

Níveis de domínio

O que decidir agora

Um manual sem pedidos explícitos é um ensaio. Estas são as decisões que este documento coloca na mesa:

Fontes e rastreabilidade

Todo número deste documento rastreia a uma das fontes abaixo ou está explícito como hipótese/ilustração.