testdouble / testdouble/han

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

Open
#202 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Shell
Stars
267
Forks
23
Avg merge
2d 6h
Merged PRs (30d)
12

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

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.

Written by the indexing model from the issue text.

Assessment

Tech stack
shell
Domain
build-system, documentation
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.