ai-repository-hygiene

AI Repository Hygiene

Keep shared repositories professional while preserving private development material in an external sidecar. Treat this as company compliance, not as a history-concealment mechanism.

Non-negotiable boundaries

• Never rewrite Git history, force-push, delete branches, or remove worktrees as part of hygiene.
• Never move or delete a tracked path automatically, even when its name contains agent, prompt, Gemini, Claude, or Codex.
• Never treat product-owned runtime prompts, model code, RAG logic, evaluations, or AI documentation as private workspace debris.
• Never move .env, credentials, keys, dependencies, databases, indexes, build outputs required in place, or configuration with a fixed runtime path.
• Never discard dirty worktree changes.
• Never commit or push unless the user explicitly requests it.
• Never print secret contents. Report paths only.
• Compare paths case-insensitively against the complete Git index before moving. Windows can expose gemini.md and tracked GEMINI.md as the same file.

Read references/policy.md when classification is ambiguous or when producing a compliance report.

Modes

Audit

Use audit by default. Make no changes.

python "$env:USERPROFILE\.codex\skills\ai-repository-hygiene\scripts\sidecar_hygiene.py" --repo .

The audit identifies safe sidecar candidates, tracked blockers, public ignore-file findings, protected paths, the inferred sidecar, and current Git status.

Apply

Use apply only when the user authorizes migration.

python "$env:USERPROFILE\.codex\skills\ai-repository-hygiene\scripts\sidecar_hygiene.py" --repo . --apply

Pass --sidecar-root <path> when the repository is not under a conventional github_repos/ directory. Apply mode moves only preflighted untracked root candidates and creates <repo>.code-workspace plus migration-report.json in the sidecar. It does not edit ignore files.

Workflow

1. Record the repository root, branch, git status --short, worktrees, and remotes.
2. Run the audit script. Do not infer safety from .gitignore or .git/info/exclude; ignored files can still be tracked or runtime-critical.
3. Inspect candidates using the policy classification:
   • move private human/agent workspace artifacts;
   • retain product-owned and runtime-required files;
   • leave tracked policy violations in place and report them for an ordinary reviewed repository change;
   • route secrets to approved secret storage, not the sidecar.
4. Apply migration only after the candidate list is safe.
5. Inspect remaining ignored/untracked files, including nested artifacts the root-candidate script intentionally does not move automatically.
6. Clean ignore files narrowly:
   • keep .gitignore limited to shared project outputs, environments, runtime data, and standard OS/editor files;
   • keep .dockerignore limited to files that must not enter the build context;
   • minimize .git/info/exclude after sidecar migration, retaining only genuine machine-local runtime paths.
7. Before removing a Docker exclusion, inspect Dockerfiles and Compose build contexts. Git exclusions do not affect Docker.
8. Verify behavior and repository integrity.
9. Report current-tree compliance separately from historical findings. Do not imply that ordinary deletion removes old Git objects.