Fix initialisation guard: single sentinel + shared action, fail loud on silent-green CI#3
Merged
Merged
Conversation
…on silent-green
The "is this template initialised, should CI run?" question was answered by
five divergent copies of a repo-wide `{{...}}` grep (3 workflows, the
/init-template skill, and CLAUDE.md), each with a different exclusion list.
They drifted, and — worse — the grep false-positives on the template's OWN
literal token examples in docs/ and .claude/, so a fully-finished replication
silently skipped its CI/Docker pipelines while reporting green.
Root-cause fix:
- Add a `.template-uninitialised` sentinel as the ONE state signal. No more
token-grepping to decide initialisation state.
- Add `.github/actions/check-ready` composite action as the single source of
truth (sentinel check + notebooks/*.py scaffold check). All three workflows
call it, so they can't drift again.
- Tripwire: if the repo records real published nanopub URIs in
nanopubs/PUBLISHED.md but the guard would still skip, fail the run loudly
instead of passing green. This is the check that turns the silent-green
failure mode into a visible one.
- CLAUDE.md first-run guard now checks the sentinel, not a {{...}} grep.
- /init-template deletes the sentinel as its final step (activating the
workflows); README updated to describe the shared guard.
Logic verified across four states: uninitialised template (skip), finished+
scaffold+published (fail), initialised+real (run), initialised+scaffold+
unpublished (skip).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Why
A real replication built from this template (
j34ni/forrt-replication-zarr-consistency) published a nanopub chain and minted a Zenodo DOI on top of CI that had never actually run — the smoke run finished green in ~8 s, skipping pixi + the whole Snakefile pipeline, and the Docker workflow skippedBuild and pushon release (sodocker run ghcr.io/...:latestfrom the README fails — no image was ever pushed).Root cause
The question "is this template initialised → should the pipeline run?" was answered five different ways — the three workflows, the
/init-templateskill, andCLAUDE.md's first-run guard — each a repo-widegrep '{{[A-Z_]\+}}'with a different exclusion list. Two problems:{{TOKEN}}examples indocs/(forrt-form-fields.md, …) and.claude/skills/(they document the token system). The grep matches those, decides "not initialised", and skips — forever, even in a finished repo.Fix
.template-uninitialisedsentinel — the single state signal. No more token-grepping to decide initialisation./init-templatedeletes it as its final step, which activates the workflows..github/actions/check-ready— one composite action (sentinel +notebooks/*.pyscaffold check) that all three workflows call. They can't drift again.nanopubs/PUBLISHED.mdrecords real published nanopub URIs but the guard would still skip, the run fails loudly instead of passing green. This directly catches the failure mode above.CLAUDE.mdfirst-run guard now checks the sentinel.Verification
YAML validated; logic simulated across four states:
The template's own
PUBLISHED.mdcarries onlynp/RA…ellipsis examples (and the template repo is itself tagged), so the tripwire keys on real URIs (np/RA+ ≥10 id chars) and does not fire on this repo.Note for downstream repos
Repos already generated from the template (e.g. Jean's) won't get this retroactively — they need the same guard backported, plus a fresh release to actually publish the Docker image to GHCR.
🤖 Generated with Claude Code