# Project Discovery - Roadmap de maturidade do sdd-layer

## Rastreabilidade
- Orquestração: `roadmap-de-maturidade-do-sdd-layer-gate-unico-de-release-corrigir-jest-do-bot-modul-960734c3de8d`
- Stage: project-discovery
- Estado atual: recorded
- Entrada: roadmap de maturidade com gate único de release, Jest do bot, modularização do CLI/TUI, resiliência Jira/GitHub, testes de precisão, checks opcionais em CI e `sdd maintenance report`.
- Context Pack derivado: `.sdd/intelligence/context-packs/roadmap-de-maturidade-do-sdd-layer-gate-unico-de-release-corrigir-jest-do-bot-modul-960734c3de8d/project-discovery.md`

## Identidade do projeto
- Projeto: `sdd-layer`
- Tipo: CLI Rust e camada de orquestração Spec-Driven Development.
- Lifecycle: brownfield.
- Stack principal: Rust 2021, Clap, Ratatui/Crossterm, Serde, SQLite via `rusqlite`, docs site Next/Fumadocs, bot TypeScript/Jest.
- Contrato central: core runtime-agnostic, provider-neutral, artifact store local, traceability map, validators e doctors determinísticos.

## Visualizações e documentação HTML
- HTML companion planejado: `00-project-discovery.html`.
- Estado: não materializado nesta etapa manual; o Context Pack e este Markdown são a fonte usada para PRD.

```mermaid
flowchart LR
  A["sdd-layer"] --> B["Core Rust CLI"]
  A --> C["TUI"]
  A --> D["Bot TypeScript"]
  A --> E["Docs site"]
  A --> F["Client surfaces"]
  A --> G["Artifact contracts"]
```

## Estrutura observada
- `src/main.rs`: composition root e grande parte dos comandos CLI.
- `src/domain/`: domínio do orquestrador, risk, providers, discovery e workflow.
- `src/runtime/`: MCP, ACP, trace, redaction, providers auxiliares e optimization.
- `src/tui/`: experiência terminal, execução, renderização, estado e providers.
- `bot/`: integração Slack/Jira/Bitbucket/GitHub em TypeScript.
- `docs-site/`: documentação Fumadocs/Next.
- `schemas/`, `templates/`, `clients/`, `.agents/`, `.claude/`, `.cursor/`, `.devin/`, `.opencode/`, `.trae/`: contratos e mirrors multi-client.

## Inventário técnico detalhado
- Manifests:
  - `Cargo.toml`: package `sdd-layer`, binário `sdd`, features opcionais `acp-agent`, `mcp-rmcp`, `rig-adapter`.
  - `bot/package.json`: scripts `build`, `test`, `dev`, integrações LLM/work tracker.
  - `docs-site/package.json`: scripts `docs:generate`, `docs:links`, `build`, `check`.
- CI:
  - `.github/workflows/sdd-layer.yml`
  - `.github/workflows/sdd.yml`
- Sinais observados na avaliação anterior:
  - `cargo test --locked`: 481 passed.
  - `cargo test --locked --all-features`: 482 passed.
  - docs site build/links/generate check verdes.
  - bot `npm run build` verde.
  - bot `npm test` falha em `githubProvider.test.ts` por `execa` ESM com Jest CommonJS.
  - `cargo fmt --check` e `cargo clippy --all-targets --all-features -- -D warnings` falham no diff atual.

## Comandos verificados
- `sdd resolve-input "<demanda>"`
- `sdd init "<name>"`
- `sdd context build --name "<name>" --stage project-discovery --write`
- `sdd context build --name "<name>" --stage idea --write`
- `sdd context build --name "<name>" --stage prd --write`
- Verificações de maturidade executadas antes desta orquestração:
  - `cargo test --locked`
  - `cargo test --locked --all-features`
  - `cargo fmt --check`
  - `cargo clippy --all-targets --all-features -- -D warnings`
  - `cargo run --quiet -- health --json`
  - `npm run build` em `bot/`
  - `npm test -- --runInBand` em `bot/`
  - `npm run docs:generate -- --check`, `npm run docs:links`, `npm run build` em `docs-site/`

## Arquitetura e padrões
- O repositório é fortemente declarativo: mudanças em runtime, docs, templates, skills, clients e schemas precisam ficar sincronizadas.
- ADRs existentes preservam o core como dono do contrato SDLC e tratam runtimes/adapters como opcionais.
- `src/main.rs` ainda é composition root pesado; a estratégia aceita historicamente é DDD incremental, não reescrita ampla.
- A TUI foi decidida como determinística, sem IA obrigatória, usando subcomandos `sdd` como fronteira de mutação.
- Artifact store local e `traceability-map.yaml` continuam fonte canônica local.

## Linguagem de domínio
- Gate obrigatório: check que bloqueia release/merge.
- Advisory: check opcional que deve aparecer no relatório, mas não bloquear quando a ferramenta não existe.
- Surface: área pública ou distribuída do produto, como CLI, bot, docs, clients ou MCP/ACP.
- Precision: capacidade de validar que artefatos SDD estão completos, rastreáveis e semanticamente coerentes.
- Maintenance report: visão agregada por área com status, evidências, riscos e próximos comandos.

## Riscos do projeto
- Refactor grande em `src/main.rs`/TUI pode conflitar com worktree sujo e regressões em comandos existentes.
- Gate único pode ficar lento ou rígido demais se não separar obrigatório de advisory.
- Checks opcionais podem virar falso negativo em ambientes sem ferramentas.
- Integrações Jira/GitHub precisam de timeout/redaction para evitar travamento e vazamento.
- Golden tests frágeis podem bloquear evolução legítima de textos.

## Regras para a pipeline
- Risco calibrado como `medium`; Refinement é obrigatório.
- Tech Spec deve usar CodeGraph antes de propor extrações.
- Execution deve ocorrer task-by-task e preservar mudanças locais existentes.
- Review deve separar achados por área: Rust core, TUI, bot, docs, clients, providers, intelligence, workflows e release.
- PRD e Tech Spec exigem checkpoint humano antes de avançar.

## Recomendações de skills e regras
- `architecture-deepening`: obrigatório na Tech Spec para modularização.
- `ci-release`: obrigatório para gate único e CI.
- `test-strategy`: obrigatório para golden/property tests.
- `security-privacy`: obrigatório para Jira/GitHub, redaction e checks opcionais.
- `provider-compatibility`: obrigatório para manter o fluxo provider-neutral.
- `artifact-schemas`: obrigatório antes de avançar artefatos.

## Capability map
| Capability | Fonte | Stages | Risco | Fallback |
|---|---|---|---|---|
| CodeGraph | `.codegraph/` disponível | Tech Spec, Execution, Review | índice pode defasar após edits | `rg --files`, `rg`, leitura focada |
| Doctors SDD | CLI `sdd` | Discovery, Review, Release | divergência entre docs e binário instalado | executar comandos reais |
| Docs site checks | `docs-site/package.json` | Review, Release | dependência Node/Next | registrar skipped se ambiente ausente |
| Bot tests | `bot/package.json` | Execution, Review | Jest/ESM | mock/adapter/ESM config |
| Optional security checks | ferramentas externas | Review, Release | falso bloqueio | advisory + ação recomendada |

## Contexto para próximos agentes
- Use sempre `--name "roadmap-de-maturidade-do-sdd-layer-gate-unico-de-release-corrigir-jest-do-bot-modul-960734c3de8d"`.
- Antes da Tech Spec, leia este Discovery, Risk, Idea, PRD e os ADRs sobre runtime-agnostic core, TUI determinística, DDD incremental e orquestrador autônomo.
- Use CodeGraph para mapear `run_ci`, `client_doctor`, `capability_doctor`, `skills_doctor`, TUI runner/app/ui e provider integrations.
- Não implemente antes do checkpoint do PRD.
