ADR-0027 — Paperclip como source-of-truth de trabalho (Paperclip-first)

Status: Accepted Data: 2026-05-20 Autor: Marcelo Lermen + CC (sessão #17) Supersedes: ADR-0014 §Princípio 4 (queue em GitHub Issues), ADR-0017 §Fase 2 inteira (cc-autopilot self-hosted), parcialmente ADR-0026 §2.7 (Paperclip "backend transparente" → vira source-of-truth) Não muda: ADR-0014 §Princípio 1 (chat única porta humana), ADR-0014 §Princípio 2 (sub-agents Camada 3 obrigatórios), ADR-0014 §Princípio 3 → ADR-0022 (ROI substitui cap)

---

Contexto

Em 2026-05-20 (sessão #17), com Paperclip em produção e 8 agents criados, revisamos a arquitetura. O modelo vigente tinha 3 camadas:

Marcelo → Chat Tynna → CC → GitHub Issue (com label cc-can-execute)
                                ↓
                          cc-autopilot.yml (cron 9h/21h BRT, serial concurrency)
                                ↓
                          claude -p execução no VPS

Paperclip era usado como "backend transparente" (ADR-0026 §2.7): backup tooling, não source-of-truth.

Problema identificado: 3 camadas + duplicação de estado (GH labels vs Paperclip status) + workflow cc-autopilot.yml com 233 linhas reimplementando o que Paperclip já tem nativo (issue queue, agent assignment, concurrency, scheduling, approvals).

Decisão

Paperclip vira source-of-truth do trabalho a partir desta sessão (#17, 2026-05-20).

Marcelo → Chat Tynna → CC → Paperclip Issue + assigneeAgent → run
                                ↓
                          GitHub Issues = só bug reports externos (user-facing)

Migração imediata — sem fase paralela. cc-autopilot.yml renomeado pra .yml.disabled na mesma PR.

Pontos da decisão

1. Issues do trabalho Tynna moram no Paperclip (companies/{cid}/issues). CC cria via API quando Marcelo descreve intenção.
2. Sub-agents Tynna são employees Paperclip (Sprint C, sessão #17). 7 employees criados: QA Reviewer, Security Reviewer, UX Reviewer, Test Writer, Root Cause Analyst, Doc Writer, Eval Runner.
3. cc-autopilot.yml desabilitado — Paperclip routines + agent heartbeat substituem cron + concurrency.
4. GitHub Issues = público externo apenas — bug reports de usuários terceiros (quando houver), CI alerts (runner:auth-expired), Dependabot. Trabalho interno NÃO vai mais pra GH Issues.
5. .claude/agents/*.md arquivados — instruções já estão duplicadas como instructionsBundle nos employees Paperclip. Diretório vira leitura histórica.
6. dev-standards §17.7-§17.12 atualizado — cc-can-execute label não existe mais. Trabalho é dispatched via Paperclip API ou UI /m/queue.

Implicações operacionais

• OAuth bridge expira 36h vira P0 — sem chat working, não há porta humana. Task #63 auto-refresh é blocker pra Paperclip-first.
• /m/queue ganha ações — criar issue, dispatch, pause, edit (#71).
• Disponibilidade Paperclip = disponibilidade da fábrica — se Paperclip cair, agents não trabalham. Mitigação: VPS neo já tem uptime monitor (UptimeRobot setup runbook PR #70).
• Paralelismo aumenta — cc-autopilot era serial (1 issue por vez). Paperclip pode rodar 8 agents simultâneos com maxConcurrentRuns: 3 cada (~24 issues concorrentes teóricas).
• Custo: sem mudança. Adapter claude_local usa mesma quota Max.

Trade-offs

Mantido:

• Chat como única porta humana (Princípio 1 ADR-0014)
• Quota Max R$ ~100/mês como cap
• Sub-agents Camada 3 obrigatórios em paths sensíveis (Princípio 2 ADR-0014)

Aceito como risco:

• Paperclip < 30d em produção (maturidade baixa)
• Decisão unidirecional — voltar pra cc-autopilot exige restaurar workflow
• Issues GH histórico permanece em GH (não vai migrar bulk)

Ganho:

• 1 source-of-truth (sem sync GH ↔ Paperclip)
• 233 linhas YAML cc-autopilot deletadas
• Paralelismo 8x
• /m/queue deixa de ser read-only
• Status tracking nativo (todo/in_progress/review/done) substitui labels frágeis
• Routines com cron via API substituem workflow_dispatch

Mudanças concretas nesta PR

1. Este ADR-0027 documenta a decisão
2. cc-autopilot.yml → cc-autopilot.yml.disabled (preservado pra referência)
3. CLAUDE.md root atualizado com novo workflow CC
4. dev-standards.md §17.7-§17.12 marcado como SUPERSEDED
5. .claude/agents/README.md adiciona nota "instructions agora em Paperclip employees"

Fora desta PR (follow-ups)

• #63 Auto-refresh OAuth bridge (CRÍTICO — Paperclip-first depende de chat estável)
• #68 Sprint B+ ativar gh CLI no user paperclip pra agents poderem dar push em PRs
• #71 UI /m/queue ações (criar/dispatch)
• #46/#47 Cowork knowledge migration (paralelo, não bloqueia)
• Migration bulk de Issues GH abertas com cc-can-execute pra Paperclip (manual, baixo volume)

Histórico de decisões superseded

Critério de sucesso

Em 30 dias (2026-06-20):

• 0 Issues GH abertas com label cc-can-execute (label vira deprecated)
• ≥10 Issues Paperclip executadas com sucesso pelos 7 employees
• 0 invocações de cc-autopilot.yml.disabled (confirma deprecation)
• /m/queue é primária pra Marcelo gerenciar work

Se não atingir → revisar e considerar rollback parcial (restaurar cc-autopilot como fallback).