BUILD-INSTRUCTIONS — fix/untrack-operator-root-files (#340)

Created: 2026-03-22 Issue: #340 Purpose: Untrack operator custom root files so branch switches stop clobbering them

Rules for Harley

Run steps in order, one at a time
Confirm each result before moving to the next
Report any failures to operator immediately
Do NOT merge any PRs — operator merges

Step 0 — Verify starting state

Regardless of what branch you’re on, get to a clean state:

cd /mnt/d/scaffolder-engine
git status

If there are uncommitted changes to tracked files, stash them:

git stash

If git status shows the 4 operator files as modified (CLAUDE.md, STANDARDS.md, PROJECT-INSTRUCTIONS.md, RELEASE-CHECKLIST.md), that’s expected — they’re still tracked and differ from the repo versions. Do NOT stash these. Proceed.

Checkout dev and pull latest:

git checkout dev
git pull origin dev

Confirm you are on dev:

git branch --show-current

Expected: dev

Step 1 — Create fix branch from dev

git checkout -b fix/untrack-operator-root-files dev

Confirm:

git branch --show-current

Expected: fix/untrack-operator-root-files

Step 2 — Update .gitignore

Add the operator custom root file rules to .gitignore. Insert these lines after the .claude/settings.local.json line and before the templates/engine-root/ line:

# Operator custom root files — local working copies
# Generic product versions live in templates/project-root/
# The engine-root swap uses git add -f to force-commit generic versions for PRs
CLAUDE.md
STANDARDS.md
PROJECT-INSTRUCTIONS.md
RELEASE-CHECKLIST.md

Also update the ai-sessions comment from:

# Session state — operator-specific, not part of the product

to:

# Session state — operator-specific, local only, NO git operations

Confirm the edit:

cat .gitignore

Step 3 — Remove files from git tracking

This removes the files from git’s index (tracking) but keeps them on disk:

git rm --cached CLAUDE.md STANDARDS.md PROJECT-INSTRUCTIONS.md RELEASE-CHECKLIST.md

Confirm they’re still on disk:

ls -la CLAUDE.md STANDARDS.md PROJECT-INSTRUCTIONS.md RELEASE-CHECKLIST.md

Confirm git no longer tracks them:

git status

Expected: The 4 files should NOT appear as untracked (gitignore hides them). The .gitignore change and the 4 deleted-from-index files should show as staged.

Step 4 — Commit

git add .gitignore
git commit -m "fix: untrack operator custom root files (closes #340)"

Step 5 — Push and create PR to dev

git push origin fix/untrack-operator-root-files

Create PR:

gh pr create --base dev --head fix/untrack-operator-root-files --title "fix: untrack operator custom root files" --body "## Summary

Removes CLAUDE.md, STANDARDS.md, PROJECT-INSTRUCTIONS.md, and RELEASE-CHECKLIST.md from git tracking so branch switches stop overwriting operator custom versions with generic product versions.

Closes #340. Replaces the incomplete approach from PR #324.

## What changed

- \`.gitignore\`: Added rules to ignore the 4 operator custom root files
- \`git rm --cached\`: Removed the 4 files from the index (files stay on disk)

## Why the hotfix approach failed

PR #324 added gitignore rules via hotfix to main only. But gitignore only protects **untracked** files. Since dev and staging still tracked them, branch switches restored tracked versions and destroyed local copies.

## How this works

The fix branch merges to dev first, then flows through staging → main via normal release. Each merge propagates the untrack commit, so all three branches end up with the files untracked.

## Test plan

After merging to dev:
- [ ] Verify the 4 files are untracked on dev (\`git ls-files CLAUDE.md\` returns nothing)
- [ ] Verify the files still exist on disk
- [ ] After full release flow (dev → staging → main): branch switches between all three do not touch operator files
- [ ] \`git add -f CLAUDE.md\` still works (engine-root swap)"

Step 6 — Report results

Tell operator:

Branch created and pushed
PR number and URL
Ready for operator to merge

STOP HERE. Do not merge. Do not proceed to other work.