Han publishing cleanup#131
Draft
mxriverlynn wants to merge 22 commits into
Draft
Conversation
Specifies the seven-step cleanup from the source plan artifact: publish han-linear to the Codex channel, close the work-items-to-issues silent hole, repair the release process, correct the frozen Codex versions, delete the two decorative han-core dependencies, correct every falsified document, and turn on the publishing check. All seven steps are retained. Execution order is 1, 2, 6, 3, 4, 5, 7: the release repair moves ahead of the version correction, because the release only writes the Claude Code channel until repaired, so any release cut between the two would re-freeze the correction and land the check red. Deleting the dependencies edits two plugin directories, which forces both to bump at the next release, so the plan's own work triggers it. Reviewed by junior-developer, devops-engineer, edge-case-explorer, and information-architect, then synthesized by project-manager. Every specialist claim was verified against the files; three were verified and rejected. Review changed the spec substantially: the ordering was a partial order asserting five couplings it did not have while missing the one it did; the release gate had no placement and the natural reading put it after the pushed tag; "the check and release share one answer" had no bearer; the document survey was incomplete by five locations; and the count of version records was wrong (three, not two).
Round 1 of iterative-plan-review, team mode, spec-aware. Five specialists: junior-developer, adversarial-validator, evidence-based-investigator, devops-engineer, edge-case-explorer. 16 findings (14 major, 2 minor). The load-bearing corrections: - The check cannot block a merge. main is unprotected, the sole ruleset is disabled, and it carries no required_status_checks rule even if enabled. Three agents converged on this from different angles. The guarantee is now stated per surface: the release refuses, a pull request reports. The real enforcement was always the release gate, not the check. - Steps 3 and 4 become one unit. The gate goes live at step 3, but nine version gaps stay open until step 4, so shipping 3 without 4 froze every release in between. - The repaired release could detect a missing target but not create one, so its headline promise never fired for the case that motivated the work. It now creates missing records (D31). - han-linear is a third untrue han-core declaration, not two. It was also the plugin D8 had chosen as the tutorial's example of a *real* dependency edge. - "Roughly twenty releases" is eleven, verified by tag ancestry. - The bundle publishes a version in two channel-one records, so exempting it from version agreement left the suite's most-exercised hand-sync unchecked. Adds review-findings.md and review-iteration-history.md. Adds D31-D35 and T2. Corrects D4, D6, D8, D13, D22, D25, D26, D29 against evidence that falsified their rationales. Round 1 was not stable; round 2 is in progress.
Round 2 of the iterative review found that R1's two headline resolutions contradicted each other: F30 gave the release the ability to repair, which means the gate never sees the version disagreements F29's steps-3+4 unit was created to survive. The unit is reverted to the ordering D18 always recorded. Also scopes creation to the two channel-two targets where the evidence lives, stops it at content that must be authored, commits every target the release writes, and extends the bundle's exception to the creation verb. Adds D36-D40; corrects D6, D18, D24, D31, D33, D34, D35, D8, D19.
Adds F44-F66 to the findings file and the R2 round entry to the iteration history, and brings the spec's Summary and Review History up to date. R2 raised 17 major and 4 minor findings and rejected 2. Nearly all trace to D31: the release's ability to repair was granted late in R1 and never carried into the six neighbouring decisions it changed. Two findings were rejected on evidence: D18's numeral list is stated in the source plan's numbering and is correct, and han-atlassian's han-communication declaration is real (README.md:84-85 documents it), so step 5 remains three.
All three R3 specialists independently found that D36 contradicted itself: it committed creation to two channel-two targets while establishing, in its own rationale, that one of them IS the authored presence the other half refuses to invent. A record that is the presence cannot be created. That is verbatim the mistake R2 caught R1 making, in the decision R2 wrote to fix it. Nine of R3's ten major findings are its blast radius. Creation now reaches channel two's listing entry alone. The Linear plugin is closed by a person at step 1, as step 1 always said and step 3 denied. Step 1 becomes a binding constraint, and a new plugin merged past the check stops the next release rather than costing lateness. Adds D41; corrects D24, D34, D36, D39, D40. Records F67-F81 and the R3 round. Review stops at its 3-round cap, not stable.
Executive summary, phase index, and vocabulary grounding. Six phases, with the source spec's steps 5 and 6 merged into one because the spec binds them to a single change.
…outline - Add Builds on and Source step columns to the index; name the one real ID collision (Phase 6 vs Step 6) instead of the wrong one - Renumber open questions to match the spec's Open items 1-4; promote a decision buried in phase 3's preconditions to OQ-5 - Restore the spec's does-not-partition-evenly clause to the vocabulary, disambiguate publishing a plugin from publishing a work item, drop the hardcoded term count - Revert marking -> annotation to keep phase 2 traceable to its source - Generalize the platform vocabulary in OQ-3 - Reconcile the phase-kinds taxonomy with the two kinds actually used - Cut phase 1's unevidenced precondition; add deferral scent to the index
han-linear is advertised as an opt-in Codex install in the README but was never published there, so 'codex plugin add han-linear@han' errored. Adds the Codex manifest and the marketplace listing entry. The manifest is created at 1.0.2, the version the Claude marketplace already publishes for the plugin, so it is correct on arrival rather than a placeholder. The interface prose is authored from the plugin's description and its work-items-to-linear skill, patterned on han-atlassian as the closest comparable (opt-in, MCP-dependent). Listing entry is placed to preserve the two marketplaces' shared plugin ordering. The han meta-plugin remains absent from Codex, which does not support meta-plugins. Phase 1 of docs/plans/han-publishing-cleanup/build-phase-outline.md
…very slice heading The GitHub publisher drops work items annotated by another tracker: they match neither the publishable pattern nor the already-published-here count, so they are neither created nor reported. A file published to Jira and then pointed at GitHub loses those items with no error and no signal. check-annotations.sh accounts for every slice heading in every file given: publishable here, already published here, or unrecognized. It names every unrecognized heading at once and exits non-zero. A heading is in scope when it carries a symbolic ID, whatever follows it. That admits foreign annotations and hand-edited malformed headings, and never matches preamble prose like '## Shared reference artifacts', which would otherwise stop a valid run. Takes every per-repo file at once: a file published elsewhere is usually annotated across all its repos, so checking one repo at a time would create issues in the clean repos before reaching the annotated one. Not yet wired into the publish path. Phase 2 of docs/plans/han-publishing-cleanup/build-phase-outline.md
…ything create-issues.sh walked the file creating one issue at a time, so a heading it could not place was simply never matched: neither created nor counted. An annotation late in the file was also preceded by issues already created. It now runs check-annotations.sh over the file before anything reaches the target repo, ahead of label creation too, since creating a label is itself a change to the repo. A heading it cannot place stops the run and is named. Tests stub gh on PATH and assert nothing is sent.
… tracker's annotation The repair pass accepted only the publishable and already-published-here heading shapes, so a Jira- or Linear-annotated heading failed the heading shape check and landed in the malformed-heading bucket, whose documented remedy is to propose the corrected shape. Continue with fills would then strip the annotation and publish the items to GitHub as duplicates of work already tracked elsewhere -- the annotation never reaching a gate. Another tracker's annotation is now its own category, never repaired, and offers only Stop. The malformed-heading rule now covers what it was always for: a heading nobody else annotated. Step 5 accounts for every slice heading across every per-repo file at once before any repo is published to, so nothing publishes anywhere while one file is annotated elsewhere. The format reference now documents all three buckets and why the scan keys on the symbolic ID rather than the heading shape.
… long-form doc The canonical operator-facing doc described a publisher that silently dropped items another tracker had published. It now states the promise every run keeps -- each item published, skipped-and-counted, or surfaced -- and the two properties that make it real: the whole file is examined before the first issue, and every per-repo file before any repo. The 'three scripts behind one wrapper' count is unchanged and still true; check-annotations.sh is called by create-issues.sh, not added to the wrapper.
Records the verified state: exactly 8 plugins' channel-two records disagree with channel one (measured, matching the spec), the channel-two listing has never been touched by a release commit, and the plugin set is cleanly derivable from 11 directories. Names the release skill's exact defect sites and the contributor-guide line phase 3 must correct.
Two corrections from the specialist round, both re-verified live. The contributor-guide diagnosis was wrong and was labelled 'Confirmed live'. CONTRIBUTING.md:138 and :157 are about moving a SKILL between plugins, which touches none of the four publishing targets, so phase 3 does not falsify them and D7 excludes them. Rewriting them to name four targets would have made the guide wrong in a new way. The real gap is that CONTRIBUTING.md has no 'Adding a plugin' section at all and no contributor-facing doc mentions channel two's files -- so phase 3 adds a section rather than correcting a passage. Adds the measured create-path field list: channel two's listing entries carry no version field, so 'created at the version it is publishing' is vacuous for the only thing a release creates. Records the measured justification for D36's boundary -- channel two's listing entry is the only target with no authored field in it.
Four specialists in parallel: junior-developer, devops-engineer, edge-case-explorer, test-engineer. 26 claims, all evidenced; one disputed (bundle identity) resolved by measurement. Spec-maturity gate not tripped. Two independent reviews converged from opposite directions on the same structural call: the writes must be script-borne, because the testability boundary and the one-bearer rule are the same line.
Project-manager synthesis of the medium-team round. 22 decisions (19 full, 3 trivial), all settled by evidence; 9 YAGNI deferrals with reopen triggers; no blocking open items. Load-bearing call, reached independently by two reviewers from opposite directions: the release's writes become script-borne via a repo-root scripts/publishing-targets.sh with argument-free check and repair verbs, so the rule has one bearer shared with phase 6's CI check. Gate lands at a new Step 4.5 (after the writes, before anything irreversible); recovery is a scoped git restore, never git clean; change detection excludes the codex manifest so the repair does not manufacture patch bumps; tests use synthetic fixtures. CONTRIBUTING.md gains an Adding-a-plugin section rather than editing lines phase 3 does not falsify.
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.
No description provided.