Diário do Apex e da tese

Tudo desde o 6d212b6, o primeiro commit do repositório, lido a partir do próprio histórico: 1.171 commits entre uma plataforma de governação e a dissertação que a descreve. Entregue no prazo. Projeto encerrado.

Entregue
7 de outubro de 2026
Defendida
23 de outubro de 2026
Nota da dissertação
17/20
Nota final do mestrado
Por atribuir
dias, do primeiro ao último commit
186
commits no total
1.171
dias a escrever a tese
83
commits em docs/thesis
199
páginas na versão final
99/100
participantes na avaliação
13/12

Contexto

Governed Human-AI Collaboration Across the Software Development Lifecycle: A Process Framework and Its Reference Implementation

Introdução

Uma dissertação de mestrado em Engenharia Informática e de Computadores (MEIC-T) no IST, seguindo a Design Science Research Methodology: identificar um problema, desenhar um artefacto que o resolva, demonstrá-lo num contexto real e avaliá-lo. O trabalho tem duas metades, separadas de propósito: uma framework (o método) e o Apex (uma instanciação funcional dela).

Contexto

A IA generativa e os grandes modelos de linguagem passaram do preenchimento automático a contribuidores ativos em todo o ciclo de vida. Os profissionais descrevem agora requisitos em linguagem natural e supervisionam o que o modelo produz. A adoção ultrapassou o método: as equipas usam estas ferramentas todos os dias sem um processo acordado sobre onde a IA participa e onde para.

Problema

Uma revisão sistemática da literatura de 646 artigos encontrou benefícios reais a par de riscos recorrentes em fiabilidade, segurança, rastreabilidade e responsabilização. A principal lacuna por resolver: não existe orientação estruturada e repetível para integrar a IA em fluxos de trabalho profissionais. O seu valor depende tanto do processo à volta do modelo como do próprio modelo.

Solução

Uma framework de processo que trata a IA como colaboradora de primeira classe, cujo resultado tem de ser delimitado, validado e rastreado: seis fases (Descoberta, Design, Implementação, Testes, Implantação, Manutenção), cinco portões de qualidade, responsabilidades atribuídas a chapéus, Bolts em vez de sprints e três métricas de governação. Tudo assenta numa especificação persistente e versionada que liga cada artefacto gerado ao seu requisito. O Apex executa-a de ponta a ponta com backends reais de Taiga/Plane, GitHub e Figma, e foi avaliado no projeto Outfolio e com 13 participantes.

Documentos

Contribuições

Commits por dia em todo o repositório. 11 rondas de revisão do Overleaf foram também sincronizadas neste histórico.

abr.mai.jun.jul.ago.set.out.segquasex2026-04-19: 02026-04-20: 02026-04-21: 02026-04-22: 02026-04-23: 02026-04-24: 22026-04-25: 02026-04-26: 02026-04-27: 02026-04-28: 22026-04-29: 12026-04-30: 02026-05-01: 02026-05-02: 02026-05-03: 12026-05-04: 202026-05-05: 62026-05-06: 12026-05-07: 72026-05-08: 72026-05-09: 112026-05-10: 32026-05-11: 362026-05-12: 202026-05-13: 22026-05-14: 32026-05-15: 172026-05-16: 02026-05-17: 42026-05-18: 202026-05-19: 282026-05-20: 12026-05-21: 112026-05-22: 232026-05-23: 292026-05-24: 02026-05-25: 02026-05-26: 202026-05-27: 12026-05-28: 72026-05-29: 102026-05-30: 02026-05-31: 02026-06-01: 72026-06-02: 112026-06-03: 212026-06-04: 122026-06-05: 82026-06-06: 52026-06-07: 52026-06-08: 152026-06-09: 162026-06-10: 72026-06-11: 112026-06-12: 252026-06-13: 82026-06-14: 202026-06-15: 182026-06-16: 132026-06-17: 172026-06-18: 142026-06-19: 122026-06-20: 172026-06-21: 102026-06-22: 132026-06-23: 72026-06-24: 22026-06-25: 62026-06-26: 02026-06-27: 162026-06-28: 72026-06-29: 82026-06-30: 272026-07-01: 222026-07-02: 52026-07-03: 62026-07-04: 42026-07-05: 182026-07-06: 32026-07-07: 02026-07-08: 52026-07-09: 52026-07-10: 42026-07-11: 42026-07-12: 132026-07-13: 62026-07-14: 02026-07-15: 32026-07-16: 02026-07-17: 52026-07-18: 472026-07-19: 92026-07-20: 112026-07-21: 112026-07-22: 12026-07-23: 42026-07-24: 22026-07-25: 112026-07-26: 52026-07-27: 22026-07-28: 02026-07-29: 02026-07-30: 02026-07-31: 02026-08-01: 02026-08-02: 02026-08-03: 02026-08-04: 102026-08-05: 212026-08-06: 62026-08-07: 12026-08-08: 32026-08-09: 02026-08-10: 42026-08-11: 112026-08-12: 52026-08-13: 02026-08-14: 02026-08-15: 02026-08-16: 02026-08-17: 12026-08-18: 22026-08-19: 252026-08-20: 82026-08-21: 52026-08-22: 02026-08-23: 02026-08-24: 12026-08-25: 02026-08-26: 02026-08-27: 02026-08-28: 92026-08-29: 02026-08-30: 32026-08-31: 102026-09-01: 122026-09-02: 12026-09-03: 12026-09-04: 12026-09-05: 02026-09-06: 02026-09-07: 12026-09-08: 22026-09-09: 02026-09-10: 62026-09-11: 02026-09-12: 02026-09-13: 202026-09-14: 292026-09-15: 22026-09-16: 02026-09-17: 02026-09-18: 62026-09-19: 132026-09-20: 112026-09-21: 72026-09-22: 02026-09-23: 02026-09-24: 12026-09-25: 02026-09-26: 02026-09-27: 62026-09-28: 12026-09-29: 32026-09-30: 22026-10-01: 122026-10-02: 72026-10-03: 12026-10-04: 152026-10-05: 192026-10-06: 02026-10-07: 22026-10-08: 02026-10-09: 02026-10-10: 02026-10-11: 02026-10-12: 02026-10-13: 02026-10-14: 02026-10-15: 02026-10-16: 02026-10-17: 02026-10-18: 02026-10-19: 02026-10-20: 02026-10-21: 02026-10-22: 02026-10-23: 02026-10-24: 02026-10-25: 02026-10-26: 72026-10-27: 1

Linha do tempo

  1. Repositório criado

    Primeiro commit: bolt, uma aplicação Streamlit de um só processo, com seis vistas de fase, um adaptador Taiga e especificações OpenSpec funcionais e técnicas. FastAPI + Next.js vieram depois, a 18-19 de maio.

    Aplicação

  2. Afinações no fluxo de gravação da Fase 2

    Indicador de progresso e mensagem de estado acrescentados ao botão Save & Lock Design.

    Aplicação

  3. Novo cabeçalho da Fase 3

    Título, subtítulo e um diagrama de processo recolhível acrescentados por cima do quadro de tarefas.

    Aplicação

  4. Disposição automática de diagramas

    Disposição automática com um clique nos painéis do diagrama ER e do fluxo de ecrãs.

    Aplicação

  5. Botão Choose New Story

    A etapa Lock & Export da Fase 3 ganha um seletor direto de histórias.

    Aplicação

  6. Enriquecimento de contexto a partir do repositório GitHub

    Versão inicial do que viria a ser o pacote repomix do lado do servidor.

    Aplicação

  7. Painel de análise de governação lançado

    Bolt Cycle Time, Context Traceability Rate, AI Defect Escape Rate: as três métricas que a tese define mais tarde no Capítulo 6.

    Aplicação

  8. Temperatura determinística + verificação do DAG na Fase 3

    Política de temperatura fixada (0 estruturado / 0,2 criativo); cobertura de tarefas verificada no servidor.

    Aplicação

  9. Explicação de EARS na Fase 1

    Explicação integrada da Easy Approach to Requirements Syntax, mais um indicador de carregamento das restrições.

    Aplicação

  10. Redis com várias réplicas em produção

    Bloqueio distribuído verificado com os IP reais do Azure; o backend deixa de estar forçado a uma só réplica.

    Aplicação

  11. Painel de verificação com modelo alternativo

    Um segundo modelo pode agora rever o resultado do primeiro, com um painel de resultados mais completo.

    Aplicação

  12. Integração com o Figma lançada

    Proxy no backend, ligação de frames a histórias e alterações de design assinaladas como desvio na manutenção da Fase 6.

    Aplicação

  13. Chave de API própria

    Chaves OpenAI, Google e Anthropic suportadas por projeto.

    Aplicação

  14. Registo de uso e custo lançado

    Telemetria real de tokens e custos, com o modelo mais barato nas chamadas de triagem.

    Aplicação

  15. Vista de clusters de rastreabilidade

    react-force-graph acrescentado como vista alternativa do grafo de rastreabilidade entre especificação e código.

    Aplicação

  16. Delta de design na Fase 2

    Regeneração incremental do design para histórias acrescentadas depois do bloqueio inicial.

    Aplicação

  17. Pacote repomix no servidor

    O github-context.md passa a ser gerado por um shallow clone + repomix reais, em vez de uma leitura da árvore de ficheiros no cliente.

    Aplicação

  18. Sistema visual gerado por IA

    Geração de design tokens acrescentada à Fase 2.

    Aplicação

  19. Perguntas de clarificação na Fase 1

    Verificação de ambiguidade entre o rascunho em linguagem natural e o Gherkin compilado.

    Aplicação

  20. Sistema de design Impeccable definido

    PRODUCT.md / DESIGN.md escritos, com "The Spec Ledger" como North Star.

    Aplicação

  21. Seletor de ficheiros de agente como base

    AGENTS.md/CLAUDE.md/CODEX.md/GEMINI.md passam a ser contexto selecionável em todas as fases.

    Aplicação

  22. Outfolio escolhido como sujeito de QA

    Um produto real de portfólio para OutSystems, escolhido como o projeto em que o Apex seria demonstrado de ponta a ponta. No mesmo dia: registo do ciclo de vida dos Bolts por tarefa.

    Aplicação

  23. Auditoria completa ao repositório com 5 agentes

    Todas as conclusões Critical/High/Medium/Low fechadas em 24 horas.

    Aplicação

  24. Avisos de erro tipados e traduzidos

    Todas as falhas passam a ser mostradas por omissão através de um único hook partilhado QueryCache/MutationCache.

    Aplicação

  25. Estrutura da dissertação criada

    Modelo do IST preparado. Os dez capítulos criados como esboços \todo, no mesmo dia em que a revisão dos avisos de erro saiu na aplicação.

    Tese

  26. Elementos pré-textuais fechados

    Estrutura da capa, declaração e agradecimentos fixada antes de haver conteúdo em qualquer capítulo.

    Tese

  27. Integração com o Plane.so integrada

    Segundo adaptador de gestão de projeto, com paridade total com o Taiga, motivado pela migração de ferramenta de uma organização parceira a meio do projeto.

    Aplicação

  28. Estatísticas do Capítulo 5 com fonte

    As duas estatísticas motivadoras de RCT/telemetria rastreadas até aos artigos originais.

    Tese

  29. Limitações da API do Plane mitigadas

    Três limites permanentes da plataforma Plane contornados onde possível e documentados onde não.

    Aplicação

  30. Capítulo 6 comprimido de 28 para 18 pp.

    O primeiro corte a sério no capítulo da framework, antes de o limite de páginas se tornar decisivo.

    Tese

  31. Capítulo 7 escrito

    O capítulo da implementação de referência do Apex: arquitetura, mapeamento de construtos, QA e limitações.

    Tese

  32. Desenho do Capítulo 8 pré-registado

    Critérios da demonstração escritos antes de qualquer trabalho de campo, para impedir seleção a posteriori.

    Tese

  33. Instrumentos de avaliação construídos

    8 Google Forms (4 instrumentos × EN/PT): consentimento, Raw NASA-TLX, SUS e questionário de UX do Apex.

    Tese

  34. AI Defect Escape Rate real e independente da ferramenta

    Calculada a partir de issues de gestão de projeto ligadas, tanto no Taiga como no Plane.

    Aplicação

  35. Revisão de redundâncias

    Corte em todo o documento, de 107 para 106 pp., com cada remoção verificada de forma independente.

    Tese

  36. Piloto P0 contado como participante

    Sessão verificada sem problemas nos quatro instrumentos; deixou de ser um piloto descartado.

    Tese

  37. Piloto P0 revela dois erros reais

    Limite de tokens do pacote GitHub e contexto desatualizado tratado como "High Confidence", ambos encontrados ao vivo na primeira sessão real de avaliação.

    Erro encontrado em uso

  38. Correção de páginas em branco no LaTeX

    openright→openany, cleardoublepage→clearpage. Páginas recuperadas sem cortar conteúdo.

    Tese

  39. Recolha de dados da avaliação concluída

    13 participantes para um objetivo de 12, os quatro instrumentos devolvidos, ninguém desistiu.

    Tese

  40. Novo diagrama do ciclo de vida

    Diagrama Graphviz de seis fases acrescentado como Figura 6.1 e reutilizado na capa.

    Tese

  41. Lote de comentários do orientador

    Citações experimentadas em apalike e depois de volta a IEEEtran numerado, seguindo o precedente de Cruz. Profundidade do índice de 5 para 3. Causa do sublinhado em emph encontrada no pacote changes. Figura 7.1 dividida, Declaração movida para página própria, Capítulo 7 renomeado "Proposal Implementation", nome completo do orientador acrescentado à capa.

    Tese

  42. Capítulo 9 escrito com dados reais do estudo

    Resultados de SUS/TLX/UX, seguidos de três revisões no mesmo dia à secção de Discussão.

    Tese

  43. PDF renomeado com jobname

    O ficheiro de saída passou a ist1103641-tomas-taborda-dissertacao.pdf; a fonte continuou a ser main.tex.

    Tese

  44. Capítulo 7 renomeado "Implementation"

    Só muda o título, para o distinguir melhor do "Proposal" do Capítulo 6.

    Tese

  45. Resumo alargado, Secções 5-8 escritas

    Da Implementação de Referência à Discussão, a partir do conteúdo já real dos Capítulos 7 e 9.

    Tese

  46. Registo manual de Fix-Bolts

    Passa a ser possível abrir relatórios de erro no painel sem um cenário de QA falhado como origem.

    Aplicação

  47. Erro de perda de dados no Fix-Bolt encontrado e corrigido

    O fail_gate reescrevia o bug_report_<id>.md em vez de acrescentar um cabeçalho datado. Perda real de dados, encontrada ao escrever o capítulo que descreve os Fix-Bolts.

    Erro encontrado em uso

  48. Visualizador do registo de implantação

    Botão View Deployment Log acrescentado à Fase 5, que mostra diretamente o deployment-log.md.

    Aplicação

  49. Motivos das falhas na cadeia de artefactos visíveis

    A análise explica agora PORQUE é que a cadeia de rastreabilidade de uma história está incompleta.

    Aplicação

  50. Dados de análise da avaliação exportados

    apex-analytics.md/csv e apex-spec-drift gerados a partir do projeto Outfolio em produção.

    Tese

  51. Primeira revisão estrutural de cortes

    2 páginas recuperadas sem tocar na narrativa.

    Tese

  52. Capítulos 8 e 10 escritos com evidência real

    Preenchidos os dois últimos capítulos \todo, com uma revisão de cortes de páginas no mesmo commit.

    Tese

  53. Auditoria final de conformidade com o IST

    Ambos os limites de páginas confirmados: 71/80 no texto principal, 99/100 no documento completo.

    Tese

  54. Resumo alargado ganha figuras e uma tabela

    Diagrama do ciclo de vida, uma tabela de mapeamento de construtos e uma captura real do Portão de Implantação.

    Tese

  55. Bolt Cycle Time em falta na exportação

    O painel calculava-o; a exportação Markdown/CSV nunca o mostrava. Encontrado ao procurar um número para o Capítulo 8.

    Erro encontrado em uso

  56. Narrativa da organização parceira corrigida

    O terceiro contexto de demonstração, abandonado, estava descrito por engano como um teste deliberado ao adaptador; corrigido para a sequência real (Taiga → migração para Plane → atraso).

    Tese

  57. Legenda da Figura 7.1 corrigida

    Legenda reescrita para corresponder à captura real do passo Review Draft ao seu lado.

    Tese

  58. Ligações dos instrumentos no Apêndice B

    URLs reais dos Google Forms EN/PT de cada instrumento, reunidos num só sítio e referidos a partir do Capítulo 9. Corrigido na mesma revisão um erro do xurl (URLs a sair da margem da página).

    Tese

  59. Revisão de dois-pontos, Capítulo 6

    14 frases "afirmação: explicação" reescritas como frases simples ou com um since/because.

    Tese

  60. Revisão de dois-pontos, Capítulo 8

    12 casos reescritos, com a mesma regra.

    Tese

  61. Revisão de dois-pontos, Capítulo 9

    24 casos reescritos, a maior revisão individual; enumerações genuínas e introduções a citações ficaram como estavam.

    Tese

  62. Revisão de dois-pontos, Capítulo 10

    5 casos reescritos, o último dos quatro capítulos.

    Tese

  63. Frase perdida de resposta de IA removida

    Apagado um preâmbulo "Below is a tighter version...", colado por engano no corpo do Capítulo 9.

    Tese

  64. Revisão final do documento completo

    Cada ficheiro .tex comparado com o zip "probably final"; edições genuínas mantidas, reversões desatualizadas recusadas com justificação.

    Tese

  65. Pendentes encerrados

    Lista de pendentes do REGULATIONS.md resolvida: Agradecimentos confirmados, espaçamento da bibliografia e Tabela 9.3 fechados sem ação, secção do júri marcada como vazia por previsão.

    Tese

  66. Este painel construído

    Gerado diretamente a partir do git log e do REGULATIONS.md. Nenhum número nesta página é uma estimativa.

    Tese

  67. Dissertação e resumo alargado entregues

    Entregues no prazo do IST: dissertação com 99/100 pp., resumo alargado com 8/10 pp. Correções de último dia: revisão de dois-pontos e declaração de uso de IA no resumo alargado, um subtítulo invisível na capa e dados do júri não confirmados retirados.

    Tese

  68. Defendida, 17/20

    Defesa pública perante o júri. Dissertação classificada com 17/20.

    Tese

  69. Versão final pós-defesa

    Referências a papéis tornadas coerentes com a Tabela 6.3 (PM como Product Manager, redação coerente com os chapéus), uma segunda revisão de coerência em capítulos e resumos, a decisão do chapéu PM registada no retorno de desvio de negócio do Cap. 8, e o júri confirmado impresso na capa.

    Tese

  70. Painel encerrado

    Última atualização com dados pós-entrega, defesa e nota, mais uma secção de Contexto. Sem mais atualizações previstas.

    Tese

Taxonomia de commits

Todo o repositório, por prefixo de conventional commit.

feat
332
docs
315
fix
310
refactor
25
test
16
chore
10

Capítulos

Todos criados a 4 ago. 2026 como esboços \todo. As datas abaixo indicam quando chegou conteúdo real.

CapítuloPrimeiro conteúdo realCommits
1. Introduçãoinício de ago. 202611
2. Metodologiainício de ago. 202615
3. Enquadramentoinício de ago. 20268
4. Revisão sistemáticainício de ago. 202618
5. Problema11 ago. 202611
6. Proposta (framework)19-20 ago. 202645
7. Apex (implementação)20 ago. 202641
8. Demonstração21 ago. 2026 desenho, 24 set. 2026 conteúdo27
9. Avaliação14 set. 202639
10. Conclusão24 set. 202620
Apêndice ASem data registada11
Apêndice B: instrumentos de avaliaçãoSem data registada18

Encontrado ao escrever sobre o assunto

Erros reais do Apex revelados pelo trabalho da tese e da demonstração.

  1. Limite de tokens do pacote GitHub

    A geração do pacote de programação era truncada em silêncio acima de um limite de tokens, descoberto ao vivo a meio do piloto.

  2. Contexto desatualizado tratado como "High Confidence"

    Uma superfície consultiva de governação indicava confiança alta com evidência que já não estava atual.

  3. Defeito num endpoint partilhado propagado a nove histórias

    Um erro de especificação comum que apareceu em nove histórias. Só foi apanhado porque a demonstração correu à escala de um projeto completo; o plano pré-registado era uma só unidade.

  4. Fix-Bolt reescreve o relatório de erro

    O fail_gate substituía o ficheiro bug_report_<id>.md inteiro em vez de acrescentar; um erro real de perda de histórico, corrigido na mesma sessão em que foi encontrado.

  5. Passagem da Fase 6 descartava o conteúdo em silêncio

    O controlo que abre um item de Manutenção na Fase 1 não levava conteúdo nenhum. O defeito só se via ao usar o retorno; ler o código não o revelava.

  6. Base de dados de produção apagada pelo implementador de IA

    Um script destrutivo de reposição correu contra a produção sem verificar o ambiente, durante uma tarefa de rotina para semear dados. Nenhum portão apanha uma ação destrutiva feita dentro de uma fase.

  7. Deteção de regressões em falta nas exportações de governação

    O registo da demonstração tem uma regressão real, introduzida por um Fix-Bolt e reparada por outro, mas as exportações não têm nenhum campo de regressões para a mostrar.

  8. Bolt Cycle Time em falta na exportação

    Calculado e mostrado no painel, nunca escrito na exportação Markdown/CSV. Encontrado ao tentar citar o número na tese.

Número de páginas

Limites do IST: texto principal até 80 páginas, documento completo até 100.

  1. 107→106

    Revisão de redundâncias: cortadas frases repetidas sem perder conteúdo.

  2. 107→94

    A correção de páginas em branco no LaTeX recuperou páginas sem cortar conteúdo.

  3. −2pp

    Primeira revisão estrutural de cortes.

  4. 99/100

    Auditoria final de conformidade: ambos os limites confirmados com margem.

  5. 100/100

    O valor do Bolt Cycle Time e as ligações do Apêndice B levaram ao limite.

  6. 99/100

    A revisão de dois-pontos recuperou 1 p. de margem.

  7. 99/100

    Revisão de coerência pós-defesa, número de páginas inalterado. Final.

O que a avaliação encontrou

Capítulo 9: 13 sessões não moderadas baseadas em tarefas, mais a demonstração no Outfolio. Dos 12 construtos de governação mapeados (Tabela 7.1), 10 ficaram realizados, 1 usou um indicador indireto e 1 ficou parcial. O Bolt Cycle Time foi inicialmente medido com o indicador errado, o que se detetou ao comparar a implementação com a sua própria definição escrita. A deteção de desvios da especificação ficou parcial para a especificação técnica.

média SUS, nota D
56,73
carga NASA-TLX, baixa
21,5/100
Context Traceability Rate
92,6%
Conformidade com a especificação
98,65%
AI Defect Escape Rate
1,85%
Bolt Cycle Time, mediana
0,22 h
épicos / histórias do Outfolio
9 / 54
dias de calendário, demonstração
9
commits do Outfolio
123
retornos exercitados
3 / 3

Escala

Árvore de trabalho final, mais os totais de diff de todo o histórico.

linhas de frontend, .ts/.tsx
48,9 mil
linhas de backend, .py
26,8 mil
linhas de testes de backend
22,6 mil
inserções, todo o histórico
252,8 mil
remoções, todo o histórico
61,7 mil
dia mais ativo, commits (18 jul.)
47
rondas de revisão do Overleaf sincronizadas
11

Commits da tese, últimas 8 semanas

Só docs/thesis, pela data de início de cada semana ISO.

7/09
26
14/09
30
21/09
7
28/09
40
5/10
15
12/10
0
19/10
0
26/10
7

Estado final

documento completo, PDF final
99/100
texto principal, última auditoria a 27 set. 2026
71/80
resumo alargado, PDF final em inglês
8/10
defendida a 23 out. 2026
17/20
participantes, nenhum desistiu
13/12

Pendentes, encerrados a 5 out. 2026

  • Agradecimentos

    Conteúdo e nome do orientador confirmados; o pendente no REGULATIONS.md era uma nota antiga.

  • Espaçamento simples na bibliografia

    Fechado sem avançar. O documento tem margem sem as páginas extra que recuperaria.

  • Tabela 9.3 (matriz NASA-TLX)

    Fica, por decisão explícita. Sem mais propostas para a apagar.

  • Secção do júri

    Deixada em branco na entrega por previsão; o júri confirmado foi impresso na capa na versão final de 26 de outubro de 2026.

  • Ambos os limites de páginas

    Texto principal 71/80, documento completo 99/100; ambos cumpridos nas versões entregue e final.

  • Recolha de dados da avaliação

    13 participantes para um objetivo de 12. Os quatro instrumentos devolvidos. Ninguém desistiu.

Gerado a partir do git log local e do docs/thesis/REGULATIONS.md. Última atualização a 27 out. 2026, depois da defesa. Último commit a 26 out. 2026.