Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Symlink the vendored rule files instead of re-syncing copies by hand

Abierto
  • ¿Algo no está bien?
#202 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Refactorización
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
shell
Área
build-system, documentation

Línea de trabajo

Start by reading #184, scripts/han-config-dir.sh, and the existing check-symlinks and destroyed-symlinks hooks, then verify dereference behavior for Claude and non-Claude packaging. Review the 22 references/*.md paths and CONTRIBUTING.md; done means the copies are replaced consistently, coverage and target correctness are tested, and the convention is documented.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Summary

The suite keeps shared material in sync three ways. One of them, byte-identical vendored copies, is the only one that
depends on a person remembering to re-sync, and it covers the most files. #184 already proved the alternative works. I
would like to reduce three mechanisms to two.

The companion issue on config-loading duplication (#203) is independent of this one; either can land first.

The three mechanisms

Mechanism Used by Sync burden
Symlink, dereferenced at install scripts/han-config-dir.sh none
Vendored byte-identical copy config-rule.md, collaborative-stop-rule.md, yagni-rule.md, evidence-rule.md manual, untested
No copy; declare a dependency readability-rule.md, writing-voice.md none

The middle row is 22 copies of 4 files, about 3,150 duplicated lines:

config-rule.md              151 lines x 12 copies = 1812
yagni-rule.md               146 lines x  4 copies =  584
evidence-rule.md            120 lines x  4 copies =  480
collaborative-stop-rule.md  137 lines x  2 copies =  274

Nothing tests that the copies match the canonical file.

There is no drift today

I checked all 22 copies against their canonical files on main: every one matches. I also walked
han-coding/references/config-rule.md against han-core's across every commit that touched the canonical file, and
they match at every point.

So this is not a bug report. It is a request to remove a manual invariant that holds only because maintainers keep
remembering it. The cost shows up in release notes: "the vendored rule files re-synced with their canonical copies" and
its variants appear 12 times in the v5.4.0 section of CHANGELOG.md.

Why symlinking works

55bdb1d (#184) records it:

Installation copies the symlink target as a regular file, so the script ships without any plugin depending on another
to reach it.

Verified across all 12 plugins in default mode, and end to end through a GitHub-source marketplace install.

I confirmed the install side independently: on a VM,
.claude/plugins/cache/han/han-communication/1.2.0/scripts/han-config-dir.sh is a regular file. A skill reads a real
file either way.

Linting is not an obstacle

Prettier on its own refuses an explicitly specified symlink and exits 2, and a .prettierignore entry does not suppress
it. But prek never hands a symlink to a hook. In a scratch repo tracking one symlinked .md whose target was
deliberately misformatted, prek run --all-files reported prettier ... Passed and left the target unchanged. No hook
change, exclude: rule, or ignore file is needed. The canonical file is still linted under its own path.

Why the markdown was never symlinked is not recorded anywhere: cfdfff7 carries a subject line and no body, and
CONTRIBUTING.md has no vendoring section. The two conventions landed two months apart, in #143 and then #184.

Proposal

  1. Replace the 22 vendored references/*.md copies with relative symlinks to their canonical files. No lint
    configuration changes.
  2. Add a test for what the existing hooks miss. check-symlinks and destroyed-symlinks already fail a dangling link
    or one flattened into a regular file. Neither can see coverage (a plugin that should carry a reference and
    carries nothing is not a symlink, so no symlink hook looks at it) or target correctness (a link that resolves,
    but to the wrong file).
  3. Record the convention in CONTRIBUTING.md.

Open questions

  • Is dereference-on-install guaranteed or incidental? Worth settling first. #184 verified it through a
    GitHub-source marketplace install and my VM agrees, but I cannot find it stated in Claude Code's docs. If it is
    incidental, a symlinked reference could one day ship dangling, which fails worse for a reference than for the script:
    the script's probe carries a 2>/dev/null || echo fallback and a references/*.md link has no equivalent. The repo
    side is already covered by check-symlinks and destroyed-symlinks; it is packaging I want confirmed.
  • Should some of these use the invoke-a-guidance-skill mechanism instead? readability-rule.md and
    writing-voice.md are not copied at all; consumers declare a han-communication dependency and invoke
    readability-guidance, which resolves them through its own ${CLAUDE_PLUGIN_ROOT}. That is a separate discussion,
    filed as #203. It does not compose for config-rule.md in any case, since readability-guidance itself
    points at config-rule.md by relative path into han-communication's own vendored copy.
  • Does non-Claude packaging dereference the same way? I have only checked the Claude Code side. #172 is doing Pi
    parity and touches .agents/plugins/marketplace.json, so it will likely reach the answer first.

Before I start

@mxriverlynn happy to take this on, including the first open question, if you have no objections. Checking first since
it touches every plugin, and you may have ruled symlinks out here for a reason that is not written down.

Lenguaje dominante
Shell
Estrellas
275
Forks
23
Merge medio
1 d 8 h
PR fusionados (30 d)
12

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de testdouble/han

Todos los issues de testdouble/han

Issues similares

Más issues de Shell/Bash

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.