a9a7a328e6
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
146 lines
6.2 KiB
Markdown
146 lines
6.2 KiB
Markdown
# Como migrar do GSD-2
|
|
|
|
**Objetivo:** Atualizar um projeto GSD-2 mais antigo (estrutura de diretório `.gsd/`) para o MSD Core (estrutura `.planning/`), e opcionalmente absorver quaisquer ADRs, PRDs ou especificações existentes no repositório para a nova estrutura de planejamento.
|
|
|
|
**Pré-requisitos:** MSD Core está instalado. O diretório do projeto GSD-2 está disponível em disco.
|
|
|
|
---
|
|
|
|
## Entenda o que é migrado
|
|
|
|
O GSD-2 usava um diretório `.gsd/` como raiz de planejamento. O MSD Core usa `.planning/`. A migração faz a conversão: lê os artefatos de `.gsd/` e os grava na estrutura padrão `.planning/` que todos os comandos MSD Core esperam.
|
|
|
|
| O que existe no GSD-2 | O que `/msd-import --from-gsd2` produz |
|
|
|-----------------------|----------------------------------------|
|
|
| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
|
|
| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
|
|
| `.gsd/STATE.md` | `.planning/STATE.md` |
|
|
| `.gsd/phases/` diretórios | `.planning/phases/` diretórios |
|
|
| Arquivos `PLAN.md` de fase | Arquivos `{NN}-{MM}-PLAN.md` do MSD Core (renomeação aplicada) |
|
|
|
|
A detecção de conflitos é executada antes que qualquer arquivo seja gravado. Se o diretório de destino já tiver um `PROJECT.md` e o conteúdo importado contradizê-lo, a migração para no ponto de bloqueio (BLOCKER) e lista os conflitos para você resolver.
|
|
|
|
---
|
|
|
|
## Execute a migração
|
|
|
|
### Migrar o diretório atual
|
|
|
|
```bash
|
|
/msd-import --from-gsd2
|
|
```
|
|
|
|
O MSD lê `.gsd/` no diretório de trabalho atual e grava os artefatos migrados em `.planning/`.
|
|
|
|
### Migrar a partir de um caminho diferente
|
|
|
|
```bash
|
|
/msd-import --from-gsd2 --path ~/projects/old-project
|
|
```
|
|
|
|
Use `--path` quando o projeto GSD-2 não for seu diretório de trabalho atual.
|
|
|
|
---
|
|
|
|
## Resolva conflitos
|
|
|
|
Se a detecção de conflitos encontrar bloqueadores — por exemplo, uma declaração de stack tecnológico do GSD-2 que contradiz um `.planning/PROJECT.md` existente — ela imprime um relatório de conflitos e para sem gravar nenhum arquivo.
|
|
|
|
Leia o relatório, resolva a contradição (edite o documento de origem ou o artefato de planejamento existente) e execute `/msd-import --from-gsd2` novamente. A migração pode ser executada novamente com segurança até ser concluída sem problemas.
|
|
|
|
---
|
|
|
|
## Importe um arquivo de plano externo
|
|
|
|
Se você tiver um documento de plano avulso (um documento de planejamento de equipe, uma especificação em Markdown, uma lista de tarefas exportada) em vez de um projeto GSD-2 completo, use `--from`:
|
|
|
|
```bash
|
|
/msd-import --from /tmp/team-plan.md
|
|
```
|
|
|
|
O MSD executa a mesma passagem de detecção de conflitos, converte o conteúdo para o formato `PLAN.md` do MSD Core e valida o resultado com o verificador de planos. Após a validação, você verá o nome do arquivo de destino e os próximos passos.
|
|
|
|
---
|
|
|
|
## Absorva documentação existente
|
|
|
|
Se o seu repositório já contiver ADRs (Architecture Decision Records), PRDs ou documentos de especificação, use `/msd-ingest-docs` para sintetizá-los na estrutura `.planning/` após a migração:
|
|
|
|
### Varrer o repositório inteiro (detecta o modo automaticamente)
|
|
|
|
```bash
|
|
/msd-ingest-docs
|
|
```
|
|
|
|
Se `.planning/` já estiver presente (por exemplo, a partir da migração que você acabou de executar), o MSD usa o modo de mesclagem por padrão — ele sintetiza os documentos ingeridos junto com o que já existe, em vez de sobrescrevê-los.
|
|
|
|
### Limitar a um diretório específico
|
|
|
|
```bash
|
|
/msd-ingest-docs docs/
|
|
/msd-ingest-docs docs/adr/
|
|
```
|
|
|
|
### Usar um manifesto de precedência explícito
|
|
|
|
Quando os documentos têm tipos mistos ou você deseja controlar qual documento prevalece em caso de conflitos:
|
|
|
|
```bash
|
|
/msd-ingest-docs --manifest ingest.yaml
|
|
```
|
|
|
|
O manifesto é um arquivo YAML que lista `{path, type, precedence?}` por documento. Consulte a descrição do flag `--manifest` em [Comandos](../COMMANDS.md) para o formato esperado.
|
|
|
|
### Forçar um modo específico
|
|
|
|
```bash
|
|
/msd-ingest-docs --mode merge # Mesclar com o .planning/ existente
|
|
/msd-ingest-docs --mode new # Inicializar do zero (sobrescreve)
|
|
```
|
|
|
|
**Saída:** `/msd-ingest-docs` sempre produz um `INGEST-CONFLICTS.md` com três categorias — resolvidos automaticamente, variantes concorrentes e bloqueadores não resolvidos. Revise este arquivo após cada execução de ingestão. Paradas forçadas ocorrem apenas em contradições LOCKED-vs-LOCKED de ADRs; todo o resto é apresentado para sua revisão, não descartado silenciosamente.
|
|
|
|
---
|
|
|
|
## Verifique o projeto migrado
|
|
|
|
Após a migração e qualquer ingestão de documentos, confirme que o estado do projeto está consistente:
|
|
|
|
```bash
|
|
/msd-health
|
|
/msd-health --repair
|
|
```
|
|
|
|
`/msd-health` verifica a integridade do diretório `.planning/` e relata qualquer desvio. `--repair` corrige automaticamente os problemas recuperáveis.
|
|
|
|
Em seguida, verifique se o MSD Core consegue ler o estado do seu projeto:
|
|
|
|
```bash
|
|
/msd-progress
|
|
```
|
|
|
|
Se o projeto foi migrado corretamente, você verá o status da fase atual e o próximo passo recomendado. A partir daí, o fluxo de trabalho padrão do MSD Core se aplica.
|
|
|
|
---
|
|
|
|
## Condicionais: o que é migrado e o que não é
|
|
|
|
| Situação | O que fazer |
|
|
|----------|-------------|
|
|
| `.gsd/` existe no diretório atual | Execute `/msd-import --from-gsd2` (sem `--path`) |
|
|
| `.gsd/` está em um diretório diferente | Use `--path ~/projects/old-project` |
|
|
| Você tem um documento de plano avulso, não um projeto GSD-2 completo | Use `/msd-import --from /path/to/plan.md` |
|
|
| Você tem ADRs em `docs/adr/` | Execute `/msd-ingest-docs docs/adr/` após a migração |
|
|
| Você tem uma mistura de ADRs, PRDs e especificações | Execute `/msd-ingest-docs` na raiz do repositório; ele classifica automaticamente |
|
|
| A detecção de conflitos relata bloqueadores | Resolva as contradições listadas e execute novamente; nenhum arquivo é gravado até que todos os bloqueadores sejam resolvidos |
|
|
| Você não tem certeza se a migração funcionou | Execute `/msd-health` e `/msd-progress` para confirmar |
|
|
| INGEST-CONFLICTS.md lista bloqueadores não resolvidos | Estes exigem resolução manual antes que os documentos afetados sejam incorporados ao planejamento |
|
|
|
|
---
|
|
|
|
## Relacionados
|
|
|
|
- [Seu primeiro projeto](../tutorials/your-first-project.md)
|
|
- [Comandos](../COMMANDS.md)
|
|
- [Índice de documentação](../README.md)
|