construct — transforme uma ideia de produto em um conjunto de d…

construct — transforme uma ideia de produto em um conjunto de Documentos de Requisitos de Software fundamentado e executável

construct transforma uma ideia de produto em um conjunto de Documentos de Requisitos de Software (SRD) cujos requisitos e decisões são fundamentados em pesquisa real, e não na memória do modelo.

O motor determinístico (scripts/construct.mjs, Node sem dependências) faz a busca, montagem do dossiê, renderização e validação do SRD com código; seu trabalho é conduzir a entrevista, direcionar a pesquisa e enriquecer o esqueleto renderizado para obter um SRD preciso e bem fundamentado.

A regra central: prefira um requisito fundamentado a um adivinhado. Use a pesquisa que o motor recupera (concorrentes, trabalhos anteriores em OSS, documentação técnica, StackOverflow) para justificar escopo, requisitos não funcionais (NFRs) e decisões de arquitetura, e cite a evidência com [E#]. A fundamentação é consultiva aqui — construct check relata a cobertura, mas nunca falha por causa dela — portanto, o rigor é seu para aplicar.

O script

Um único arquivo consolidado, sem dependências: node scripts/construct.mjs <comando>. Sem npm install, sem chaves de API. Execute --help para ver a superfície completa. Comandos principais:

• init --idea "<descrição curta>" --out <execução> — cria a estrutura de pastas da execução + brief.json.
• research --out <execução> [--angles mercado,oss,tech,semantico] [--q "<foco>"] [--semantico] — coleta evidências de vários ângulos em <execução>/evidence/ (um dossiê EVIDENCE.md + evidence.json com IDs [E#]). Ângulos padrão: mercado,oss,tech.
• analyze --out <execução> [--json] — o relatório "o que está raso?": nomeia cada funcionalidade/concorrente/tecnologia/semente que será renderizada como NÃO FUNDAMENTADA, e imprime o comando de aprofundamento que corrige cada lacuna. Informativo, nunca bloqueia.
• web|oss|tech|so --out <execução> [--q "<foco>"] [--url ...] [--seeds ...] [--docs-url <u,...>] — aprofunda UM ângulo na saída padrão (sem dossiê). Use para se aprofundar em um tópico raso; --docs-url fundamenta páginas de documentação conhecidas diretamente.
• render --out <execução> [--level leve|complexo] [--merge] — renderiza a árvore SRD + SRD.json a partir de brief.json + o dossiê.
• check --out <execução> [--min-grounding <0-100>] [--semantico] [--json] — a verificação estrutural rígida (código de saída ≠ 0 se o SRD estiver incompleto) mais o relatório de cobertura de fundamentação consultivo. --min-grounding N ativa uma segunda barreira que falha abaixo de N% de claims fundamentados; --semantico incorpora VERIFY.json (veja review) e falha em qualquer claim refutado/não suportado. (Distinto de research --semantico, que apenas reordena evidências por relevância de embedding.)
• review --out <execução> [--apply <veredictos.json>] [--max-review N] [--json] — a ferramenta de suporte a claims. Sem --apply ele escreve uma lista de trabalho claim↔evidência (VERIFY.todo.json + VERIFY.md): cada claim fundamentado pareado com cada trecho de [E#] citado para ser julgado. --apply <veredictos.json> reduz seus veredictos (supported|partial|refuted|unsupported) em VERIFY.json, no qual check --semantico se baseia. Distribua conforme references/orchestration.md.
• verify --out <execução> [--app <dir>] [--run-tests] [--strict] [--json] — o árbitro da construção: BUILD-PLAN.json bem formado e acíclico, toda referência de tarefa resolve em SRD.json, arquivos de tarefas concluídas existem, todo requisito é referenciado por um teste. --run-tests também executa os comandos de teste declarados; --strict falha se um must-have construído não tiver teste que o referencie.
• status --out <execução> [--json] — o que existe na execução até agora; --json adiciona a fronteira de construção (quais tarefas do BUILD-PLAN são construíveis agora vs. bloqueadas).
• semantico up|down|status — pilha Docker local opcional (Qdrant + Ollama + SearXNG).

Fluxo de trabalho

Você é invocado uma vez e espera-se que retorne um SRD completo e fundamentado. Conduza o ciclo até a conclusão; pause apenas para perguntar ao usuário uma decisão real.

1. Entreviste o usuário — uma pergunta de cada vez. Estabeleça o produto antes de pesquisar. Siga references/interview-playbook.md: problema, usuários-alvo, valor central, funcionalidades must/should/could, restrições (orçamento, cronograma, equipe, conformidade), tecnologias candidatas e quaisquer concorrentes / sementes OSS. Recomende uma resposta a cada pergunta; não despeje um questionário. Escreva as respostas em brief.json (inicie com construct init).

2. Pesquise — fundamente a ideia. Execute:

   node scripts/construct.mjs research --out <execução> --angles mercado,oss,tech
   

   Isso descobre concorrentes na web, minera projetos OSS comparáveis (e seus issues/PRs para armadilhas reais) e puxa documentação de tecnologias candidatas + StackOverflow. Leia <execução>/evidence/EVIDENCE.md.

3. Aprofunde — até que analyze esteja limpo ou o usuário o pare. Execute:

   node scripts/construct.mjs analyze --out <execução>
   

   Ele nomeia exatamente o que está raso — funcionalidades, concorrentes, tecnologia candidata e sementes OSS sem evidências correspondentes — e imprime o comando de aprofundamento que corrige cada lacuna. Distribua: se você pode criar subagentes paralelos, despache um por lacuna; cada um recebe a descrição curta, a lacuna, seu comando de aprofundamento e seu próprio WebSearch, e retorna um resumo de ≤5 linhas mais URLs que valem a pena fundamentar. Subagentes NÃO DEVEM escrever na pasta da execução — os aprofundamentos imprimem na saída padrão; apenas construct research escreve o dossiê, e apenas VOCÊ o executa. Incorpore os achados serialmente: construct web --url <u,...> --out <execução> → execute research novamente → execute analyze novamente. (Sem subagentes? Trabalhe as lacunas você mesmo, um aprofundamento de cada vez.) Conte ao usuário o que encontrou e deixe-o direcionar — priorize funcionalidades must-have e decisões críticas, pare quando ele disser que é suficiente. Consulte references/orchestration.md e references/research-playbook.md.

4. Renderize o SRD. Quando o brief estiver sólido e o dossiê estiver rico:

   node scripts/construct.mjs render --out <execução> --level complexo
   

   Escolha complexo sempre que uma construção for mesmo possível; mudar de nível depois renumerará IDs de FR (veja references/srd-authoring.md). Isso escreve a árvore SRD (veja abaixo). O modelo de dados e as interfaces vêm pré-preenchidos por inferência do brief — verifique-os, não confie neles. Em seguida, enriqueça-o: resolva cada chamada 🧠 Decida:, refine os critérios de aceitação e métricas NFR modelados em declarações testáveis e delimitadas (siga references/acceptance-criteria.md — check avisa enquanto algum permanecer modelado), corrija/estenda o modelo de dados e interfaces, e adicione citações [E#] do dossiê aos requisitos e decisões que os fundamentam. Consulte references/srd-authoring.md e references/citation-format.md. No nível complexo, enriqueça também o sistema de design (design/): substitua os tokens de design semeados pelos reais valores da marca do produto, verifique o inventário de componentes e telas/fluxos, e refine os critérios de acessibilidade para o padrão alvo (derivado do brief, padrão WCAG 2.2 AA). Consulte references/design-system-authoring.md.

5. Revisão adversarial — deixe olhos novos quebrá-lo. Crie um subagente revisor sem NENHUM contexto além do caminho da pasta de execução e references/adversarial-review.md (sem subagentes? faça a passagem você mesmo, seguindo estritamente essa lista de verificação como um leitor hostil). Ele deve tentar quebrar o SRD — ambiguidade, critérios não testáveis, caminhos de falha ausentes, lavagem de citações, contradições — e retornar achados marcados. Corrija cada [blocker], use julgamento em [advisory], então execute check novamente. Itere enquanto novos blockers aparecerem (limite: 3 rodadas, então apresente o que restar ao usuário). Para uma ADR genuinamente contestada e difícil de reverter no nível complexo, execute também o painel de 3 juízes de references/orchestration.md.

6. Valide (três camadas).

   • Estrutural (rígida): node scripts/construct.mjs check --out <execução>. Falha em qualquer 🧠 não resolvido, nenhum requisito funcional, um FR sem critério de aceitação, uma referência a entidade/interface/NFR pendente, uma categoria NFR obrigatória ausente ou uma ADR malformada. Corrija até passar.
   • Fundamentação (consultiva): o mesmo comando imprime a cobertura — que fração dos requisitos/decisões citam evidências. Eleve onde for importante (as decisões críticas); consulte references/grounding-coverage.md. Por padrão, nunca falha a construção, então use julgamento. Quando o usuário quiser a fundamentação imposta, adicione a barreira opt-in: check --out <execução> --min-grounding 70.
   • Suporte a claims (consultiva → barreira opt-in): cobertura conta citações; ela não verifica se elas se sustentam. construct review --out <execução> constrói uma lista de trabalho claim↔evidência; julgue cada par (distribua conforme references/orchestration.md Padrão 4), monte verdicts.json, review --apply verdicts.json, então check --out <execução> --semantico para barrar claims refutados/não suportados. Vale uma passagem sobre os FRs/ADRs críticos antes de apresentar. Itere as etapas 3–6 até que check passe estruturalmente, o revisor não encontre novos blockers e a fundamentação seja honesta.

7. Apresente. Entregue ao usuário o conjunto SRD: a visão, o cenário competitivo, os requisitos fundamentados e as principais decisões (com suas evidências [E#] e links). Marque explicitamente quaisquer incógnitas em vez de adivinhar.

8. Construa (quando o usuário quiser o aplicativo, não apenas o SRD). A renderização também emitiu BUILD-PLAN.json — um DAG de tarefas legível por máquina (esqueleto T-000 + uma tarefa por FR, must → should → could, dependências cientes de entidades) cujas entradas acceptance APONTAM para SRD.json. Você escreve todo o código do aplicativo; o motor é o árbitro. Siga references/build-playbook.md:

   • Faça T-000 (estrutura, harness de teste, CI); defina conventions.appDir e conventions.testCommand em BUILD-PLAN.json.
   • Por tarefa, em ordem topológica: leia os critérios de aceitação de SRD.json; faça TDD — cada teste nomeia seu ID de FR (ex.: describe("FR-001 …"); é isso que verify busca); registre artifacts + tests; defina status: "done"; execute node scripts/construct.mjs verify --out <execução> e corrija qualquer erro antes da próxima tarefa.
   • Tarefas do mesmo marco não têm arestas entre si, portanto sua fronteira pronta (status --out <execução> --json) pode ser construída em paralelo — uma worktree git isolada por tarefa; você sozinho consolida os resultados em BUILD-PLAN.json (Padrão 5 em references/orchestration.md).
   • Por marco: verify --out <execução> --run-tests --strict, depois uma revisão adversarial do marco — olhos novos procurando um critério de aceitação que nenhum teste realmente exercita (veja o playbook; references/verify.md explica o que verify pode e não pode provar).
   • Se um FR se mostrar errado durante a construção, altere o brief, renderize novamente (o progresso é mesclado por título de funcionalidade), reatualize os IDs de FR deslocados, execute check novamente.

O que produz (a árvore SRD, sob --out)

00-overview/   VISION.md · SCOPE.md (+ 🧠 decisões em aberto)
requirements/  FUNCTIONAL.md (FR-NNN · prioridade · Given/When/Then · [E#])
               NON-FUNCTIONAL.md (NFR-NNN por categoria · métrica · [E#])
architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
               decisions/NNNN-*.md  (ADRs)
design/        PRINCIPLES.md · DESIGN-TOKENS.md (+ design-tokens.json) · COMPONENTS.md
               SCREENS.md · ACCESSIBILITY.md      (apenas complexo; --no-design para pular)
competitive/   LANDSCAPE.md (concorrentes + trabalhos anteriores em OSS)
BUILD-PLAN.md · BUILD-PLAN.json (DAG de tarefas para a fase de construção)
TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ entidade ↔ interface ↔ componente ↔ tela)
evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json

leve mantém enxuto; complexo adiciona o conjunto completo de NFRs, uma segunda ADR, critérios de aceitação de caminhos de falha, a matriz de rastreabilidade completa e uma subárvore do sistema de design (design/: princípios, tokens, componentes, telas/fluxos, um contrato de acessibilidade — --no-design desativa). Adicione --merge para um único arquivo SRD.md.

Modo semântico opcional (totalmente local, sem chave de API)

Os ângulos mercado/OSS/tech precisam apenas de acesso à rede. Para uma passagem de relevância sobre as evidências coletadas, você pode ativar um modelo de embedding local:

node scripts/construct.mjs semantico up        # docker: Qdrant + Ollama + SearXNG
node scripts/construct.mjs research --out <execução> --angles mercado,oss,tech,semantico --semantico

Tudo roda em contêineres Docker locais — sem chave, nenhum dado sai da máquina. Se a pilha não estiver ativa, --semantico registra um aviso e mantém a classificação lexical. Consulte references/semantic-setup.md.

Referências

• references/interview-playbook.md — como eliciar o brief, uma pergunta de cada vez.
• references/research-playbook.md — escolher ângulos e se aprofundar até "bom o suficiente".
• references/orchestration.md — o modelo de fluxo de trabalho dinâmico de três camadas e os padrões de subagentes: distribuição de pesquisa, time vermelho, painel de juízes, distribuição de revisão de suporte a claims, distribuição de construção (e a regra de um único escritor).
• references/adversarial-review.md — a lista de verificação do time vermelho e seu contrato de achados.
• references/srd-authoring.md — resolver chamadas 🧠, escrever requisitos e ADRs testáveis.
• references/design-system-authoring.md — enriquecer o sistema de design complexo: tokens, componentes, telas/fluxos e o contrato de acessibilidade.
• references/acceptance-criteria.md — reescritas Given/When/Then de ruim para bom e padrões de métricas NFR mensuráveis.
• references/citation-format.md — a convenção de fundamentação [E#].
• references/grounding-coverage.md — o que significa o relatório de cobertura consultivo e como elevá-lo.
• references/build-playbook.md — o ciclo de construção: TDD de tarefas, convenção de tag FR, barreiras de marco, a revisão de marco.
• references/verify.md — o que cada verificação de verify prova e o que ainda precisa de olhos humanos.
• references/provider-apis.md — como issues/PRs de OSS são buscados por host, sem chave.
• references/web-discovery.md — a busca web em camadas sem chave.
• references/semantic-setup.md — a pilha Docker local opcional.