Arquivar alteração com OpenSpec ZDEV-XXR/make-videos-with-Remot…

Arquive uma alteração concluída no fluxo de trabalho experimental.

Seleção de repositório: Se o usuário nomear um repositório (um repositório OpenSpec independente registrado nesta máquina) ou o trabalho estiver em um, execute openspec store list --json para descobrir os IDs de repositório registrados e passe --store <id> nos comandos que leem ou escrevem especificações e alterações (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Uma vez selecionado, trate --store <id> como fixo para o restante do fluxo de trabalho. Todo exemplo não qualificado desses comandos abaixo é uma abreviação: antes de executá-lo, anexe a flag. Por exemplo, execute openspec status --change "<nome>" --json --store "<id>", não a forma não qualificada mostrada abaixo. Outros comandos não aceitam a flag. Dicas impressas pelos comandos já carregam a flag; mantenha-a nos acompanhamentos. Sem um repositório, os comandos atuam na raiz local openspec/ mais próxima.

Verificação do projeto: Estas etapas esperam um projeto que já usa OpenSpec. Antes do primeiro passo que escreve algo (new change, archive, sync specs ou criação de um arquivo de artefato), confirme que o projeto tem uma raiz: execute openspec list --json (com --store <id> quando um repositório estiver selecionado, pois o repositório é então a raiz) e leia root. Um objeto root significa que o projeto está configurado. "root": null significa que não está - não há diretório openspec/ aqui, e uma escrita como openspec new change criaria um como efeito colateral. O comando também sai com código não zero, que é essa resposta, não uma CLI quebrada, então leia o JSON em vez de tentar novamente ou contornar.

Um "root": null não é sobre configuração: quando uma mensagem de erro status começa com Declared in ou Invalid store declaration in e nomeia o openspec/config.yaml (ou config.yml) deste projeto, o projeto usa OpenSpec através de um repositório que declara, o qual esta máquina não pode resolver (o repositório não está registrado ou a linha store: está malformada). Não trate como não inicializado e pule os ramos abaixo: pare antes de escrever e mostre ao usuário a message e fix desse erro.

Caso contrário, sem raiz, o que acontece a seguir depende de como este fluxo de trabalho foi alcançado:

• Auto-selecionado: você escolheu este fluxo de trabalho por conta própria, sem o usuário nomear OpenSpec, nomear esta skill ou executar seu comando de barra. Pare de usar OpenSpec e responda à solicitação normalmente, como faria sem OpenSpec instalado. Não peça para configurar nada e não mencione a configuração do OpenSpec.
• Solicitação explícita do OpenSpec: o usuário nomeou OpenSpec, nomeou esta skill ou executou seu comando de barra. Pare antes de escrever e pergunte como proceder: configurar este projeto (openspec init), direcionar um repositório que já possuem (--store <id>) ou continuar sem OpenSpec para esta solicitação. Aguarde a resposta deles.

Em ambos os ramos, nunca crie a raiz como efeito colateral: não execute openspec init até que o usuário peça, não crie manualmente arquivos openspec/ e não deixe um comando criá-la.

<caminho-da-capacidade> é o diretório da especificação relativo a specs/ (por exemplo, user-auth ou identity/user-auth). Preserve o caminho completo de cada especificação delta ao resolver sua especificação principal.

Entrada: Opcionalmente, especifique um nome de alteração. Se omitido, verifique se pode ser inferido do contexto da conversa. Se vago ou ambíguo, você DEVE solicitar as alterações disponíveis.

Etapas

1. Selecione a alteração

   Se um nome for fornecido, use-o. Caso contrário:

   • Infira do contexto da conversa se o usuário mencionou uma alteração
   • Auto-selecione se apenas uma alteração ativa existir
   • Se ambíguo, execute openspec list --json para obter as alterações disponíveis e peça ao usuário para selecionar uma

   Ao solicitar, mostre apenas as alterações ativas (não já arquivadas). Inclua o esquema usado para cada alteração, se disponível.

   Sempre anuncie: "Usando alteração: " e como substituir (por exemplo, /openspec-archive-change <outro>).

   Carregue as entradas de arquivo atuais antes das verificações de arquivo existentes:

   Após resolver a alteração selecionada e planejar a raiz, execute:

   openspec instructions archive --change "<nome>" --json
   

   Mantenha as mesmas flags de raiz selecionada neste comando. Esta consulta é consultiva e opcional: ela apenas fornece entradas extras de prompt, portanto nunca deve bloquear o arquivamento. Se sair com código não zero ou retornar JSON inválido — por exemplo, em uma CLI mais antiga que não suporta este comando ainda — continue o fluxo de trabalho de arquivamento sem contexto e sem orientação de operação. Não relate um erro e não pare.

   Uma resposta bem-sucedida pode omitir ambos os campos opcionais. Trate context como uma entrada obrigatória no nível do prompt: leia e considere, e aplique fatos, convenções e restrições relevantes do projeto. Trate operationGuidance como conselho aditivo opcional: leia e considere cada entrada, e siga entradas que sejam aplicáveis e compatíveis com o fluxo de trabalho de arquivamento integrado.

   Mantenha ambos os campos separados das etapas integradas, escolhas explícitas do usuário, caminhos resolvidos, verificações da CLI e contratos de comando. Se o contexto conflitar com uma dessas entradas controladoras, relate o conflito e preserve o valor controlador. Se a orientação for inaplicável ou conflitar com uma entrada controladora, não a siga e explique por quê. Não infira caminhos de substituição, prompts pulados ou flags de qualquer um dos campos, e não copie o texto deles literalmente em especificações, artefatos de alteração ou resumos de arquivo, a menos que o usuário peça separadamente. Estes são contratos de comportamento no nível do prompt, não verificações executáveis.

2. Verifique o status de conclusão do artefato

   Execute openspec status --change "<nome>" --json para verificar a conclusão do artefato.

   Analise o JSON para entender:

   • schemaName: O fluxo de trabalho sendo usado
   • planningHome, changeRoot, artifactPaths e actionContext: contexto de caminho e escopo
   • artifacts: Lista de artefatos com seu status (done, skipped ou outro)

   Se algum artefato não estiver done nem skipped (artefatos pulados satisfazem o requisito - a alteração declara skip_specs):

   • Exiba aviso listando artefatos incompletos
   • Peça ao usuário para confirmar se deseja prosseguir
   • Prossiga se o usuário confirmar

3. Verifique o status de conclusão da tarefa

   Execute openspec list --json com as mesmas flags de raiz selecionada e encontre a entrada em changes cujo name corresponda exatamente à alteração selecionada. Exija exatamente uma correspondência e inteiros não negativos totalTasks e completedTasks, com completedTasks <= totalTasks. A CLI resolve os arquivos de tarefa rastreados do esquema, incluindo nomes de artefato personalizados, caminhos de saída e globs. Tarefas incompletas = totalTasks - completedTasks.

   Não infira conclusão de tarefa a partir do status do artefato ou da ausência de um tasks.md de nível superior. Se a consulta falhar, retornar JSON inválido, omitir ou duplicar a alteração selecionada, ou retornar contagens inválidas, relate o problema e pare antes de sincronizar ou arquivar. A CLI conta apenas marcadores de caixa de seleção x/X como concluídos; outros marcadores, incluindo os não familiares, permanecem incompletos.

   Se tarefas incompletas forem encontradas:

   • Exiba aviso mostrando a contagem de tarefas incompletas
   • Peça ao usuário para confirmar se deseja prosseguir
   • Prossiga se o usuário confirmar

   Se totalTasks for zero: Prossiga sem aviso relacionado a tarefas.

4. Avalie o estado de sincronização das especificações delta

   Use artifactPaths.specs.existingOutputPaths do JSON de status como a única fonte de especificações delta. Se a entrada specs estiver ausente ou existingOutputPaths estiver vazio, prossiga sem prompt de sincronização e não infira especificações delta de outros artefatos.

   Se existirem especificações delta:

   • Compare cada especificação delta com sua especificação principal correspondente em <planningHome.root>/openspec/specs/<caminho-da-capacidade>/spec.md (use o planningHome.root ciente de repositório da etapa 2, não um caminho de repositório codificado)
   • Uma especificação principal ausente não é automaticamente "já sincronizada". Para uma nova capacidade, a especificação principal é uma saída da sincronização, não uma entrada:
     • Se o delta tiver requisitos MODIFICADOS ou RENOMEADOS, relate que apenas requisitos ADICIONADOS podem criar uma nova especificação principal e marque essa capacidade como bloqueada para sincronização. Nunca invente um requisito que não tenha versão atual.
     • Caso contrário, se o delta tiver apenas requisitos REMOVIDOS e o .openspec.yaml da alteração declarar retire_capabilities: true, a capacidade já está retirada: conte-a como já sincronizada, avise que não há nada a remover e não recrie a especificação principal. Aplique esta regra tanto agora quanto ao verificar uma sincronização concluída.
     • Caso contrário, se o delta não tiver requisitos ADICIONADOS, relate que nenhuma sincronização é possível e marque essa capacidade como bloqueada para sincronização. Para um delta apenas com REMOVIDOS, avise que não há especificação principal da qual remover e deixe a árvore de especificações principal inalterada. openspec archive recusa o caso apenas com REMOVIDOS não marcado com Spec must have at least one requirement.
     • Caso contrário, conte a capacidade como necessitando sincronização e nomeie-a no resumo (<caminho-da-capacidade>: nova especificação principal será criada). Se o delta também tiver requisitos REMOVIDOS, avise que eles serão ignorados porque não há especificação principal da qual remover. A sincronização cria a especificação principal apenas a partir dos requisitos ADICIONADOS do delta, exatamente como openspec archive faz.
   • Determine quais alterações seriam aplicadas (adições, modificações, remoções, renomes)
   • Continue avaliando as capacidades restantes mesmo quando uma estiver bloqueada para sincronização. Mostre um resumo combinado antes de solicitar.

   Opções de prompt:

   • Se alguma capacidade estiver bloqueada para sincronização: explique o porquê e ofereça apenas "Arquivar sem sincronizar", "Cancelar"
   • Caso contrário, se alterações forem necessárias: "Sincronizar agora (recomendado)", "Arquivar sem sincronizar"
   • Caso contrário, se já sincronizado: "Arquivar agora", "Sincronizar mesmo assim", "Cancelar"

   Roteie com base na resposta:

   • "Cancelar" — pare, não arquive
   • "Arquivar sem sincronizar" ou "Arquivar agora" — prossiga para arquivar
   • "Sincronizar agora" ou "Sincronizar mesmo assim" — sincronize, depois verifique (abaixo). Não inicie nenhuma sincronização enquanto uma capacidade estiver bloqueada para sincronização; explique o bloqueador e repita as escolhas disponíveis.
   • Qualquer outra coisa — pergunte novamente em vez de arquivar

   Antes de uma sincronização selecionada escrever qualquer especificação principal, execute openspec instructions specs --change "<nome>" --json uma vez com as mesmas flags de raiz selecionada. Exija status de saída zero e JSON de instruções de artefato válido. Se a consulta falhar ou retornar JSON inválido, relate o erro e pare antes de escrever qualquer especificação principal ou mover a alteração. Uma resposta válida com rules omitidos é o caso sem regras. Aplique rules retornados apenas ao conteúdo e forma das especificações principais produzidas por esta mesclagem; não os use como orientação de arquivo, altere o comportamento da CLI ou copie o texto da regra em qualquer arquivo de saída.

   Em seguida, execute o fluxo de trabalho openspec-sync-specs inline (mesclagem inteligente orientada por agente) para a alteração '', passando a análise da especificação delta e o instantâneo das regras de especificações buscado acima, e aguarde sua conclusão. A sincronização inline deve reutilizar esse instantâneo sem buscar as instruções specs novamente. Não delegue a uma tarefa em segundo plano — a etapa 5 moveria changeRoot de uma sincronização que ainda está lendo, deixando a alteração arquivada e as especificações principais nunca atualizadas. Se seu agente só puder executá-la por delegação, delegue de forma síncrona e aguarde o resultado.

   Se a sincronização relatar qualquer condição de parada ou bloqueio, trate a sincronização como falha. Pare o arquivamento imediatamente. Não execute a comparação de conteúdo pós-sincronização e não mova seu changeRoot. Nada foi movido, então o usuário pode corrigir a condição de bloqueio ou reexecutar a sincronização.

   Após a sincronização escrever cada especificação principal, verifique sua estrutura em relação ao contrato de sincronização canônico:

   • Uma nova especificação principal começa com um título # <capacidade> Specification. Uma especificação principal existente mantém seu título exatamente como está.
   • Preserve seções ## Purpose existentes completamente intactas para especificações principais estabelecidas.
   • Para uma nova especificação principal, copie o ## Purpose do delta literalmente. Avise apenas se o texto do propósito for mais curto do que a validação padrão espera. Não regenere ou reescreva o propósito existente do autor. Se nenhum ## Purpose utilizável for fornecido, use o comportamento e aviso existentes de Purpose TBD.
   • Verifique se nenhum cabeçalho de seção de estilo delta (## ADDED Requirements, ## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements) permanece na especificação principal, aderindo estritamente às regras de formatação do fluxo de trabalho de sincronização.
   • Blocos de requisitos que a sincronização escreveu ou alterou usam cabeçalhos ### Requirement: e seus cenários usam cabeçalhos #### Scenario:, sob a seção ## Requirements da especificação. Deixe o conteúdo que o delta não menciona exatamente como está.

   Em seguida, reexecute a comparação do início desta etapa, incluindo o caso de especificação ausente explicitamente retirada, contra cada capacidade que tenha uma especificação delta em artifactPaths.specs.existingOutputPaths — não apenas aquelas que a sincronização relata ter tocado. Uma sincronização bem-sucedida não deixa nada a ser aplicado, portanto cada capacidade deve agora ser lida como já sincronizada:

   • Requisitos ADICIONADOS presentes
   • Requisitos MODIFICADOS carregando as alterações de cenário e descrição nomeadas no delta, com seus outros cenários intactos
   • Requisitos REMOVIDOS ausentes — e onde esta sincronização retirou uma capacidade (removeu seu último requisito, deixando ## Requirements vazio), sua especificação principal deletada em vez de deixada vazia.
   • Requisitos RENOMEADOS presentes sob o novo nome e ausentes sob o antigo

   Se a sincronização falhou, ou qualquer capacidade não corresponder, relate o que difere e pare — não arquive. Nada foi movido e changeRoot está intacto, então o usuário pode corrigir a incompatibilidade ou reexecutar a sincronização e iniciar o arquivamento novamente.

5. Execute o arquivamento

   Crie um diretório archive sob planningHome.changesDir se não existir:

   mkdir -p "<planningHome.changesDir>/archive"
   

   Gere o nome de destino: use o nome da alteração como está quando já começar com um prefixo YYYY-MM-DD-; caso contrário, prefixe a data atual no formato YYYY-MM-DD-.

   Execute:

   openspec archive --change "<nome>" --json
   

   forneça o nome gerado se o comando aceitar um caminho de destino. Se a alteração já foi arquivada e o comando falha, capture o erro, avise o usuário e pare.

   Se o comando for bem-sucedido, exiba um resumo.

6. Resuma

   Anuncie o arquivamento concluído: "Alteração arquivada com sucesso."

   • Se a sincronização de especificações foi executada, observe que as especificações principais foram atualizadas.
   • Se tarefas ou artefatos estavam incompletos, registre que eles permanecem como estão.
   • Se alguma capacidade foi retirada, liste-a e observe que sua especificação foi removida.