docs(adr): the emitted CI template moves, the plugin does not (#13) - #15
Merged
Conversation
#13 asks which of the plugin and the CLI is wrong about `.mdx`. Answering it needed the premise measured first, and it did not hold. The issue names `hooks/lib.sh:is_doc()` as the primary intent-to-publish signal. Instrumented with real captured payloads, `is_doc()` has one caller — `post-edit.sh`, the `elif` branch — and it gates the ORPHAN warning. Under a `vault.yaml` the dirty-list append is unconditional (a `.ts` file lands on it too) and `is_doc()` never runs. So the issue`s option 2, "change the plugin`s signal", cannot fix the reported symptom: it is not on that code path. The nag comes from `published_by_repo_action()`, which reads the workflow`s actual `paths:` list. The suite already pins both shapes: under the emitted template a `.mdx` still nags (correct — the Action will not publish it), and under a widened one it goes silent. So the template is what is wrong, and all three of its `.md`-only filters must widen — widening only the two `paths:` swaps a silent no-publish for a silent no-op. That file lives in the private CLI repo, so this ADR is the plugin half: a record that the plugin`s behavior is deliberate and stays. Refs #13
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.
Records the product call issue #13 asks for. No plugin code changes — that is the finding, and the reasoning is why.
The premise did not hold, so the answer is not the one on offer
#13 offers two options: widen the emitted template, or stop treating
.mdxas the plugin's primary publish signal. I instrumented the second before choosing, firingpost-edit.shwith the real captured payload shape, each arm paired with the control that would falsify it (7/7):vault.yamlabove the file, the dirty-list append is unconditional —ROOT.md(whichis_doc()rejects) and evenCODE.tsland on the list. Orphan list empty (control).is_doc()does discriminate — the.mdxraises the orphan warning, a root.mdand a.tsraise nothing. Dirty list empty (control).is_doc()has exactly one caller,post-edit.sh'selifbranch, and it gates the orphan warning. It is not on the path that produces the nag. Option 2 would not have changed the reported symptom.What actually produces it, already tested here
published_by_repo_action()reads the workflow's realpaths:list.hooks/tests/run.shalready pins both shapes, green before this PR:paths:['**.md']— the emitted template.mdx['**.md','**.mdx']— hand-widened.mdxThe hook is right under both. It is honest about the inconsistency; it cannot resolve it.
The decision
The emitted CI template moves. Because the plugin is not the mechanism; because
.mdxis first-class to the product the template automates (basalt pullwrites canonical MDX, and the CLI's slug derivation strips.mdand.mdxalike, so the template is narrower than the CLI emitting it); and because narrowingis_doc()would blind the orphan sensor to exactly the extensionbasalt pullwrites — and that sensor exists for the one Basalt failure that is silent.Measured on
basalt-cli@0.10.0: the template has three.md-only filters, not the two #13 quotes — bothpaths:lists and the run step'sgit ls-files '*.md'. All three must widen, or a trigger fires on a file that is then never passed tobasalt publish.That file is in the private CLI repo (ADR 0001), so it ships from there. This is the plugin's half.
Follow-up this creates
When the template widens,
WF_CANONinhooks/tests/run.shshould widen with it and the.mdxcell flips from nags to silent legitimately — keeping its paired negative arm, since a doc edited and not pushed must still nag.Leaving #13 open until both halves agree; this PR does not close it.