GIT_TRACKING_POLICY

Git Tracking Policy

Created: 2026-03-06
Purpose: Categorization of all workspace files regarding Git tracking
Based on: Workspace scan after git filter-repo cleanup (Commit f9b35ca)

---

Legend

Symbol	Category	Meaning
✅	MUST	Must be tracked in Git
❌	NEVER	Must never be in Git
❓	UNCERTAIN	Decision required

---

✅ MUST Be in Git

Source Code

Path	Justification
apps/backend/src/opencloudtouch/	Entire backend source code
apps/backend/adapters/	Bose SoundTouch adapter
apps/backend/tests/	Backend tests (unit + integration + regression)
apps/frontend/src/	Entire frontend source code
apps/frontend/tests/	Frontend tests (unit + E2E Cypress specs)
apps/frontend/public/	Static assets (SVGs, icons, HTML templates)

Build & Deployment

Path	Justification
Dockerfile	Container build definition
deployment/docker-compose.yml	Docker Compose for production
deployment/local/deploy-local.ps1	Local deployment script
deployment/local/deploy-to-server.ps1	TrueNAS deployment script
deployment/local/export-image.ps1	Image export script
deployment/local/run-real-tests.ps1	Real hardware tests
deployment/local/.env.template	Environment variables template
deployment/local/config.ps1	Deployment configuration
deployment/local/clear-database.ps1	DB reset script
deployment/local/emergency-cleanup.ps1	Emergency cleanup
deployment/local/run-e2e-tests-remote.ps1	Remote E2E runner
deployment/README.md, deployment/LOCAL-DEPLOYMENT.md	Deployment documentation

Configuration & Standards

Path	Justification
.gitignore	Git exclusion rules
.gitattributes	Line-ending normalization
.pre-commit-config.yaml	Pre-commit hook configuration
.pre-commit-config-hooks/check-git-user.py	Hook script
.prettierrc, .prettierignore	Code formatting
.dockerignore	Docker build exclusions
.commitlintrc.json	Commit message format
config.example.yaml	Configuration template (NO secrets!)
.env.template	Environment variables template (root)
codecov.yml	Code coverage configuration
package.json, package-lock.json	Node.js dependencies
apps/backend/pyproject.toml	Python project definition
apps/backend/requirements*.txt	Python dependencies
apps/frontend/package.json, apps/frontend/package-lock.json	Frontend dependencies
apps/frontend/vite.config.ts	Vite build configuration
apps/frontend/tsconfig*.json	TypeScript configuration
apps/frontend/.eslintrc.json	ESLint configuration
apps/frontend/.prettierrc	Frontend Prettier
.vscode/settings.json	VS Code workspace settings

CI/CD

Path	Justification
.github/workflows/ci-cd.yml	Main CI/CD pipeline
.github/workflows/commitlint.yml	Commit lint workflow
.github/workflows/release.yml	Release automation
.github/dependabot.yml	Dependency updates
scripts/	Automation scripts (hooks, E2E runner, etc.)

Documentation (public)

Path	Justification
README.md	Project entry point
CHANGELOG.md	Version history
CONTRIBUTING.md	Contribution guidelines
SECURITY.md	Security guidelines
LICENSE, NOTICE, TRADEMARK.md	Legal documents
docs/API.md	API reference
docs/CONFIGURATION.md	Configuration documentation
docs/TESTING.md	Test documentation
docs/GIT_HOOKS.md	Hook documentation
docs/TROUBLESHOOTING.md	Troubleshooting
docs/SSH_QUICKSTART.md	SSH quickstart
docs/CONVENTIONAL_COMMITS.md	Commit format
docs/DEPENDENCY-MANAGEMENT.md	Dependency management
docs/BLOCKING_NO_VERIFY.md	No-verify blocking documentation
docs/LICENSES_*.md	License overviews
docs/PRESET_PLAYBACK.md	Preset playback documentation
docs/adr/	Architecture Decision Records
apps/backend/README.md	Backend documentation
apps/frontend/README.md	Frontend documentation
apps/frontend/DEVELOPMENT-MODES.md	Development modes

Bose API Reference (public schemas)

Path	Justification
apps/backend/bose_api/device_schemas/	153 XML schema files (publicly researched)
apps/backend/bose_api/README.md	API overview
apps/backend/bose_api/SCHEMA_DIFFERENCES.md	Schema differences
apps/backend/bose_api/2025.12.18 SoundTouch Web API.pdf	Original documentation
apps/backend/bose_api/PRESET_ANALYSIS_OCT.md	Preset analysis
apps/backend/bose_api/TEST_RESULTS_PRESET_COMPARISON.md	Test results
apps/backend/bose_api/analyze_api.py	API analysis script
apps/backend/bose_api/compare_api_sources.py	Schema comparison
apps/backend/bose_api/consolidate_schemas.py	Schema consolidation
apps/backend/bose_api/preset_*.xml	Example preset data (anonymized)

---

❌ NEVER in Git

Personal AI Agent Configuration

Path	Justification
AGENTS.md	Personal AI development guidelines — in .gitignore
.github/AGENT_PROMPT_TEMPLATES.md	AI prompt templates — currently tracked! → clean up
.github/AGENT_TASK_PROTOCOL.md	AI task protocol — currently tracked! → clean up

Local Development Tools

Path	Justification
tools/local-scripts/	Personal automation scripts — in .gitignore
tools/firmware_branch_scanner.py	Personal analysis tool — in .gitignore
tools/Prepare-SoundTouchUSB.ps1	Personal device script — in .gitignore
tools/soundtouch-post-ssh.sh	Personal SSH script — in .gitignore
tools/Test-SoundTouchSSH.ps1	Personal test script — in .gitignore

Personal Analysis & Planning

Path	Justification
docs/analysis/	Personal research notes — in .gitignore
docs/project-planning/	Personal roadmap/planning folder — in .gitignore
reference-impl/	Personal reference implementations — in .gitignore

Secrets & Local Configuration

Path	Justification
.env, .env.local	Secrets — in .gitignore
deployment/local/.env	Local deployment secrets — in .gitignore
config.yaml	Local configuration with secrets — in .gitignore
docker-compose.override.yml	Local overrides — in .gitignore
apps/frontend/.env.development.local	Local dev env (contains private IPs)

Runtime Data & Databases

Path	Justification
data-local/	Local SQLite database — in .gitignore
deployment/data-local/	Container runtime data — in .gitignore
*.db, *.db-journal	Database files — in .gitignore

Build Artifacts

Path	Justification
apps/frontend/dist/	Vite build output — in .gitignore
apps/frontend/coverage/	Test coverage reports — in .gitignore
htmlcov/	Python coverage HTML — in .gitignore
.venv/	Python virtual environment — in .gitignore
apps/frontend/node_modules/	Node.js dependencies — in .gitignore
*.tar	Container image exports — in .gitignore

Test Artifacts

Path	Justification
apps/frontend/tests/e2e/screenshots/	Cypress screenshots — in .gitignore
apps/frontend/tests/e2e/reports/	Cypress reports — in .gitignore
cypress-output.txt, e2e-result.txt etc.	Test output files — in .gitignore
*_TEMP.md	Temporary documents — in .gitignore

---

❓ UNCERTAIN — Decision Required

Device-Specific Bose API Files with Personal Data

Path	Issue	Recommendation
apps/backend/bose_api/device_info_wohnzimmer.xml	Contains real device name "Wohnzimmer" and network information	Anonymize or remove
apps/backend/bose_api/preset_list_wohnzimmer.xml	Contains personal preset configuration	Anonymize or remove
apps/backend/bose_api/current_preset_list.xml	Current preset status of a real device	Anonymize or remove
apps/backend/bose_api/current_preset_list_prettified.xml	Same as above (formatted version)	Anonymize or remove

GitHub Agent Files

Path	Issue	Recommendation
.github/AGENT_PROMPT_TEMPLATES.md	Personal AI workflow documentation in public .github/	Either move to NEVER and add to .gitignore, or rewrite as neutral project documentation
.github/AGENT_TASK_PROTOCOL.md	Same as above	Same as above

CI Configuration Files

Path	Issue	Recommendation
.ci-config.json	Unclear purpose — CI-specific switches?	Verify if publicly safe
.ci-config.md	Documentation for .ci-config.json	Verify if publicly safe

Hardware-Specific Tools

Path	Issue	Recommendation
tools/pi4-usb-gadget/	USB gadget setup for Raspberry Pi 4 — could be useful for community	Either leave in NEVER (currently gitignored) or release as public documentation
tools/pi-zero-usb-gadget/	Same as above for Pi Zero	Same as above

Frontend Development Environment

Path	Issue	Recommendation
apps/frontend/.env.development.local	Contains local API URLs (may contain private IPs)	Add to .gitignore, create template
apps/frontend/.env.production	Contains production API configuration	Check for secrets, convert to template if needed

---

Summary

Category	Count (estimated)	Status
✅ MUST be in Git	~470 files	Correctly tracked
❌ NEVER in Git	~80+ files	Correctly gitignored (after filter-repo cleanup)
❓ UNCERTAIN	10 files	Decision pending

Recommended Next Steps

1. Anonymize device data: device_info_wohnzimmer.xml, preset_list_wohnzimmer.xml, current_preset_list*.xml — replace device names and network data
2. Decide on agent files: .github/AGENT_PROMPT_TEMPLATES.md and .github/AGENT_TASK_PROTOCOL.md — either delete/gitignore or prepare for community use
3. Check frontend .env: apps/frontend/.env.development.local and .env.production for secrets
4. Check .ci-config.*: Ensure no internal infrastructure details are exposed

---

Last reviewed: 2026-03-06 | After git filter-repo cleanup (f9b35ca)