Sincronização House
Atualiza os arquivos house de um repositório com o plugin instalado, sem nunca descartar uma edição local silenciosamente. Invoque este skill apenas através de /house-rules:sync. Não é um skill de consulta e escreve arquivos, portanto nunca é acionado por uma pergunta simples sobre convenções (use /house-rules:conventions para isso).
O CLI que este skill controla:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house <init|render|check> [--repo <caminho>] [--apply] [--force-managed <caminho>]
--repo padrão é o diretório atual. Nada abaixo inventa um subcomando fora de init, render, check.
Caminho padrão: planejar, depois aplicar
A sincronização tem exatamente um caminho padrão. Execute-o nesta ordem toda vez.
1. Confirme que o repositório adotou house
Leia house.json na raiz do repositório. A ausência de house.json significa que este repositório nunca foi inicializado: pare e informe ao usuário para executar /house-rules:bootstrap primeiro. Não trate um manifesto ausente como "nada para sincronizar".
2. Planejamento (execução seca)
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <caminho>
Sem --apply, isso apenas planeja. Ele lê .house/lock.json (cada entrada: path, module, source, bodySha256) e compara o hash atual do corpo de cada arquivo gerenciado no disco com o lock, e então com o que o novo corpo renderizado seria. Classifique cada arquivo gerenciado em exatamente um balde:
- Limpo. O hash no disco corresponde ao lock. Plano: sobrescrever com o corpo recém-renderizado.
- Ausente. Arquivo ausente no disco. Plano: restaurá-lo.
- Modificado localmente. O hash no disco não corresponde nem ao lock nem a uma renderização sem alterações. Plano: recusar. Veja as três saídas abaixo.
Imprima o plano antes de fazer qualquer outra coisa. Não aplique nada neste passo, mesmo para arquivos limpos ou ausentes.
3. Modificado localmente: três saídas, nunca uma escolha silenciosa
Um arquivo gerenciado modificado localmente não é mesclado, sobrescrito ou deixado quieto por si só. Imprima o diff entre o arquivo no disco e o que house renderizaria, depois imprima exatamente estas três saídas, nesta ordem, e pare para o arquivo (ele permanece intacto sob --apply também, é simplesmente excluído da escrita):
- Upstream-first. Abra um PR contra o próprio repositório do pacote house (
dubbl-a/house-rules) carregando a alteração pretendida, para que a edição se torne a nova regra house para todos, em vez de um fork privado. Esta é a saída preferida. - Registre um desvio e desgerencie. Adicione uma entrada ao array
deviationsdohouse.jsoncom umwhy, remova o arquivo do conjunto gerenciado e espelhe-o na seção## Deviations from housedo CLAUDE.md do repositório. Use isso quando a edição for genuinamente específica do repositório e nunca for para o upstream. - Force a sobrescrita. Execute:
Use isso apenas quando a edição local for confirmadamente descartável, nunca como padrão porque é o mais rápido. Peça confirmação ao usuário antes de executar; nunca escolha por conta própria sem solicitação.node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <caminho> --force-managed <caminho>
Não ofereça uma quarta opção e não transforme isso em um menu interativo que fica em loop esperando uma escolha. Apresente as três saídas como o resultado da execução, então deixe o usuário (ou uma invocação posterior deste skill) agir sobre uma.
4. Aplicar
Depois que os arquivos limpos e ausentes forem contabilizados e cada arquivo modificado localmente tiver sido direcionado para uma das três saídas (ou deliberadamente deixado recusado), aplique:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <caminho> --apply
Isso escreve arquivos limpos e ausentes. Nunca escreve um arquivo modificado localmente que ainda foi recusado; --force-managed é o único caminho que faz isso, e apenas para o caminho nomeado.
Se o render imprimiu uma linha warning: ... is git-ignored, pare e corrija a regra de ignore antes de continuar: um destino que o git não vê nunca chega ao verificador ou CI. Ignore apenas .claude/settings.local.json, nunca .claude/ ou .house/.
Se o render ou o verificador imprimiu warning: module is not in house.json, but <dir>/ exists here, um módulo foi enviado após a escrita do house.json deste repositório, e suas regras não estão vendidas até que o repositório adicione "<nome>": {"enabled": true} sob modules. Não adicione a chave você mesmo: copie a linha de aviso literalmente no corpo do PR de sincronização, sob uma linha dizendo que um novo módulo se aplica a este repositório e precisa da escolha do adotante.
4b. Faça stage do que o render escreveu, por caminho
git add house.json .house/ .claude/rules/house/
Adicione scripts/house/ a esse comando apenas quando o plano de render listar um arquivo lá; o git recusa o comando inteiro quando qualquer pathspec não corresponde a nada. Por caminho explícito, nunca git add -A: o verificador e o CI leem git ls-files, então um arquivo renderizado que não foi staged é um que ninguém verifica, e um add geral varreria qualquer outra coisa que esteja na árvore.
A lista Scaffolded do render (.github/PULL_REQUEST_TEMPLATE.md, .github/workflows/pr-checks.yml, o esqueleto CLAUDE.md) não é um arquivo gerenciado, então o aviso [untracked] não pode vê-lo: revise esses arquivos, depois faça stage deles também por caminho.
Um scaffold é oferecido uma vez por repositório, não uma vez por render. A lista scaffolds do lock registra quais templates este repositório já recebeu; um template registrado lá nunca é escrito novamente, mesmo que seu arquivo ainda esteja no disco. Portanto, um CLAUDE.md.house-skeleton que foi mesclado em CLAUDE.md e deletado permanece deletado, e nenhuma nova sincronização precisa fazer rm dele. Se um repositório quiser um de volta, render --apply --scaffold escreve qualquer scaffold ausente e ainda nunca sobrescreve um arquivo que está lá. Espere que a chave scaffolds apareça no diff do lock na primeira sincronização na versão 0.2.3 ou posterior; é um registro, não um hash, e nada recusa com base nele.
4c. Gitignore de ferramenta scratch
Garanta que o .gitignore do repositório contenha .claude/worktrees/ e .superpowers/, acrescentando a linha que estiver faltando. O scratch de ferramenta que aparece em git status está a um git add -A de ser commitado.
5. Confirme o pin
Confirme que house.json agora carrega a versão do plugin carregado; o render o escreveu, nunca edite manualmente. render --apply define o campo version para a versão do plugin em:
${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json
Nunca leia installed_plugins.json para verificar isso. Ele registra o estado de instalação entre repositórios e pode atrasar ou diferir do que está carregado no momento; plugin.json sob CLAUDE_PLUGIN_ROOT é a versão que realmente está executando esta sincronização.
6. Verifique com o verificador vendado
Execute o verificador como CI e prebuild realmente o executarão, não a cópia do próprio plugin:
node .house/check.mjs
node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <caminho> executa a lógica idêntica contra a carga útil do próprio plugin e é útil antes de .house/check.mjs ter sido vendado no repositório (uma primeira sincronização). Uma vez que a cópia vendada existe, executá-la diretamente prova que o arquivo que é enviado é o que passa, não uma cópia que apenas parece igual.
Um aviso [untracked] aqui significa que o passo 4b foi pulado para aquele arquivo; faça stage dele e execute novamente. Um achado [gitignored] significa que a regra de ignore do passo 4 ainda engole um arquivo gerenciado.
7. Imprima a saída do doutor
Após a execução do check, execute o doutor e relate suas linhas:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house doctor --repo <caminho>
O que cada linha impressa significa (rótulos como o doctor os imprime):
effective branch guard: plugin | repo | NONE.NONE: nenhumhouse.jsone nenhum hook local do repositório. Nada está protegendo commits diretos para um branch protegido agora.repo: um arquivo.claude/hooks/no-direct-master.shlocal do repositório existe, ou.claude/settings.jsoncarrega um blocohooks. O hook do repositório vence durante a migração; o hook do plugin recua e sai com código 0.plugin:house.jsonexiste e nenhum sinal de hook local do repositório está presente. O hook do plugin é o que realmente está aplicandobranchPolicyeprotectedBranches. Ele imprime comoplugin (recorded <data>)quandohouse.jsoncarrega um registroguardeplugin (unrecorded)quando não, o que é apenas sobre se o aviso do verificadorguardestá limpo: o hook aplica o mesmo de qualquer forma.
git-hook floor: .... Se a árvore.githooks/vendada está realmente conectada ao git NESTE clone.core.hooksPathvive em.git/config, então é estado da máquina que nenhum clone, nenhum render e nenhum PR carrega; o verificador nunca o lê (ADR 0008 mantém o verificador apenas no repositório) e o doctor é onde ele é relatado.armed (core.hooksPath=<caminho>, <escopo>): git executa o floor aqui. Nada a fazer.NOT armed -- core.hooksPath is unset in this clone: o floor está renderizado e inerte.house render --applyo arma, e também o início de uma sessão no repositório com o plugin instalado.NOT armed -- core.hooksPath is <outro>: outra ferramenta (husky, lefthook, uma convenção de monorepo) possui o único hooksPath que este repositório tem. House nunca o sobrescreve. Encadeie o floor a partir dos hooks lá, ou desdefina-o e execute render novamente.not rendered here (missing: <caminhos>): pelo menos um dos sete arquivos do floor está ausente, e a linha nomeia quais. Todos os sete ausentes é simplesmente um repositório que ainda não renderizou o floor. Um ausente é pior do que parece: todo guard faz source de.githooks/house-lib.she sai com código não zero quando esse source falha, então um floor faltando apenas a biblioteca faz todo commit falhar fechado em vez de falhar aberto. De qualquer forma, render.not applicable: nenhumhouse.jsonnesta raiz, oubranchPolicynão épr.- As linhas subsequentes indentadas relatam o que tornaria o floor silencioso em vez de protetivo.
foreign hooks in this clone's .git/hooks: armar é recusado, porquecore.hooksPathsubstitui.git/hookscompletamente e os desabilitaria silenciosamente.not executable: git ignora silenciosamente um hook sem a permissão, então um modo perdido é uma falha aberta; render o restaura (adicionando a permissão apenas para as classes que já podem ler o arquivo, então um arquivo deliberadamente 0600 volta como 0700 e nunca é ampliado).reference-transaction: supported by git <versão> (>= 2.28)ouinert on git <versão> (needs 2.28): no 2.28 e mais novos, o floor tem um membro que nenhuma bandeira desliga, e a linha inerte é uma lacuna real em vez de cosmética. Abaixo de 2.28--no-verifypulapre-commitepre-pushjuntos e nada mais está lá para pegá-lo, então nesse git a bandeira é recusada apenas pelo hook PreToolUse de sessão, que não está lá quando nenhuma sessão está no loop. Trate a linha como um incentivo para atualizar o git, não como uma nota.
jq on PATH: yes | no. O hook ainda nega sem ele (deny JSON escrito à mão), mas relate a lacuna para que seja corrigida.pin vX matches plugin vY|pin vX differs from installed plugin vY.versiondohouse.jsoncontra oplugin.jsondo próprio plugin, a mesma comparação do passo 5.differssignifica que o bump do pin ainda não foi implantado ou foi pulado.npm wiring (.house/check.mjs referenced by): <scripts> | none found. Espere um scriptcheck:docs(ou equivalente leve) invocando.house/check.mjs --only=drift,todoe um scriptcheck:houseinvocando.house/check.mjscompleto. Se algum estiver faltando, imprima o snippet copiável em vez de editarpackage.jsondiretamente:"check:docs": "node .house/check.mjs --only=drift,todo" "check:house": "node .house/check.mjs"rule-load positive control: .... Se um hookInstructionsLoadedestá conectado, e o que seu próprio log realmente testemunhou; sem um, uma regra cujo glob nunca corresponde parece exatamente como uma regra que não faz nada.repo (.claude/settings.json): o repositório declara seu próprio hook.plugin hook; log <caminho>: last load <ts>, <n> of <m> vendored rules seen: o hook do próprio plugin está conectado e registrou pelo menos um load, com uma contagem real de quantos arquivos de regra vendados ele realmente viu carregar. Quando<n>é menor que<m>, a linha continua; not seen in this log: <nomes>, nomeando cada regra vendada para a qual o log não carrega, porque a contagem sozinha diz que algo está errado e nunca qual arquivo abrir. Leia essa lista como uma pista e não um veredito: o log se auto-apara, então uma regra pode aparecer lá após carregar apenas há muito tempo, e o próximo passo honesto é abrir um arquivo que a regrapaths:afirma e executar doctor novamente. Um nome que sobrevive a isso é uma regra cujo escopo não está alcançando os arquivos para os quais foi escrito.plugin hook declared; no log yet for this checkout: o hook do plugin está conectado mas não registrou nada aqui ainda -- inicie uma sessão neste repositório e execute doctor novamente.none wired: nada declara o hook.git-ignored house destinations: none | <caminhos>. Qualquer coisa diferente denoneé um destino que o verificador não pode ver; corrija a regra de ignore como no passo 4.
8. Roteie o que o repositório não pode corrigir upstream, um item por issue
Uma passagem de sincronização ou conformidade frequentemente revela achados e avisos que apenas o pacote pode resolver: uma lacuna no verificador, um nome de âncora de regra que nomeia um arquivo que não existe aqui, um slot de configuração que o repositório precisa e o esquema não possui. Para cada item, corrija-o upstream na mesma sessão (branch e PR contra o repositório do pacote, a mesma saída upstream-first do passo 3) ou abra UMA issue por item acionável no repositório do pacote, pequena o suficiente para ser fechada com uma única alteração.
Nunca coloque em lote em uma issue digest de múltiplos itens: um digest não pode ser fechado até que seu item mais lento chegue, seus itens não podem ser priorizados independentemente e digests meio resolvidos se acumulam. O que fica neste repositório é apenas o que este repositório pode corrigir.
Saídas de escape
Estas são exceções levantadas inline no caminho padrão acima, não um menu separado para escolher de antemão:
- Sem
house.json: pare no passo 1, aponte para/house-rules:bootstrap. - Arquivo modificado localmente: as três saídas no passo 3.
- Edição local confirmadamente descartável:
--force-managed <caminho>, apenas depois de perguntar. - Primeira sincronização em um repositório,
.house/check.mjsainda não vendado: usehouse check --repo <caminho>no passo 6 em vez do caminho vendado, e note que esta é uma substituição única, não o estado estável.
Não
- Não mescle uma modificação local sem decisão explícita.
- Não ofereça um menu interativo no lugar das três saídas.
- Não use
git add -A.