zhifengjiang/git-repo-organizer

Git Repository Organizer

Fundamenta cada conclusión en una instantánea fresca de Git. Trata las referencias, los directorios verificados, los archivos sin commit y los remotos alojados como capas de estado separadas.

Selecciona el modo de operación

Infiere el modo más restrictivo autorizado por la solicitud:

• Analizar: inspecciona e informa sin modificar referencias, el índice ni el contenido del worktree. Usa git ls-remote cuando la verdad actual del remoto sea importante; no hagas fetch, merge, pull, commit, rebase, delete, push, crees ramas de seguimiento ni cambies de worktree solo para analizar.
• Refrescar: actualiza las referencias de seguimiento remoto (fetch) y luego informa. No integres una rama solo porque se actualizaron las referencias.
• Consolidar: organiza y consolida (commit) cambios solo en el worktree nombrado.
• Integrar: haz merge, rebase o cherry-pick solo de las ramas nombradas a través de un worktree de integración limpio.
• Limpiar: elimina solo ramas o worktrees que se demuestren seguros según la matriz de decisión.
• Sincronizar: haz push o fast-forward solo de las ramas nombradas después de refrescar y volver a verificar.

Si "整理" o "同步" no autorizan claramente mutaciones, primero inventaria y presenta las operaciones propuestas exactas. Exige confirmación explícita antes de eliminar referencias remotas, hacer force-push, reescribir historial compartido, descartar cambios o eliminar un worktree por la fuerza.

Construye una instantánea actual

1. Localiza el repositorio real y el directorio común de Git. Nunca asumas que el directorio de trabajo del prompt es la raíz del repositorio.
2. Lee las instrucciones del proyecto, como AGENTS.md, antes de actuar.
3. En modo Analizar, verifica los tips remotos activos sin actualizar las referencias de seguimiento remoto:

git ls-remote --symref --heads REMOTE

Indica claramente que las referencias remotas locales permanecen en caché y sin cambios. En modo Refrescar, o inmediatamente antes de una mutación remota solicitada explícitamente, ejecuta:

git fetch --all --prune --no-tags

Usa no-tags por defecto. Obtener ramas y obtener etiquetas son operaciones separadas; nunca sobrescribas automáticamente una etiqueta local conflictiva.

Hacer fetch actualiza solo las referencias de seguimiento remoto. En modo Refrescar, detente ahí y compara cada rama local con su contraparte remota sin integrar ninguno de los lados:

• Nunca hagas merge o pull solo para que una auditoría parezca actual. Una rama local puede estar legítimamente adelantada, atrasada o divergida; informa ese estado.
• Nunca hagas commit, stash, snapshot, switch, reset o toques un worktree sucio solo para analizarlo. Registra el estado sucio y trátalo como un bloqueador de mutación.
• Las ramas locales cuyo remoto fue eliminado (upstream gone) o que nunca se enviaron (push) siguen siendo solo locales; anótalo explícitamente en el informe.
• Solo entra en modo Sincronizar o Integrar cuando el usuario lo solicite explícitamente. Vuelve a ejecutar la auditoría inmediatamente antes, opera en el worktree que posee la rama y aplica la matriz de decisión.

4. Ejecuta la auditoría de solo lectura incluida:

python3 scripts/audit_git_state.py --repo /ruta/absoluta --format markdown
python3 scripts/audit_git_state.py --repo /ruta/absoluta --base main --format json

Resuelve los scripts relativos al directorio de este skill, no al repositorio objetivo.

5. Inspecciona los commits únicos y los archivos modificados de cada rama que pueda mantenerse, integrarse o eliminarse:

git log --left-right --cherry-pick --oneline BASE...RAMA
git diff --stat BASE...RAMA
git diff --name-status BASE...RAMA

Lee diffs representativos antes de describir la funcionalidad de una rama. No infieras la función a partir del nombre de la rama.

6. Clasifica cada worktree desprendido (detached) antes de limpiar:

git merge-base --is-ancestor HEAD BASE && echo "HEAD ya está en BASE"

Verifica tanto contra la base local como contra la base remota (por ejemplo main y github/main). Un HEAD desprendido limpio que es ancestro de la base remota está ya fusionado (ya está en la base): no necesita reintegración ni una rama de recuperación; probablemente es un remanente de un script de verificación y puede eliminarse de forma segura después de la confirmación. Un HEAD desprendido que no es ancestro puede contener commits únicos; crea una rama de recuperación en HEAD antes de cualquier eliminación, incluso si el worktree parece limpio. Inspecciona los archivos no rastreados y separa los artefactos generados (salidas de prueba, directorios de construcción) del trabajo escrito a mano antes de la eliminación forzada.

7. Mantén la salida proporcional a la decisión. Escribe la auditoría JSON y las listas de referencias/worktrees/diffs en un archivo temporal y lee solo los resúmenes. Realiza inmersiones profundas solo para las ramas que son candidatas a integración o eliminación; no llenes el contexto con registros por rama y diffs completos en repositorios grandes.

8. Vuelve a ejecutar la auditoría inmediatamente antes del informe final y antes de cada mutación. Los repositorios pueden cambiar mientras se ejecuta el análisis; incluye la hora de la instantánea y los hashes de los tips en el resultado. También presta atención a la actividad concurrente: una referencia, worktree o rama remota creada o eliminada por otro proceso desde la última instantánea (por ejemplo, una rama candidata a fusión) cambia el plan; vuelve a presentar el plan en lugar de actuar sobre objetivos obsoletos.

Mantén el modelo de estado preciso

• La copia de trabajo normal del repositorio es el worktree principal. Aparece en git worktree list pero no es un worktree enlazado externo.
• Una rama verificada en otra ruta es un worktree enlazado externo.
• Un worktree desprendido tiene un commit verificado pero ninguna rama. Trata los worktrees desprendidos sucios como trabajo recuperable, no como basura. Siempre verifica si su HEAD es ancestro de la base (local y remota): si es así y el worktree está limpio, ya está fusionado y no necesita reintegración; si no, sus commits pueden volverse inalcanzables después de la eliminación y necesitan primero una rama de recuperación.
• Una referencia de rama (branch ref) y un worktree son objetos diferentes. Eliminar un worktree enlazado limpio no elimina su rama; eliminar una rama no maneja de forma segura un worktree sucio.
• HEAD remoto es un puntero simbólico a la rama predeterminada, no otra rama remota.
• Una referencia de seguimiento remoto es una observación local del estado remoto. Obtenerla (fetch) no es hacer pull ni merge.
• No crees una rama local para cada rama remota a menos que el usuario pida ramas de seguimiento local.

Al explicar el estado al usuario, mantén estos hechos claros:

• Una referencia de rama puede estar verificada como máximo en un único worktree a la vez (0 o 1); Git rechaza una segunda verificación de la misma rama.
• Eliminar un worktree elimina solo su directorio y registro. Las referencias de rama y los commits permanecen en el repositorio compartido; la rama simplemente deja de estar verificada y se puede volver a verificar más tarde.
• Eliminar un worktree solo pierde el trabajo no consolidado (archivos staged, unstaged, no rastreados o en conflicto). "Limpio" significa que el riesgo de pérdida es cero, no que la rama esté fusionada.
• Un worktree desprendido no ocupa ninguna rama. Su HEAD apunta directamente a un commit, por lo que nunca causa que otro worktree gane o pierda una rama.
• Las ramas no están "dentro" del worktree principal; las ramas no verificadas existen como referencias y se pueden cambiar en cualquier momento.

Define ramas claramente eliminables

Una rama es claramente eliminable (明确删除) solo cuando su contenido está completamente fusionado en la rama base prevista (normalmente main):

• Por ascendencia: el tip de la rama es un ancestro de la base (git merge-base --is-ancestor RAMA BASE), por lo que tiene cero commits exclusivos de la rama.
• Por equivalencia de parches: cada commit exclusivo de la rama tiene un patch-id equivalente ya presente en la base (git cherry BASE RAMA no muestra entradas +), verificado con git patch-id, nunca a partir de los asuntos de los commits.

Cualquier rama con un commit único o un parche único no es claramente eliminable, incluso si su trabajo parece redundante, su nombre se asemeja a una rama fusionada o su tip está preservado por una etiqueta. Las ramas archivadas con etiquetas solo pueden eliminarse con confirmación explícita, no por esta regla.

Una rama puede, en cambio, estar superada (被取代): implementa una funcionalidad ya entregada por una implementación evolucionada o alternativa en la base. Verifica commit por commit y archivo por archivo que la base cubre la misma intención y archivos, y que las líneas restantes exclusivas de la rama son remanentes obsoletos en lugar de funcionalidad faltante. Las ramas superadas no son claramente eliminables por esta regla; archiva el tip exacto con una etiqueta, presenta la evidencia de comparación y elimina solo después de la confirmación explícita del usuario.

Para ramas remotas, la evidencia de contenido fusionado debe mantenerse contra la base remota; el contenido fusionado solo en una base local no enviada (push) no califica. Siempre aplica los filtros de eliminación en references/decision-matrix.md antes de eliminar.

Informa con una matriz de ramas fija

Para cada nombre de rama canónico, informa:

Campo	Significado requerido
Local	Si refs/heads contiene la rama
Remoto	Cada referencia remota con el mismo nombre, no solo la ascendente (upstream)
Sincronización	Adelantada/atrasada o divergida respecto a su upstream configurado
Relación con base	Commits solo en la base y solo en la rama, ascendencia y evidencia de equivalencia de parches
Verificación	No verificada, worktree principal, worktree enlazado externo o desprendido
Estado del worktree	Archivos staged, unstaged, no rastreados y conflictos
Función	Funcionalidades o correcciones probadas por commits y diffs
Recomendación	Mantener, consolidar, integrar, archivar, eliminar o investigar; usa "eliminar" solo para ramas claramente eliminables cuyo contenido está completamente fusionado en la base

Enumera los worktrees desprendidos y podables por separado, cada uno con su hash HEAD, si ese HEAD es ancestro de la base local y remota, estado limpio/sucio, artefactos no rastreados y una recomendación (seguro de eliminar / rama de recuperación primero / mantener). Termina con acciones ordenadas divididas en: seguro ahora, requiere confirmación y bloqueado por trabajo no consolidado o único. Cuando el usuario quiera una vista solo local, o cuando la solicitud involucre decisiones de limpieza/eliminación (整理、删除候选、哪些可以删), incluye siempre el diagrama de repositorio local coloreado a continuación como parte del informe; no esperes una solicitud explícita de "画图".

Dibuja el diagrama del repositorio local (画出本地的代码库图)

Actívalo ante solicitudes explícitas como "画出本地的代码库图", "本地 Git 状态的图", "只展示本地分支", o "本地优先视图", e inclúyelo automáticamente en cada informe orientado a limpieza (整理、删除候选、哪些可以删). Genera un diagrama de ramas local-prioritario:

• Vuelve a ejecutar la auditoría inmediatamente antes de dibujar; etiqueta el diagrama con la hora de la instantánea y los hashes de los tips.
• Limita el alcance a solo las ramas locales (refs/heads/*). No renderices ramas solo remotas.
• Marca cada rama que también tenga una rama remota con el mismo nombre como 也有远程分支; de lo contrario, marca 无远程分支, distinguiendo entre nunca enviada (push) y enviada y luego eliminada (upstream gone).
• Agrupa las ramas por naturaleza: longevas/principales (mantener), temporales (archivar/eliminar tras confirmación) y trabajo real (mantener y decidir integración).
• Adjunta el estado del worktree a cada rama: no verificada, worktree principal o worktree enlazado (con su ruta), y estado limpio/sucio.
• Adjunta evidencia de limpieza: commits/parches únicos, estado del upstream (incluyendo adelantado/atrasado), archivos sucios y stashes.
• Si otro proceso creó un candidato a fusión o una referencia de verificación durante la sesión, coloca esas ramas en su propio grupo pendiente; infórmalas pero no las modifiques hasta que el proceso externo se resuelva.
• Dibuja cada worktree desprendido en el subgrafo de Worktree aunque no tenga rama: etiquétalo detached <ruta> → HEAD <hash>, con estado limpio/sucio y el veredicto de ancestro (✔ HEAD 已在 base 中，已合入 o ✘ 未合入，需恢复分支). No tiene borde de rama.
• Renderiza un diagrama de flujo mermaid con un subgrafo por grupo más un subgrafo separado de worktree; conecta cada rama verificada con su worktree.

Plantilla:

flowchart TB
    subgraph LOCAL["本地分支 refs/heads/*"]
        subgraph KEEP["长期/主要 —— 保留"]
            A["main（ahead 25 · behind 4）<br/>✔ 也有远程分支<br/>primary worktree · 干净"]
            B["dev<br/>✔ 也有远程分支 · 未检出<br/>祖先，已完全合入 main"]
        end
        subgraph TEMP["临时性 —— 确认后归档/删除"]
            C["branch-c（N 个独有提交）<br/>✘ 无远程分支（upstream gone）<br/>linked worktree · 脏"]
        end
        subgraph WORK["有实际工作 —— 保留并决定是否合入"]
            D["branch-d（N 个独有提交）<br/>✘ 无远程分支（从未推送）<br/>linked worktree · 干净"]
        end
        subgraph PENDING["在途/外部验证 —— 不动"]
            E["merge-candidate-x（外部创建）<br/>✔ 也有远程分支 · linked worktree · 干净"]
        end
    end

    subgraph WT["Worktree"]
        W1["primary /ruta/al/repo → main · 干净"]
        W2["linked /ruta/al/wt1 → branch-d · 干净"]
        W3["linked /ruta/al/wt2 → branch-c · 脏"]
        W4["linked /ruta/al/wt3 → merge-candidate-x · 干净"]
        W5["detached /ruta/al/wt4 → HEAD abc1234 · 干净<br/>✔ HEAD 已在 base 中（已合入）"]
        W6["detached /ruta/al/wt5 → HEAD def5678 · 脏<br/>✘ 未合入（需恢复分支）"]
    end

    A --> W1
    B -- "祖先" --> A
    D --> W2
    C --> W3
    E --> W4

    style LOCAL fill:#e3f2fd,stroke:#1e88e5
    style KEEP fill:#e8f5e9,stroke:#4c8c4c
    style TEMP fill:#fff8e1,stroke:#f9a825
    style WORK fill:#e8eaf6,stroke:#3949ab
    style PENDING fill:#fff3e0,stroke:#fb8c00
    style WT fill:#f3e5f5,stroke:#8e24aa
    style A fill:#fce4ec,stroke:#d81b60

Organiza los commits locales

Trabaja solo dentro del worktree que posee los cambios.

1. Inspecciona archivos staged, unstaged, no rastreados, ignorados, generados, grandes y similares a secretos.
2. Separa las salidas generadas, cachés, capturas de pantalla, registros locales y credenciales de los cambios de producto. Para archivos de bloqueo (lockfiles), separa la reserialización solo de formato (por ejemplo, un cambio de estilo de comillas en la versión de pnpm) de los cambios reales de dependencias; verifica con un diff de dependencias antes de restaurar o hacer commit.
3. Agrupa los commits por comportamiento, no solo por directorio. Usa la preparación por parches (patch staging) cuando un archivo contenga múltiples preocupaciones:

git add -p
git diff --cached --check
git diff --cached --stat
git diff --cached

4. Ejecuta validación enfocada antes de cada commit lógico y validación más amplia antes de la integración.
5. Usa mensajes de commit convencionales. Nunca uses git add -A a ciegas en un worktree mixto o desconocido.
6. Vuelve a verificar el estado después de cada commit e indica exactamente qué queda sin consolidar.

Integra ramas de forma segura

Lee references/decision-matrix.md antes de merge, rebase, cherry-pick, eliminación, eliminación de worktrees u operaciones similares forzadas.

... [truncado para la traducción]