feat(#517): keep onboarding config out of git (example-file + gitignore + guard) by atlas-apex · Pull Request #522 · me2resh/apexyard

atlas-apex · 2026-06-06T08:45:59Z

Summary

Makes the safe path the default for onboarding config — adopts the .env.example/.env convention: a tracked onboarding.example.yaml (placeholders) plus a gitignored onboarding.yaml (real values). Previously the real config was tracked and committed, so on a publicly-forked framework a CTO's company name, internal URLs, tracker instance, and team roster leaked into public history / upstream PR refs by default. Single-fork mode now matches what split-portfolio v2 already does.
Adds a commit-time backstop — new block-onboarding-in-git.sh (PreToolUse on git commit) blocks a staged onboarding.yaml whose content differs from the example placeholders (a placeholder-diff signal), so a git add -f or a pre-[Feature] Keep onboarding config out of git: example-file + gitignore + commit-time guard #517 tracked copy can't silently re-leak. Sibling to check-secrets.sh; env-var (APEXYARD_ALLOW_ONBOARDING_COMMIT=1) and in-message () escape hatches. 6-case test suite, all green.
Rewires detection + setup, no behaviour loss — onboarding-check.sh now reports "configured" from the local real file (or the v2 private committed copy) and prompts /setup on a fresh fork that has only the example; /setup copies the example → real and never stages the real file. Split-portfolio v2 is unaffected (private committed config still carries across clones); the only single-fork change is that each fresh clone runs /setup once.
Migration documented, not silent — docs/multi-project.md + the /setup skill carry the one-time git rm --cached onboarding.yaml step for existing adopters. Decision recorded in AgDR-0064.

Known follow-up (called out, not hidden)

The already-committed history of onboarding.yaml still contains prior real values — this PR untracks going forward but does not rewrite history. The full-history secret/config sweep is tracked in #518 (security hardening), which also reuses this PR's placeholder-diff signal for its release-artifact guard.

Testing

.claude/hooks/tests/test_block_onboarding_in_git.sh → 6 passed, 0 failed (filled-in blocked · placeholder-equals-example allowed · env-var escape · marker escape · non-onboarding file unaffected · non-commit ignored).
shellcheck -S error clean on the new + modified hooks.
python3 yaml.safe_load on onboarding.example.yaml; json.load on .claude/settings.json → valid.
git rm --cached onboarding.yaml verified: file untracked, git check-ignore confirms ignored, local copy preserved on disk.
markdownlint clean on the new AgDR.

Closes #517

Glossary

Term	Definition
Example-file pattern	Tracked `*.example` template + gitignored real file (like `.env.example`/`.env`).
Placeholder-diff	Detecting a filled-in template by comparing staged config against the shipped `*.example` placeholders.
Commit-time guard	A PreToolUse-on-`git commit` hook that blocks staged content which must never be published.
Single-fork vs split-portfolio v2	Default layout (config at fork root) vs the v2 layout where private config lives in a sibling private repo.
Escape hatch	A deliberate, auditable bypass (env var or in-message marker) for the rare legitimate case.

…re + guard) Layer 1 — structure: - Add tracked onboarding.example.yaml (placeholders only) as the template - Gitignore onboarding.yaml; untrack it (git rm --cached, local copy preserved) - /setup copies example -> onboarding.yaml (gitignored) and never stages the real file - onboarding-check.sh detects configured state from the local real file (or the v2 private committed copy), not a committed public file; prompts /setup on a fresh fork that has only the example Layer 2 — commit-time guard: - New block-onboarding-in-git.sh: blocks committing a filled-in onboarding.yaml via placeholder-diff vs onboarding.example.yaml; env-var + in-message escape hatches; wired into settings.json after check-secrets.sh - Tests: test_block_onboarding_in_git.sh (6 cases) — all green Docs: - Migration note (git rm --cached) in docs/multi-project.md + /setup SKILL - Hook listed in .claude/hooks/README.md - Decision recorded in AgDR-0064 Note: already-committed history still holds prior real values until the full-history scrub tracked in #518. This change untracks going forward. Closes #517 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ion drift - Bump hook count 39→40 across site/ marketing copy (the new block-onboarding-in-git.sh hook from this PR) — satisfies the site-counts drift gate - Incidental: bump site/index.html advertised version 2.2.0→2.3.0 to match CHANGELOG (pre-existing drift on dev from the 2.3.0 release; the version-drift guard only fires here because this PR touches site/) Refs #517 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

atlas-apex

Code Review (re-review): PR #522

Commit: e32983461407e1259395acd16d4e6ef6a279b0ca

Scope of this re-review

Prior APPROVAL stands at f5a9c6f. This re-review covers the single new commit e329834 — a site/ marketing-copy drift refresh triggered because this PR now touches site/.

Verification of the new commit

Scope — clean, no creep ✅
Commit e329834 touches exactly the 7 site/ files described and nothing else: site/architecture.html, site/architecture.md.gen, site/index.html, site/index.md.gen, site/llms-full.txt, site/llms.txt, site/skill.md. No code, hook, test, or feature file is touched by this commit.
Hook count bump 39 → 40 — correct ✅
The canonical count (find .claude/hooks -maxdepth 1 -name '*.sh' ! -name '_lib*', per test_site_counts.sh) returns 40 at HEAD e329834. The new block-onboarding-in-git.sh this PR adds is included in that set. Every 39 → 40 edit across the 7 files is a 1:1 refresh of the same claim — no over- or under-count.
Version bump 2.2.0 → 2.3.0 — matches CHANGELOG ✅
CHANGELOG.md top release entry at HEAD is ## [2.3.0] — 2026-06-04. site/index.html softwareVersion and the v2.3.0 release-tag link are both bumped to 2.3.0, satisfying the version-drift guard (#493). This was pre-existing drift on dev that surfaced only because the PR now touches site/ — correctly resolved in-band rather than left for a later cut.
Prior approval rationale holds ✅
The new commit carries zero functional or behavioural change to the onboarding feature (block-onboarding-in-git.sh, onboarding-check.sh, /setup, .gitignore, AgDR-0064). The feature code reviewed at f5a9c6f is byte-identical at e329834. Nothing in a marketing-copy refresh can invalidate the original verdict.

Checklist Results

✅ Architecture & Design: Pass (unchanged from f5a9c6f)
✅ Code Quality: Pass (no code change in new commit)
✅ Testing: Pass (6-case hook suite green; drift gate satisfied by the count + version refresh)
✅ Security: Pass (this is the leak-prevention feature itself)
✅ Performance: Pass (N/A — docs only)
✅ PR Description & Glossary: Pass (narrative summary + glossary present)
✅ Summary Bullet Narrative: Pass
✅ Technical Decisions (AgDR): Pass — AgDR-0064 linked
✅ Adopter Handbooks: N/A (no handbooks loaded)

Issues Found

None.

Verdict

APPROVED (recorded via comment — Rex cannot self-approve on GitHub; approval marker written for the merge gate.)

🤖 Reviewed by Rex (Code Reviewer Agent)
📌 Reviewed commit: e32983461407e1259395acd16d4e6ef6a279b0ca

) Follow-up to the #517 review (PR #522): the staged-path check used `grep -qx`, so the '.' in 'onboarding.yaml' was a regex wildcard. Switch to `grep -Fxq` (fixed string, still whole-line anchored) so it matches the literal filename only. No behaviour change in practice; removes a latent over-match. Refs #517 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot added github-issue has-ticket labels Jun 6, 2026

atlas-apex commented Jun 6, 2026

View reviewed changes

atlas-apex merged commit 3c1e728 into dev Jun 6, 2026
5 checks passed

atlas-apex deleted the feature/GH-517-onboarding-out-of-git branch June 6, 2026 10:24

atlas-apex mentioned this pull request Jun 6, 2026

chore(#517): onboarding guard literal filename match (grep -Fxq) #525

Merged

atlas-apex mentioned this pull request Jun 6, 2026

release(#534): v3.0.0 #535

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(#517): keep onboarding config out of git (example-file + gitignore + guard)#522

feat(#517): keep onboarding config out of git (example-file + gitignore + guard)#522
atlas-apex merged 2 commits into
devfrom
feature/GH-517-onboarding-out-of-git

atlas-apex commented Jun 6, 2026

Uh oh!

atlas-apex left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

atlas-apex commented Jun 6, 2026

Summary

Known follow-up (called out, not hidden)

Testing

Glossary

Uh oh!

atlas-apex left a comment

Choose a reason for hiding this comment

Code Review (re-review): PR #522

Scope of this re-review

Verification of the new commit

Checklist Results

Issues Found

Verdict

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants