spec-first-copilot 0.7.0 → 0.8.0-beta.2

package/templates/.github/skills/sf-merge-docs/SKILL.md

@@ -1,152 +1,152 @@
-
-# /sf-merge-docs $ARGUMENTS
-
-Skill atômica pós-dev. Aplica as decisões de **PRD + TRD aprovados** em `docs/` pra manter a síntese cross-feature sincronizada com o estado do sistema.
-`$ARGUMENTS` = nome do scope (ex: `feat_cadastro_cliente`).
-
-Chamado automaticamente pelo `/sf-dev` ao final. Re-executável manualmente quando precisa.
-
-> **Mudança v3 → v4**: antes aplicava `SDD §11 Delta Specs` (mecanismo OpenSpec).
-> Agora lê **PRD + TRD aprovados diretamente** e infere o delta comparando com
-> o estado atual de `docs/` (diff semântico). SDD não existe mais em v4.
-
-## Agente: Integrator (Opus)
-
-Em v4 promovido de Sonnet → Opus: diff semântico PRD/TRD ↔ docs/ exige reasoning
-de maior nível que o antigo "aplicar §11 explícito". Meticuloso com consistência.
-Merge idempotente — re-aplicar os mesmos docs source não duplica conteúdo.
-
-## Pré-condições
-
-| # | Validação | Se falhar |
-|---|-----------|-----------|
-| 1 | `$ARGUMENTS` informado | Parar |
-| 2 | `.context.md` com status `dev_done` (uso auto no /sf-dev) OU `design_done` a mais (uso manual) | Se anterior → "Rode /sf-design primeiro" |
-| 3 | Pelo menos PRD.md OU TRD.md existe e está aprovado | Parar — "Nenhum doc source aprovado pra mergear" |
-| 4 | `docs/` populado (veio de first-run anterior) | Parar — "/sf-design com first_run=true é quem cria docs/" |
-
-> `/sf-merge-docs` **só se aplica a features**, não a first-run. Em first-run, é o
-> próprio `/sf-design` que cria `docs/` a partir de PRD+TRD — não há o que mergear.
-
-## Passos
-
-### 1. Snapshot do estado atual de docs/
-
-Ler `docs/{architecture,domain,conventions,apiContracts,decisions}.md`.
-Indexar por elementos (tabelas, endpoints, ADRs, papéis, env vars...) pra diff.
-
-### 2. Extrair elementos-destino do PRD e TRD aprovados
-
-| Fonte (PRD/TRD) | Elemento | Destino em docs/ |
-|-----------------|----------|------------------|
-| TRD §1.1 Stack | Nova tecnologia / versão | `architecture.md` §Stack |
-| TRD §1.2 Arquitetura | Novo container / padrão | `architecture.md` §Containers/Padrões |
-| TRD §1.3 Ambientes | Novo ambiente / mudança | `architecture.md` §Ambientes |
-| TRD §1.4 Deploy | Mudança na estratégia | `architecture.md` §Deploy |
-| TRD §4 §Área-DB | Nova tabela / índice / FK | `domain.md` §Catálogo de Tabelas |
-| TRD §2.1 Endpoints | Novo endpoint | `apiContracts.md` §Catálogo |
-| TRD §7.1 Auth | Mudança em auth | `conventions.md` §Autenticação |
-| TRD §7.2 Autorização | Novo papel / permissão | `conventions.md` §Autorização |
-| TRD §7.3 LGPD | Novo dado pessoal | `conventions.md` §LGPD |
-| TRD §7.4 Rate limit | Nova categoria | `conventions.md` §Rate Limiting |
-| TRD §5.3 Env vars | Nova variável | `conventions.md` §Variáveis de Ambiente |
-| TRD §6 Integrações | Novo sistema externo | `domain.md` §Integrações Externas |
-| TRD §9 ADRs | Nova decisão | `decisions.md` (append-only, imutável) |
-| PRD §2 Atores | Novo papel/persona | `domain.md` §Usuários e Papéis |
-| PRD §5 RNs | Nova regra de negócio | (não vai pra docs/ — fica em specs/{nome}/contracts.md) |
-
-> **Regra**: PRD alimenta poucas seções de `docs/` (só atores e alto-nível).
-> O grosso vem do TRD — `docs/` é síntese técnica + negócio cross-feature.
-
-### 3. Diff semântico: calcular ADDED / MODIFIED / REMOVED
-
-Pra cada elemento-destino extraído (passo 2), comparar com snapshot (passo 1):
-
-| Resultado | Condição | Ação |
-|-----------|----------|------|
-| ADDED | Elemento não existe em docs/ | Adicionar na seção apropriada |
-| MODIFIED | Elemento existe mas mudou (nome igual, valor diferente) | Atualizar campos |
-| UNCHANGED | Elemento existe e está igual | Skip (idempotente) |
-| REMOVED | Elemento estava em docs/ mas não aparece em PRD+TRD aprovados | **NÃO remover** — apenas registrar no output como "possivelmente orfão" |
-
-> **Conservadorismo em REMOVED**: PRD/TRD falam só da feature atual. Algo que
-> "não aparece" pode ser de outra feature (que continua válida). NUNCA deletar
-> automaticamente. Reportar e deixar remoção manual.
-
-### 4. Aplicar ADDED e MODIFIED
-
-- Localizar seção apropriada no doc destino
-- Preservar estrutura do template (não quebrar tabelas)
-- ADRs em `decisions.md`: SEMPRE append; ADR com status=aceita é imutável
-- Registrar cada mudança em changelog do doc afetado
-
-### 5. Changelog em cada doc afetado
-
-Adicionar linha no `## Changelog` do doc:
-
-```markdown
-| Data | Feature | Tipo | Descrição |
-|------|---------|------|-----------|
-| {{ISO_DATE}} | $ARGUMENTS | ADDED | Endpoint POST /api/v1/users |
-| {{ISO_DATE}} | $ARGUMENTS | MODIFIED | Matriz de permissões: novo role `manager` |
-```
-
-### 6. Validar consistência cross-doc
-
-- Referências quebradas (endpoint do apiContracts referencia tabela que não existe em domain) → reportar
-- Papel novo em conventions mas não aparece em matriz de autorização → reportar
-- ADR substituída mas ainda referenciada → reportar
-
-Validação reporta, não bloqueia. Usuário decide se resolve manualmente.
-
-### 7. Atualizar status
-
-```yaml
-status: "done"
-ultima_skill: "/sf-merge-docs"
-atualizado_em: "{{ISO_DATETIME}}"
-```
-
-### 8. Saída obrigatória
-
-```
-/sf-merge-docs $ARGUMENTS — completo
-
-docs/ sincronizado com PRD + TRD aprovados:
-- docs/architecture.md    (2 ADDED, 0 MODIFIED)
-- docs/apiContracts.md    (3 ADDED, 1 MODIFIED)
-- docs/conventions.md     (0 ADDED, 1 MODIFIED — novo role)
-- docs/decisions.md       (1 ADDED — ADR-007)
-- docs/domain.md          (0 mudanças)
-
-Possivelmente órfãos (NÃO removidos — revisão manual):
-  - docs/apiContracts.md: endpoint `/legacy/foo` não aparece em PRD+TRD novos
-    (pode ser de outra feature; deletar manualmente se confirmado deprecated)
-
-Validação: passed / N issues
-```
-
-## Erros
-
-| Erro | Ação |
-|------|------|
-| Status != `dev_done` (auto) nem >= `design_done` (manual) | Parar — pedir rodar /sf-dev ou /sf-design primeiro |
-| `docs/` não existe | Parar — explicar que `/sf-design` em first-run cria docs/ (feature só atualiza) |
-| PRD+TRD sem nada novo vs docs/ | Marcar `done` (legítimo — feature sem impacto cross-feature) |
-| Elemento MODIFIED não encontrado no doc | Converter pra ADDED + reportar (doc estava desatualizado) |
-| Referências quebradas detectadas | Reportar, não bloqueia |
-
-## Uso automático (pelo `/sf-dev`)
-
-`/sf-dev` chama `/sf-merge-docs` automaticamente ao final de feature (não first-run):
-
-- Condição: `status=dev_done` E `first_run=false` E (`prd_aprovado=true` OU `trd_aprovado=true`)
-- Rodado inline, sem nova interação
-- Falha em `/sf-merge-docs` não derruba `/sf-dev` — apenas reporta; user pode re-rodar manualmente
-
-## Uso manual
-
-Rodar `/sf-merge-docs $ARGUMENTS` quando:
-- `/sf-dev` falhou e você quer sincronizar docs/ com o que já foi aprovado
-- Fez edição direta em PRD/TRD aprovados e quer propagar pra docs/
-- Quer forçar um re-merge (idempotente — não duplica)
+
+# /sf-merge-docs $ARGUMENTS
+
+Skill atômica pós-dev. Aplica as decisões de **PRD + TRD aprovados** em `docs/` pra manter a síntese cross-feature sincronizada com o estado do sistema.
+`$ARGUMENTS` = nome do scope (ex: `feat_cadastro_cliente`).
+
+Chamado automaticamente pelo `/sf-dev` ao final. Re-executável manualmente quando precisa.
+
+> **Mudança v3 → v4**: antes aplicava `SDD §11 Delta Specs` (mecanismo OpenSpec).
+> Agora lê **PRD + TRD aprovados diretamente** e infere o delta comparando com
+> o estado atual de `docs/` (diff semântico). SDD não existe mais em v4.
+
+## Agente: Integrator (Opus)
+
+Em v4 promovido de Sonnet → Opus: diff semântico PRD/TRD ↔ docs/ exige reasoning
+de maior nível que o antigo "aplicar §11 explícito". Meticuloso com consistência.
+Merge idempotente — re-aplicar os mesmos docs source não duplica conteúdo.
+
+## Pré-condições
+
+| # | Validação | Se falhar |
+|---|-----------|-----------|
+| 1 | `$ARGUMENTS` informado | Parar |
+| 2 | `.context.md` com status `dev_done` (uso auto no /sf-dev) OU `design_done` a mais (uso manual) | Se anterior → "Rode /sf-design primeiro" |
+| 3 | Pelo menos PRD.md OU TRD.md existe e está aprovado | Parar — "Nenhum doc source aprovado pra mergear" |
+| 4 | `docs/` populado (veio de first-run anterior) | Parar — "/sf-design com first_run=true é quem cria docs/" |
+
+> `/sf-merge-docs` **só se aplica a features**, não a first-run. Em first-run, é o
+> próprio `/sf-design` que cria `docs/` a partir de PRD+TRD — não há o que mergear.
+
+## Passos
+
+### 1. Snapshot do estado atual de docs/
+
+Ler `docs/{architecture,domain,conventions,apiContracts,decisions}.md`.
+Indexar por elementos (tabelas, endpoints, ADRs, papéis, env vars...) pra diff.
+
+### 2. Extrair elementos-destino do PRD e TRD aprovados
+
+| Fonte (PRD/TRD) | Elemento | Destino em docs/ |
+|-----------------|----------|------------------|
+| TRD §1.1 Stack | Nova tecnologia / versão | `architecture.md` §Stack |
+| TRD §1.2 Arquitetura | Novo container / padrão | `architecture.md` §Containers/Padrões |
+| TRD §1.3 Ambientes | Novo ambiente / mudança | `architecture.md` §Ambientes |
+| TRD §1.4 Deploy | Mudança na estratégia | `architecture.md` §Deploy |
+| TRD §4 §Área-DB | Nova tabela / índice / FK | `domain.md` §Catálogo de Tabelas |
+| TRD §2.1 Endpoints | Novo endpoint | `apiContracts.md` §Catálogo |
+| TRD §7.1 Auth | Mudança em auth | `conventions.md` §Autenticação |
+| TRD §7.2 Autorização | Novo papel / permissão | `conventions.md` §Autorização |
+| TRD §7.3 LGPD | Novo dado pessoal | `conventions.md` §LGPD |
+| TRD §7.4 Rate limit | Nova categoria | `conventions.md` §Rate Limiting |
+| TRD §5.3 Env vars | Nova variável | `conventions.md` §Variáveis de Ambiente |
+| TRD §6 Integrações | Novo sistema externo | `domain.md` §Integrações Externas |
+| TRD §9 ADRs | Nova decisão | `decisions.md` (append-only, imutável) |
+| PRD §2 Atores | Novo papel/persona | `domain.md` §Usuários e Papéis |
+| PRD §5 RNs | Nova regra de negócio | (não vai pra docs/ — fica em specs/{nome}/contracts.md) |
+
+> **Regra**: PRD alimenta poucas seções de `docs/` (só atores e alto-nível).
+> O grosso vem do TRD — `docs/` é síntese técnica + negócio cross-feature.
+
+### 3. Diff semântico: calcular ADDED / MODIFIED / REMOVED
+
+Pra cada elemento-destino extraído (passo 2), comparar com snapshot (passo 1):
+
+| Resultado | Condição | Ação |
+|-----------|----------|------|
+| ADDED | Elemento não existe em docs/ | Adicionar na seção apropriada |
+| MODIFIED | Elemento existe mas mudou (nome igual, valor diferente) | Atualizar campos |
+| UNCHANGED | Elemento existe e está igual | Skip (idempotente) |
+| REMOVED | Elemento estava em docs/ mas não aparece em PRD+TRD aprovados | **NÃO remover** — apenas registrar no output como "possivelmente orfão" |
+
+> **Conservadorismo em REMOVED**: PRD/TRD falam só da feature atual. Algo que
+> "não aparece" pode ser de outra feature (que continua válida). NUNCA deletar
+> automaticamente. Reportar e deixar remoção manual.
+
+### 4. Aplicar ADDED e MODIFIED
+
+- Localizar seção apropriada no doc destino
+- Preservar estrutura do template (não quebrar tabelas)
+- ADRs em `decisions.md`: SEMPRE append; ADR com status=aceita é imutável
+- Registrar cada mudança em changelog do doc afetado
+
+### 5. Changelog em cada doc afetado
+
+Adicionar linha no `## Changelog` do doc:
+
+```markdown
+| Data | Feature | Tipo | Descrição |
+|------|---------|------|-----------|
+| {{ISO_DATE}} | $ARGUMENTS | ADDED | Endpoint POST /api/v1/users |
+| {{ISO_DATE}} | $ARGUMENTS | MODIFIED | Matriz de permissões: novo role `manager` |
+```
+
+### 6. Validar consistência cross-doc
+
+- Referências quebradas (endpoint do apiContracts referencia tabela que não existe em domain) → reportar
+- Papel novo em conventions mas não aparece em matriz de autorização → reportar
+- ADR substituída mas ainda referenciada → reportar
+
+Validação reporta, não bloqueia. Usuário decide se resolve manualmente.
+
+### 7. Atualizar status
+
+```yaml
+status: "done"
+ultima_skill: "/sf-merge-docs"
+atualizado_em: "{{ISO_DATETIME}}"
+```
+
+### 8. Saída obrigatória
+
+```
+/sf-merge-docs $ARGUMENTS — completo
+
+docs/ sincronizado com PRD + TRD aprovados:
+- docs/architecture.md    (2 ADDED, 0 MODIFIED)
+- docs/apiContracts.md    (3 ADDED, 1 MODIFIED)
+- docs/conventions.md     (0 ADDED, 1 MODIFIED — novo role)
+- docs/decisions.md       (1 ADDED — ADR-007)
+- docs/domain.md          (0 mudanças)
+
+Possivelmente órfãos (NÃO removidos — revisão manual):
+  - docs/apiContracts.md: endpoint `/legacy/foo` não aparece em PRD+TRD novos
+    (pode ser de outra feature; deletar manualmente se confirmado deprecated)
+
+Validação: passed / N issues
+```
+
+## Erros
+
+| Erro | Ação |
+|------|------|
+| Status != `dev_done` (auto) nem >= `design_done` (manual) | Parar — pedir rodar /sf-dev ou /sf-design primeiro |
+| `docs/` não existe | Parar — explicar que `/sf-design` em first-run cria docs/ (feature só atualiza) |
+| PRD+TRD sem nada novo vs docs/ | Marcar `done` (legítimo — feature sem impacto cross-feature) |
+| Elemento MODIFIED não encontrado no doc | Converter pra ADDED + reportar (doc estava desatualizado) |
+| Referências quebradas detectadas | Reportar, não bloqueia |
+
+## Uso automático (pelo `/sf-dev`)
+
+`/sf-dev` chama `/sf-merge-docs` automaticamente ao final de feature (não first-run):
+
+- Condição: `status=dev_done` E `first_run=false` E (`prd_aprovado=true` OU `trd_aprovado=true`)
+- Rodado inline, sem nova interação
+- Falha em `/sf-merge-docs` não derruba `/sf-dev` — apenas reporta; user pode re-rodar manualmente
+
+## Uso manual
+
+Rodar `/sf-merge-docs $ARGUMENTS` quando:
+- `/sf-dev` falhou e você quer sincronizar docs/ com o que já foi aprovado
+- Fez edição direta em PRD/TRD aprovados e quer propagar pra docs/
+- Quer forçar um re-merge (idempotente — não duplica)