fix(codex): register the three packages missing from the Codex catalog - #210
Merged
Conversation
Three Han packages the README tells Codex users to install cannot be installed. han-documentation and han-research are absent from .agents/plugins/marketplace.json despite having valid Codex manifests; han-linear is absent from the catalog and has never had a manifest at all. The root cause is structural rather than a one-off slip. Four hand-maintained lists enumerate the Codex-installable packages (the directory tree, the manifests, the catalog, the README) and nothing checks that they agree. The drift entered on 2c09799, which scaffolded both plugins and updated only the Claude marketplace; the comparison case is 556b49e, which updated both marketplace files plus CLAUDE.md, which is why han-ddd installs. The plan names the directory tree as the authority and adds one Bats check enforcing it, in three units that each leave the repo green: register the two plugins that already have manifests; give han-linear a manifest, a catalog entry, and a corrected CLAUDE.md line; then add the check. Planned with plan-a-change. Discovery ran structural and behavioral analysts; the review round ran test-engineer, devops-engineer, and junior-developer, which found nine defects in the draft, including a verification step using git stash that cannot reach committed history and a worked JSON example that would have introduced permanent formatting drift.
han-plugin-builder's guidance is where every plugin-asset decision in this repo is supposed to route, and it has no document describing the Codex packaging surface. Its only Codex mentions are plugin-naming.md's dot rule and that file's rename checklist, which acknowledges .codex-plugin/plugin.json and a Codex marketplace exist as things to keep in step. Nothing states a plugin needs both to ship. Recorded as a deferral with a reopening trigger rather than pulled into this change: the consistency check answers the question mechanically, and a failing check is a stronger statement than a document nobody has to read.
Both plugins have carried a valid .codex-plugin/plugin.json since they were scaffolded in 2c09799, but that commit updated only the Claude marketplace, so neither name was ever resolvable: $ codex plugin add han-documentation@han Error: plugin `han-documentation` was not found in marketplace `han` A Codex install reads the catalog first and the per-plugin manifest second, so the lookup failed before reaching manifests that were correct all along. Adding the two entries is the whole fix for these two. Both entries take the four-key form every existing entry uses, and sit after han-core and before han-planning: the Codex catalog's order is the Claude marketplace's order with its omissions removed, so restoring the omitted names to their Claude positions is the placement consistent with the file. Unit 1 of 3 from docs/plans/codex-marketplace-catalog-consistency. Closes two of the three symptoms in #198.
han-linear failed one layer deeper than han-documentation and
han-research: it was absent from the catalog and had never carried a
.codex-plugin/plugin.json on any commit, so a catalog entry alone would
have resolved to a directory with no manifest to read. Both land here.
The manifest copies the nine fields that are byte-identical across all
twelve siblings (author, homepage, repository, license, skills, and the
four constant interface keys) and supplies the eight package-specific
ones from han-linear's README and skill description.
It ships at 1.0.0 rather than mirroring the Claude manifest's 1.1.1. The
release skill's own rule is that a brand-new plugin is not bumped by the
release that introduces it, and a Codex manifest that has never existed
is that case. The two version fields are separate lineages: the release
skill bumps {source}/.claude-plugin/plugin.json and the Claude
marketplace, and never opens a .codex-plugin file. Eleven of twelve
pairs already differ, so seeding 1.1.1 would manufacture a parity the
next release destroys.
CLAUDE.md line 83 recorded the missing manifest as intentional. This
change makes that false, and it is the file every agent reads before
scaffolding, so it is corrected here rather than left to drift. Same
shape as 556b49e, which added han-ddd and updated the Codex catalog, the
Claude marketplace, and the map together.
Unit 2 of 3 from docs/plans/codex-marketplace-catalog-consistency.
Closes the third symptom in #198.
Nothing in the test, lint, or CI chain read a manifest or a marketplace file, so the four data fixes above would not have stopped the next plugin repeating 2c09799. This adds the check that would have caught #198 when han-linear and han-ddd landed. The directory tree is the authority: every han-* directory needs a Codex manifest and a catalog entry. The han-* glob excludes the han/ meta-plugin structurally rather than by an exception list. Three assertions, bash and grep only: 1. the enumeration is non-empty, so the other two cannot pass over an empty set while looking identical to success 2. every package has a .codex-plugin/plugin.json 3. every package has a catalog entry whose name and path sit in the same entry, matched in a three-line window rather than tested for presence anywhere in the file Deliberately not asserted: version parity (false for eleven of twelve pairs) and description parity (false for all twelve). Both would fail the build the day they landed, and neither is a latent goal, since the release skill touches only the Claude side. Verified against a worktree on the commit before the data fixes: the check fails there and names han-documentation, han-research, and han-linear, with han-linear failing both assertions. A consistency check nobody has seen fail is a check nobody knows works. sanity.bats stated that test/ keeps only harness-level checks, which this file breaks. Widened to name the second category, keeping the clause that still decides most cases: a test covering one script sits beside that script. Unit 3 of 3 from docs/plans/codex-marketplace-catalog-consistency.
mxriverlynn
changed the title
mxriverlynn
marked this pull request as ready for review
September 10, 2026 18:15
This was referenced Sep 10, 2026
Draft
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #198. Plans and implements the fix in five commits: two documentation commits carrying the change plan, then the three change units.
What #198 reported
Three Han packages the README tells Codex users to install could not be installed:
han-researchfailed identically.han-linearfailed one layer deeper: absent from the catalog and never carrying a Codex manifest on any commit.Why it happened
Four hand-maintained lists enumerate the Codex-installable packages — the
han-*directory tree, the per-plugin manifests,.agents/plugins/marketplace.json, and the README — and nothing checked that they agreed.The drift is visible in the history.
2c09799scaffoldedhan-documentationandhan-researchand updated only the Claude marketplace; its own message says "registered in the marketplace", singular. The comparison case is556b49e, which addedhan-dddand updated both marketplace files plusCLAUDE.md, which is whyhan-dddinstalls today.The three units
b83712f1928de6han-linear's manifest, its catalog entry, and theCLAUDE.mdline that recorded its absence as intentionalf15663fsanity.batsheader it makes staleEach unit leaves the repository green on its own.
The check
The directory tree is the authority: every
han-*directory needs both files. Thehan-*glob excludes thehanmeta-plugin structurally rather than by an exception list.Three assertions, bash and grep only:
.codex-plugin/plugin.jsonnameandpathsit in the same entry, matched in a three-line window rather than tested for presence anywhere in the fileDeliberately not asserted: version parity (false for eleven of twelve pairs) and description parity (false for all twelve). Both would fail the build the day they landed, and neither is a latent goal — the release skill touches only the Claude side.
Verified to actually fail
Run against a worktree on the commit before Unit 1, with only the test file copied in:
Exactly the three packages #198 names. On
HEAD: 121 tests pass, 0 fail, every lint hook passes.Worth a reviewer's attention
han-linear's Codex manifest ships at1.0.0, not the Claude manifest's1.1.1. The release skill's own rule is that a brand-new plugin is not bumped by the release that introduces it. The two version fields are separate lineages; seeding1.1.1would manufacture a parity the next release destroys. No version is bumped by this PR.han-linearas changed on the strength of the new manifest alone, and the level buckets have no entry for "gained Codex installability." Worth deciding deliberately at release time.CLAUDE.mdis edited, and it was not in the area originally scoped. Brought in because this change makes line 83 false, on the556b49eprecedent. Line 73 was cut for scope and is reinstatable.docs/choosing-a-han-plugin.mdstill gives Codex readers Claude-only install commands. Left alone as outside scope; recorded as a follow-up.Planning artifacts
docs/plans/codex-marketplace-catalog-consistency/carries the change plan, 11 decisions, 18 current-state findings, and the scope boundary. Nine items are deferred with reopening triggers, including a reverse check on the catalog and a Codex packaging document for thehan-plugin-builderguidance, which has none.Produced with
/han-planning:plan-a-change. The review round (test-engineer,devops-engineer,junior-developer) found nine defects in the draft plan, including a verification step usinggit stashthat cannot reach committed history, and a worked JSON example whose formatting would have diverged permanently from every sibling entry.