Sincronización de reglas de la casa
Mantén actualizados los archivos de reglas de la casa incluidos en un repositorio con el plugin instalado, sin descartar nunca una edición local en silencio. Invoca esta habilidad solo a través de /house-rules:sync. No es una habilidad de consulta y escribe archivos, por lo que nunca se activa con una pregunta simple sobre convenciones (usa /house-rules:conventions para eso).
La CLI que impulsa esta habilidad:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house <init|render|check> [--repo <ruta>] [--apply] [--force-managed <ruta>]
--repo predetermina al directorio actual. Nada de lo siguiente inventa un subcomando fuera de init, render, check.
Ruta predeterminada: planificar, luego aplicar
La sincronización tiene exactamente una ruta predeterminada. Ejecútala en este orden cada vez.
1. Confirmar que el repositorio ha adoptado las reglas de la casa
Lee house.json en la raíz del repositorio. Si falta house.json, significa que este repositorio nunca se ha iniciado: detente e indica al usuario que ejecute /house-rules:bootstrap primero. No trates un manifiesto faltante como "nada que sincronizar".
2. Planificar (ejecución de prueba)
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <ruta>
Sin --apply, esto solo planifica. Lee .house/lock.json (cada entrada: ruta, módulo, origen, bodySha256) y compara el hash del cuerpo actual de cada archivo administrado en disco con el bloqueo, y luego con lo que sería el nuevo cuerpo renderizado. Clasifica cada archivo administrado en exactamente un grupo:
- Limpio. El hash en disco coincide con el bloqueo. Plan: sobrescribir con el cuerpo recién renderizado.
- Faltante. El archivo no está en disco. Plan: restaurarlo.
- Modificado localmente. El hash en disco no coincide ni con el bloqueo ni con una renderización sin cambios. Plan: rechazar. Consulta las tres salidas a continuación.
Imprime el plan antes de hacer cualquier otra cosa. No apliques nada en este paso, incluso para archivos limpios o faltantes.
3. Modificado localmente: tres salidas, nunca una elección silenciosa
Un archivo administrado modificado localmente no se fusiona, no se sobrescribe y no se deja en paz en silencio. Imprime la diferencia entre el archivo en disco y lo que las reglas de la casa renderizarían, luego imprime exactamente estas tres salidas, en este orden, y detente para el archivo (permanece sin tocar bajo --apply también, simplemente se excluye de la escritura):
- Ascendente primero. Abre un PR contra el repositorio del paquete de reglas de la casa (
dubbl-a/house-rules) que contenga el cambio previsto, para que la edición se convierta en la nueva regla de la casa para todos en lugar de una bifurcación privada. Esta es la salida preferida. - Registrar una desviación y desadministrar. Agrega una entrada al array
deviationsdehouse.jsoncon unwhy, elimina el archivo del conjunto administrado y reflejalo en la sección## Desviaciones de las reglas de la casadel CLAUDE.md del repositorio. Usa esto cuando la edición sea genuinamente específica del repositorio y nunca se incluya en el upstream. - Forzar la sobrescritura. Ejecuta:
Usa esto solo cuando la edición local se confirme como desechable, nunca como predeterminado porque es lo más rápido. Pide al usuario que confirme antes de ejecutarlo; nunca lo elijas sin que se lo pidan.node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <ruta> --force-managed <ruta>
No ofrezcas una cuarta opción y no conviertas esto en un menú interactivo que se repite esperando una elección. Indica las tres salidas como el resultado de la ejecución, luego deja que el usuario (o una invocación posterior de esta habilidad) actúe sobre una.
4. Aplicar
Una vez que los archivos limpios y faltantes se hayan contabilizado y cada archivo modificado localmente se haya dirigido a una de las tres salidas (o se haya dejado deliberadamente rechazado), aplica:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <ruta> --apply
Esto escribe archivos limpios y faltantes. Nunca escribe un archivo modificado localmente aún rechazado; --force-managed es la única ruta que lo hace, y solo para la ruta nombrada.
Si la renderización imprime una línea warning: ... is git-ignored, detente y corrige la regla de ignorado antes de continuar: un destino que git no puede ver nunca llega al verificador o a CI. Ignora solo .claude/settings.local.json, nunca .claude/ o .house/.
Si la renderización o el verificador imprimen warning: module is not in house.json, but <dir>/ exists here, significa que un módulo se envió después de que se escribió el house.json de este repositorio, y sus reglas no están incluidas hasta que el repositorio agregue "<nombre>": {"enabled": true} bajo modules. No agregues la clave tú mismo: copia la línea de advertencia textualmente en el cuerpo del PR de sincronización, debajo de una línea que indique que un nuevo módulo se aplica a este repositorio y necesita la elección del adoptante.
4b. Agregar al área de preparación lo que la renderización escribió, por ruta
git add house.json .house/ .claude/rules/house/
Agrega scripts/house/ a ese comando solo cuando el plan de renderización haya listado un archivo allí; git rechaza todo el comando cuando algún pathspec no coincide con nada. Por ruta explícita, nunca git add -A: el verificador y CI leen git ls-files, por lo que un archivo renderizado que no está en el área de preparación es uno que nadie verifica, y una adición general barrería cualquier otra cosa que esté en el árbol.
La lista Scaffolded de la renderización (.github/PULL_REQUEST_TEMPLATE.md, .github/workflows/pr-checks.yml, el esqueleto de CLAUDE.md) no es un archivo administrado, por lo que la advertencia [untracked] no puede verlo: revisa esos archivos y luego agrégalos al área de preparación también por ruta.
Un scaffold se ofrece una vez por repositorio, no una vez por renderización. La lista scaffolds del bloqueo registra qué plantillas ya se le han dado a este repositorio; una plantilla registrada allí nunca se vuelve a escribir, independientemente de si su archivo todavía está en disco. Por lo tanto, un CLAUDE.md.house-skeleton que se fusionó en CLAUDE.md y se eliminó permanece eliminado, y ninguna resincronización tiene que rm ello. Si un repositorio quiere uno de vuelta, render --apply --scaffold escribe cualquier scaffold faltante y aún así nunca sobrescribe un archivo que ya está ahí. Espera que la clave scaffolds aparezca en la diferencia del bloqueo en la primera sincronización en 0.2.3 o posterior; es un registro, no un hash, y nada lo rechaza.
4c. Ignorar el espacio de trabajo de la herramienta
Asegúrate de que el .gitignore del repositorio contenga .claude/worktrees/ y .superpowers/, agregando la línea que falte. El espacio de trabajo de la herramienta que aparece en git status está a un git add -A de ser confirmado.
5. Confirmar la versión fijada
Confirma que house.json ahora contiene la versión del plugin cargado; la renderización lo escribió, nunca lo edites a mano. render --apply establece el campo version a la versión del plugin en:
${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json
Nunca leas installed_plugins.json para verificar esto. Registra el estado de instalación entre repositorios y puede retrasarse o diferir de lo que está cargado actualmente; plugin.json bajo CLAUDE_PLUGIN_ROOT es la versión que realmente está ejecutando esta sincronización.
6. Verificar con el verificador incluido
Ejecuta el verificador de la manera en que CI y prebuild realmente lo ejecutarán, no la copia del propio plugin:
node .house/check.mjs
node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <ruta> ejecuta la misma lógica contra la carga útil del propio plugin y es útil antes de que .house/check.mjs se haya incluido en el repositorio (una sincronización por primera vez). Una vez que la copia incluida existe, ejecutarla directamente demuestra que el archivo que se envía es el archivo que pasa, no una copia que solo se ve igual.
Una advertencia [untracked] aquí significa que el paso 4b se omitió para ese archivo; agrégalo al área de preparación y vuelve a ejecutar. Un hallazgo [gitignored] significa que la regla de ignorado del paso 4 aún oculta un archivo administrado.
7. Imprimir la salida del doctor
Después de que el verificador se ejecute, ejecuta el doctor e informa sus líneas:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house doctor --repo <ruta>
Qué significa cada línea impresa (etiquetas como las imprime el doctor):
effective branch guard: plugin | repo | NONE.NONE: no hayhouse.jsonni hook local del repositorio. Nada está protegiendo las confirmaciones directas a una rama protegida en este momento.repo: existe un archivo.claude/hooks/no-direct-master.shlocal del repositorio, o.claude/settings.jsonlleva un bloquehooks. El hook del repositorio gana durante la migración; el hook del plugin se aplaza y sale con 0.plugin:house.jsonexiste y no está presente ninguna señal de hook local del repositorio. El hook del plugin es el que realmente aplicabranchPolicyyprotectedBranches. Se imprime comoplugin (recorded <fecha>)cuandohouse.jsonlleva un registroguardyplugin (unrecorded)cuando no, lo que solo indica si la advertencia deguarddel verificador está despejada: el hook aplica lo mismo de cualquier manera.
git-hook floor: .... Si el árbol incluido.githooks/está realmente conectado a git en ESTE clon.core.hooksPathreside en.git/config, por lo que es estado de la máquina que ningún clon, ninguna renderización y ningún PR lleva; el verificador nunca lo lee (ADR 0008 mantiene el verificador solo para el repositorio) y el doctor es donde se informa.armed (core.hooksPath=<ruta>, <alcance>): git ejecuta el piso aquí. No hay nada que hacer.NOT armed -- core.hooksPath is unset in this clone: el piso está renderizado e inerte.house render --applylo arma, y también lo hace iniciar una sesión en el repositorio con el plugin instalado.NOT armed -- core.hooksPath is <other>: otra herramienta (husky, lefthook, una convención de monorepo) posee el único hooksPath que tiene este repositorio. Las reglas de la casa nunca lo sobrescriben. Encadena el piso desde los hooks allí, o desactívalo y vuelve a ejecutar la renderización.not rendered here (missing: <rutas>): al menos uno de los siete archivos del piso está ausente, y la línea nombra cuáles. Los siete faltantes simplemente son un repositorio que aún no ha renderizado el piso. Uno faltante es peor de lo que parece: cada guardia utiliza.githooks/house-lib.shy sale con código distinto de cero cuando esa fuente falla, por lo que un piso al que solo le falta la biblioteca falla cada cierre de confirmación en lugar de fallar abierto. De cualquier manera, renderiza.not applicable: no hayhouse.jsonen esta raíz, obranchPolicyno espr.- Las líneas posteriores con sangría informan qué haría que el piso esté silencioso en lugar de protector.
foreign hooks in this clone's .git/hooks: el armado es rechazado, porquecore.hooksPathreemplaza.git/hookspor completo y los deshabilitaría silenciosamente.not executable: git ignora silenciosamente un hook sin el bit, por lo que un modo perdido es un fallo abierto; la renderización lo restaura (agregando el bit solo para las clases que ya pueden leer el archivo, por lo que un hook deliberadamente 0600 vuelve 0700 y nunca se amplía).reference-transaction: supported by git <versión> (>= 2.28)oinert on git <versión> (needs 2.28): en 2.28 y posteriores, el piso tiene un miembro que ninguna bandera desactiva, y la línea inerte es una brecha real en lugar de una cosmética. Por debajo de 2.28,--no-verifyomitepre-commitypre-pushjuntos y no hay nada más para detectarlo, por lo que en ese git la bandera solo es rechazada por el hook de PreToolUse de sesión, que no está allí cuando no hay sesión en el bucle. Trata la línea como un aviso para actualizar git, no como una nota.
jq on PATH: yes | no. El hook aún lo niega sin él (JSON de denegación escrito a mano), pero informa la brecha para que se solucione.pin vX matches plugin vY|pin vX differs from installed plugin vY.house.json'sversioncontra el propioplugin.jsondel plugin, la misma comparación que el paso 5.differssignifica que el aumento de la versión fijada aún no ha llegado o se omitió.npm wiring (.house/check.mjs referenced by): <scripts> | none found. Se espera un scriptcheck:docs(o equivalente ligero) que invoque.house/check.mjs --only=drift,todoy un scriptcheck:houseque invoque el completo.house/check.mjs. Si falta alguno, imprime el fragmento copiable en lugar de editarpackage.jsondirectamente:"check:docs": "node .house/check.mjs --only=drift,todo" "check:house": "node .house/check.mjs"rule-load positive control: .... Si un hookInstructionsLoadedestá conectado y qué ha presenciado realmente su propio registro; sin uno, una regla cuyo glob nunca coincide se ve exactamente como una regla que no hace nada.repo (.claude/settings.json): el repositorio declara su propio hook.plugin hook; log <ruta>: last load <ts>, <n> of <m> vendored rules seen: el hook del propio plugin está conectado y ha registrado al menos una carga, con un recuento real de cuántos archivos de reglas incluidos ha visto realmente cargar. Cuando<n>es inferior a<m>, la línea continúa; not seen in this log: <nombres>, nombrando cada regla incluida para la que el registro no tiene carga, porque el recuento solo dice que algo está mal y nunca qué archivo abrir. Lee esa lista como una pista y no como un veredicto: el registro se auto-recorta, por lo que una regla puede aparecer allí después de cargar solo hace mucho tiempo, y el siguiente paso honesto es abrir un archivo que reclaman laspaths:de la regla y volver a ejecutar el doctor. Un nombre que sobrevive a eso es una regla cuyo alcance no está llegando a los archivos para los que fue escrita.plugin hook declared; no log yet for this checkout: el hook del plugin está conectado pero aún no ha registrado nada aquí: inicia una sesión en este repositorio y vuelve a ejecutar el doctor.none wired: nada declara el hook en absoluto.git-ignored house destinations: none | <rutas>. Cualquier cosa que no seanonees un destino que el verificador no puede ver; corrige la regla de ignorado como en el paso 4.
8. Enrutar lo que el repositorio no puede corregir upstream, un problema por elemento
Una sincronización o una verificación de cumplimiento a menudo revela hallazgos y advertencias que solo el paquete puede solucionar: una brecha en el verificador, un ancla de regla que nombra un archivo que no existe aquí, un espacio de configuración que el repositorio necesita y que el esquema no tiene. Para cada uno de esos elementos, corrígelo upstream en la misma sesión (rama y PR contra el repositorio del paquete, la misma salida ascendente primero del paso 3) o presenta UN problema por elemento procesable en el repositorio del paquete, lo suficientemente pequeño como para cerrarse con un solo cambio.
Nunca los agrupes en un problema de resumen de varios elementos: un resumen no se puede cerrar hasta que su elemento más lento llegue, sus elementos no se pueden priorizar de forma independiente y los resúmenes medio resueltos se acumulan. Lo que permanece en este repositorio es solo lo que este repositorio puede corregir.
Vías de escape
Estas son excepciones que se muestran en línea en la ruta predeterminada anterior, no un menú separado para elegir de antemano:
- Sin
house.json: detente en el paso 1, apunta a/house-rules:bootstrap. - Archivo modificado localmente: las tres salidas en el paso 3.
- Edición local confirmada como desechable:
--force-managed <ruta>, solo después de preguntar. - Primera sincronización en un repositorio,
.house/check.mjsaún no incluido: usahouse check --repo <ruta>en el paso 6 en lugar de la ruta incluida, y ten en cuenta que se trata de una sustitución única, no del estado estable.
No hacer
- No fusiones una modificación local...