feat: junk-file gate, shell gate, and the reusable gate workflow

[scott-wueschinski-GTMify]

First deliverable of the uniform-CI plan. One reusable workflow that many repos call, so a rule gets fixed once instead of thirty times.

Why this repo is public

A private reusable workflow can only be called from inside the same org or user account. Four of the ten active repos live under the personal scott-wueschinski-GTMify account rather than the GTMify org, so an org-private host would have reached six of ten and left the rest on a vendored copy that drifts. Nothing secret lives here: workflow YAML and check scripts only.

The junk-file gate

This is the check that pays for itself immediately.

Nothing stopped 33 .claude/worktrees/* gitlinks and 40 .pos-supervisor/* files, one of them a SQLite analytics.db-wal, from becoming tracked in GTMify/GTMify. A write-ahead log is rewritten on nearly every run, so that repo was permanently dirty, the session-end auto-commit hook turned the dirt into a commit every time, and local master drifted 19 commits off origin carrying no app code at all. gtmify-config has a committed hooks/Icon for the same reason.

Three modes: diff against a base (what a PR would add), --staged (for the pre-commit hook landing next), --audit (one-time cleanups).

Two properties worth reviewing closely:

Only tracked paths can fail. Every mode enumerates through git, so a gitignored file on disk is invisible by construction. The gate objects to junk being tracked, not to junk existing.

.ci-junk-allowlist is a deliberate escape hatch. A gate with no legitimate override gets switched off the first time it is wrong.

Verification

35 cases, one throwaway git repo each, dirty in exactly one way. All pass. The two carrying the most weight:

Case	Proves
ignored_but_present	A gitignored analytics.db-wal on disk does not fail the gate
icon_in_a_longer_name	A file named My Icon Design.txt passes; this is the exact false-positive class that made auto_commit_on_exit.sh silently drop real work

The suite was observed failing, not only passing. Removing the worktree pattern turns 3 cases red; restoring it returns 35/0. self-test.yml runs that mutation on every PR to this repo, so the tests cannot quietly stop asserting anything. That check has already caught two false greens in the app repo, which is why it is wired in from the start.

shellcheck --severity=warning and bash -n are clean on all three scripts.

Deliberately not in this PR

House style is off, with the input wired and defaulted false. The linter lives in the private GTMify/claude-house-style repo, which a public workflow cannot read without a token. That needs your decision (make the linter public, or mint a read-only PAT) rather than ten repos each carrying a secret. Until then the local write-time hook covers the common case.

Enforcement has a hard limit. The org is on the free plan, where branch protection and rulesets return 403 on private repos, so these checks run and show red but cannot be made required. Real enforcement for the junk gate arrives in the next PR as a local pre-commit hook, which blocks junk before it can be committed at all and does not depend on a GitHub plan.

Incidental finding

A comment line beginning with the word shellcheck is parsed as a directive and fails the whole file. shell_gate.sh's own docblock had to be reworded, which is noted inline so nobody reintroduces it.

Next

Tag v1 on merge, then the spike: wire one personal-account repo and confirm a public reusable workflow actually resolves from a private repo in a different account. That assumption is load-bearing for the whole design and I would rather learn it on one repo than ten.

🤖 Generated with Claude Code