You are responsible for a comprehensive **Git repository cleanup, worktree hygiene, and source-of-truth clarification pass**.

Your objective is **not** merely to make `git status` empty.

Your objective is to leave the repository:

- correctly tracked;
- correctly ignored;
- low-noise;
- safe to continue developing;
- easy to navigate;
- explicit about authoritative source versus generated output;
- free of unnecessary build, cache, temporary, runtime, backup, dump, archive, and obsolete artifacts where safely possible;
- clear about what belongs in source control;
- understandable to future maintainers;
- less likely to produce confusing dirty-worktree warnings during normal development;
- fully usable through its normal development, build, test, packaging, and deployment workflows.

The highest-level rule is:

> **Make the repository correct, intentional, and understandable without destroying legitimate work.**

This is an **implementation task**, not merely an audit.

Do not stop after listing problems or creating recommendations.

Inspect the repository, determine why it is dirty or confusing, classify the causes, make justified corrections, validate the affected workflows, reassess the result, and continue while worthwhile repository-hygiene improvements remain.

---

# Core Scope

This pass is responsible for:

- Git tracking correctness;
- `.gitignore` correctness;
- dirty-worktree noise;
- generated files;
- build and distribution output;
- local runtime state;
- caches;
- logs;
- temporary files;
- editor and OS metadata;
- machine-local configuration;
- secrets or secret-like files accidentally stored in the repository;
- backups and accidental copies;
- stale archives and dumps;
- obsolete repository artifacts;
- unclear source-versus-generated relationships;
- unnecessary repository clutter;
- repository organization where clutter materially harms comprehension;
- concise documentation of important source-of-truth relationships;
- validating that cleanup does not break normal workflows.

This is **not primarily**:

- a code-quality refactor;
- an architecture redesign;
- a feature sprint;
- a performance optimization pass;
- a dependency-upgrade campaign;
- a formatting or naming cleanup;
- a broad documentation rewrite;
- unrelated technical-debt cleanup.

If unrelated problems are discovered, leave them alone unless they directly block repository hygiene.

Record important out-of-scope findings briefly for later work.

---

# Critical Safety Rule

## Never destroy legitimate work merely to clean Git

Treat all existing:

- modified files;
- staged files;
- deleted files;
- renamed files;
- conflicted files;
- untracked files;

as potentially valuable until evidence establishes otherwise.

Existing work may belong to:

- the current developer;
- another developer;
- an earlier task;
- an unfinished development session;
- an automated tool;
- a build or generation process.

Do not assume:

- an existing change belongs to this task;
- an uncommitted file is disposable;
- an unfamiliar file is generated;
- an untracked file should be ignored;
- a dirty repository is necessarily incorrect.

### Never use broad destructive cleanup as a shortcut

Do not use operations such as:

- `git reset --hard`;
- `git clean -fd`;
- `git clean -fdx`;
- `git checkout -- .`;
- `git restore .`;
- equivalent destructive operations;

merely to obtain a cleaner status.

Do not:

- revert unknown work;
- overwrite pre-existing modifications;
- delete ambiguous untracked files;
- mass-untrack files without understanding their purpose;
- rewrite history merely for cleanliness;
- force-push;
- silently remove source because another copy appears to exist.

A clean `git status` produced by destroying legitimate work is a **failed cleanup**.

The repository may legitimately remain modified after this task when those modifications represent intentional work.

---

# Preserve Existing Work Intelligently

When pre-existing work can be identified:

1. determine what it appears to accomplish;
2. determine whether it is source, generated output, runtime state, or ambiguous;
3. preserve legitimate work;
4. distinguish it from repository-hygiene noise;
5. avoid broad edits across unrelated modifications;
6. sequence cleanup around it when necessary;
7. leave ambiguous areas unchanged rather than guessing;
8. report unresolved ambiguity when it materially affects the result.

Use Git as evidence where useful:

- `git status`;
- working-tree diff;
- staged diff;
- log;
- blame;
- file history;
- tracking history;
- ignore behavior.

Do not use Git as a tool for erasing uncertainty.

---

# Investigate Before Asking Questions

Use evidence already available in the repository before asking for clarification.

Inspect relevant:

- Git state;
- source code;
- build configuration;
- package configuration;
- compiler configuration;
- bundler configuration;
- project or engine configuration;
- scripts;
- generation scripts;
- deployment configuration;
- CI configuration;
- documentation;
- imports and references;
- generated-file headers or comments;
- dependency configuration;
- repository history;
- existing conventions;
- actual build behavior;
- actual generation behavior.

Resolve questions from repository evidence whenever possible.

Ask for clarification only when proceeding safely genuinely requires information that cannot be established, such as:

- ownership of important ambiguous work;
- whether an ambiguous asset is authoritative source;
- undocumented deployment requirements affecting tracking;
- deletion that could plausibly destroy irreplaceable material;
- a tracked credential requiring an owner decision;
- required external access that is unavailable.

Do not ask questions merely because investigation takes effort.

---

# Implementation Over Auditing

The audit exists to create an **implementation queue**.

Do not spend most of the task:

- inventorying files;
- narrating repository structure;
- describing problems;
- producing speculative recommendations;
- repeatedly reassessing categories that are already understood.

Once enough evidence exists to act safely:

> **act.**

Use this loop:

> **Investigate → classify → implement → validate → reinspect**

Prefer small, coherent cleanup cycles over one enormous audit followed by one enormous modification phase.

For each meaningful problem category:

1. gather enough evidence;
2. determine what the files represent;
3. determine the correct repository behavior;
4. implement the cleanup;
5. validate the result;
6. inspect the resulting Git state;
7. continue to the next worthwhile category.

Do not manufacture changes after useful work is exhausted.

---

# Phase 1 — Establish the Repository Baseline

Before substantive cleanup, understand enough of the repository to make responsible decisions.

Inspect:

- repository root;
- current branch;
- Git status;
- staged changes;
- modified tracked files;
- deleted tracked files;
- renamed files;
- untracked files;
- relevant ignored files;
- root `.gitignore`;
- nested `.gitignore` files;
- major applications or packages;
- source directories;
- generated directories;
- build configuration;
- compiler configuration;
- bundler configuration;
- project or engine configuration where applicable;
- package scripts;
- generation scripts;
- output paths;
- deployment configuration;
- CI configuration;
- local-development configuration;
- documentation;
- lockfiles;
- runtime directories.

Build an internal map of which locations represent:

1. **authoritative source**;
2. **generated source or generated files**;
3. **build or package output**;
4. **runtime/local state**;
5. **developer-machine state**;
6. **vendored dependencies**;
7. **production/deployment artifacts**;
8. **documentation**;
9. **obsolete clutter**.

Do not classify files from names alone.

Use configuration, scripts, references, history, and actual behavior.

You do not need to understand every source file.

Understand the repository **as a repository**.

---

# Phase 2 — Classify the Dirty Worktree

Classify every meaningful dirty-worktree category.

When many files clearly share the same cause, group them rather than inspecting every file individually.

## A. Legitimate Existing Source Changes

Existing intentional development work.

Preserve it.

Determine whether it:

- is already correctly tracked;
- belongs to unfinished development;
- can safely coexist with cleanup;
- requires no repository-hygiene action.

Do not revert legitimate work because it makes the repository dirty.

---

## B. Legitimate New Source Files

Untracked files may be real source.

Examples include:

- components;
- modules;
- services;
- types;
- migrations;
- tests;
- scenes;
- shaders;
- source assets;
- scripts;
- repository configuration.

Do not ignore legitimate source merely to silence Git.

Determine whether it belongs in normal tracking.

---

## C. Generated Source or Generated Files

Examples include:

- generated clients;
- generated schemas;
- generated manifests;
- compiled source;
- generated CSS;
- generated metadata;
- source maps;
- generated resources.

Establish:

- what produces them;
- what consumes them;
- whether they are reproducible;
- whether they are intentionally committed;
- whether production, packaging, or deployment requires committed copies.

Do not blindly ignore generated files.

Some projects intentionally commit generated artifacts.

---

## D. Build and Distribution Output

Examples include:

- `dist/`;
- `build/`;
- export directories;
- packaged executables;
- deployment staging directories;
- extension bundles;
- release archives;
- installer output.

Determine whether each output is:

- intentionally committed;
- locally generated only;
- required by deployment;
- safe to ignore;
- stale or obsolete.

---

## E. Cache and Temporary Files

Look for:

- compiler caches;
- framework caches;
- engine caches;
- test caches;
- package-manager caches;
- temporary files;
- editor state;
- OS metadata.

These normally should not pollute Git.

Use narrow, project-appropriate ignore rules.

---

## F. Logs and Runtime State

Look for:

- logs;
- debug logs;
- PID files;
- cursor files;
- worker state;
- local queues;
- runtime caches;
- sessions;
- local databases;
- locally generated application state.

Determine whether the application unnecessarily writes them inside source directories.

Ignore or safely relocate them where justified.

Do not alter working runtime behavior merely for repository aesthetics.

---

## G. Machine-Local Configuration and Secrets

Look for indicators of:

- `.env`;
- local credentials;
- API tokens;
- passwords;
- certificates;
- private keys;
- machine-specific configuration.

Do **not** print secret contents.

Determine tracking state without exposing values.

Prefer patterns such as:

- ignored local secret files;
- documented environment variables;
- safe example configuration such as `.env.example`.

If a secret is already committed:

1. identify the problem clearly;
2. do not expose the secret value;
3. do not pretend deleting the current file removes it from Git history;
4. do not rotate credentials unless explicitly authorized and technically possible;
5. separate present-worktree cleanup from any required history-remediation or credential-rotation work.

---

## H. Backups and Accidental Copies

Look for:

- `.bak`;
- `.orig`;
- `*-old`;
- `*-copy`;
- timestamped copies;
- duplicate source trees;
- backup directories;
- downloaded archives;
- old deployment packages.

Remove them only when redundancy or obsolescence is established with high confidence.

---

## I. Obsolete Repository Artifacts

Look for:

- stale generated files;
- superseded configuration;
- abandoned migration output;
- duplicate generated resources;
- obsolete packages;
- incomplete migration leftovers;
- artifacts whose authoritative replacement is established.

Before removing anything:

- check references;
- understand its purpose;
- establish its replacement;
- evaluate build consequences;
- evaluate deployment consequences.

---

# Phase 3 — Fix `.gitignore` Correctly

Audit ignore rules against the **actual repository**.

Do not replace `.gitignore` with a generic language template without understanding the project.

Consider appropriate rules for:

- generated output;
- build output;
- export output;
- caches;
- test output;
- coverage;
- logs;
- temporary files;
- editor metadata;
- OS metadata;
- local environment files;
- runtime state;
- project-specific generated artifacts.

Prefer the **narrowest useful rule**.

Avoid rules broad enough to hide legitimate source.

Bad cleanup includes:

- ignoring an entire source directory because it is noisy;
- globally ignoring a source-code extension;
- ignoring every unfamiliar file type;
- adding broad wildcards without understanding them;
- using local-only Git exclusions to conceal repository-wide problems.

Inspect nested `.gitignore` files when relevant.

Remove contradictory, obsolete, duplicate, or dangerous rules when justified.

Comment unusual ignore rules only when their purpose is genuinely non-obvious.

---

# Phase 4 — Correct Existing Tracking Mistakes

Remember:

> **`.gitignore` does not stop Git from tracking files that are already committed.**

When a tracked file or directory should actually be local or generated output:

1. verify what it represents;
2. establish reproducibility or non-necessity;
3. inspect consumers;
4. inspect packaging and deployment requirements;
5. add the correct ignore rule;
6. remove it from tracking using a non-destructive method;
7. preserve required local copies;
8. regenerate where appropriate;
9. validate the workflow.

Do not mass-untrack large directories merely because they are noisy.

Every meaningful tracking change requires evidence.

---

# Phase 5 — Remove Repository Clutter

Search for clutter that creates ambiguity, repository bloat, or unnecessary maintenance burden.

Examples:

- huge generated directories;
- committed minified bundles;
- duplicated compiled source;
- old copies of code;
- stale release builds;
- enormous logs;
- database dumps;
- downloaded archives;
- coverage output;
- temporary assets;
- machine-generated metadata;
- abandoned deployment packages;
- obsolete generated resources.

Where safe:

- remove obsolete clutter;
- ignore reproducible local output;
- relocate runtime output away from source where appropriate;
- clarify generated relationships.

Do not delete:

- authoritative source;
- production assets;
- required dependencies;
- irreplaceable user-created assets;
- required deployment material;

merely to reduce repository size.

---

# Phase 6 — Improve Repository Organization Where It Matters

Repository cleanup may include small structural corrections when the current layout actively creates ambiguity.

Look for:

- source inside build directories;
- build output mixed into source;
- runtime files inside source directories;
- ambiguous duplicate directories;
- random dump folders;
- backup directories;
- obsolete project copies;
- miscellaneous root-level clutter;
- scripts with no understandable location;
- documentation scattered without purpose.

Move things only when:

1. the source-of-truth relationship is understood;
2. the destination is clearly better;
3. references can be updated safely;
4. the move materially improves comprehension;
5. validation can confirm the result.

Do not reorganize working code merely because another directory structure looks cleaner.

That belongs in a dedicated architecture or refactoring pass.

---

# Phase 7 — Clarify Repository Source of Truth

A maintainer entering the repository should be able to determine quickly:

- what the repository contains;
- where authoritative source lives;
- which directories are generated;
- which generated files are intentionally committed;
- what should not be manually edited;
- how to build the project;
- how to validate it;
- where runtime or local output belongs.

Inspect existing guidance first:

- README files;
- contributing documentation;
- repository-maintainer guides;
- project-specific development documentation.

Improve the existing authoritative guide rather than creating several competing documents.

If no suitable documentation exists and orientation is genuinely difficult, create one concise repository-level guide.

Useful information may include:

- major applications or packages;
- authoritative source directories;
- generated directories;
- directories not manually edited;
- build commands;
- test commands;
- generation commands;
- local-development commands;
- deployment caveats;
- configuration locations;
- files that should never be committed;
- unusual source/generated relationships.

Keep documentation **compact and high-signal**.

Do not create an architectural novel.

Do not duplicate documentation already maintained correctly elsewhere.

---

# Phase 8 — Reduce Source-of-Truth Noise

Inspect files that make it unnecessarily difficult to identify the real source of the project.

Common offenders include:

- generated source trees;
- minified bundles;
- duplicated compiled output;
- caches;
- huge logs;
- database dumps;
- archives;
- coverage reports;
- old project copies;
- stale generated dependencies;
- machine-generated metadata.

The goal is not simply to shrink the repository.

The goal is to make the distinction clear between:

> **authoritative source**

and:

> **generated / derived / local / irrelevant output**

Do not delete useful material solely because it is large.

Do remove or correctly ignore noise that provides no authoritative value.

---

# Phase 9 — Validate Continuously

Repository cleanup must preserve normal development behavior.

After meaningful cleanup categories, run proportionate validation.

Depending on the project, this may include:

- dependency setup;
- code generation;
- compilation;
- builds;
- type checking;
- linting;
- tests;
- client builds;
- server builds;
- editor or engine validation;
- package builds;
- release builds;
- export builds;
- deployment-related builds;
- validation scripts;
- runtime smoke tests.

Pay particular attention to anything that was:

- removed;
- moved;
- newly ignored;
- untracked;
- reclassified as generated.

If generated output was removed, verify it can actually be regenerated.

If an output directory was newly ignored, verify normal commands recreate it successfully.

Record pre-existing validation failures separately.

Do not attribute an existing failure to this cleanup without evidence.

Treat newly introduced failures as regressions until proven otherwise.

---

# Build-Then-Inspect Test

A particularly important repository-hygiene test is:

1. inspect Git state;
2. run the normal build or generation workflow where practical;
3. inspect Git state again.

Determine whether normal development unexpectedly produces:

- untracked files;
- modified generated files;
- caches;
- logs;
- temporary files;
- runtime state;
- packaging output.

A repository that becomes mysteriously dirty every time it is built is not fully cleaned.

Correct these causes where safe.

---

# Reinspect After the First Cleanup Wave

Do not stop immediately after the first major cleanup.

Reinspect the repository from its new state.

Ask:

- Is unexplained Git noise still present?
- Are generated files still appearing after builds?
- Did validation reveal additional output that should be ignored?
- Are generated/source relationships still ambiguous?
- Are backups, dumps, archives, logs, or caches still mixed into source areas?
- Are tracked local files still present?
- Are ignore rules hiding legitimate source?
- Are nested applications or packages following different unexplained tracking policies?
- Did cleanup expose stale output that is now clearly obsolete?
- Is repository guidance inaccurate?
- Does building the project immediately dirty the repository again?

If worthwhile problems remain:

> **investigate → implement → validate → reinspect**

Continue through progressively smaller worthwhile issues.

Stop when remaining findings are primarily:

- legitimate existing development work;
- low-impact;
- subjective;
- speculative;
- insufficiently supported;
- outside repository-hygiene scope;
- riskier to change than preserve.

Do not invent cleanup simply to create more changes.

The objective is **maximum useful repository improvement**, not maximum churn.

---

# Final Safety Review

After meaningful deletions, untracking, generated-output changes, or structural moves, actively challenge the result.

Check:

- Was legitimate work lost?
- Is legitimate source now ignored?
- Was source incorrectly classified as generated?
- Was generated material incorrectly classified as authoritative source?
- Are `.gitignore` rules too broad?
- Are important artifacts no longer available?
- Can removed generated output actually be recreated?
- Could deployment depend on something that was removed?
- Did repository cleanup unintentionally alter application behavior?
- Does the repository remain buildable?
- Is authoritative source genuinely clearer?
- Did normal workflows begin producing new Git noise?

Repair justified problems before completion.

---

# Final Git-State Review

Inspect Git status at the end.

The target is **not**:

> zero modified files

The target is:

> **every remaining meaningful change is intentional, understandable, and correctly classified.**

Classify remaining:

- modified tracked files;
- staged files;
- deleted files;
- renamed files;
- untracked files;
- important ignored generated/local categories.

Legitimate development work may remain.

That is acceptable.

What should not remain is unexplained noise caused by:

- ignore mistakes;
- generated output;
- caches;
- runtime state;
- build artifacts;
- temporary files;
- accidental copies;
- stale output;
- obsolete clutter;
- incorrect tracking relationships.

A future maintainer should be able to inspect `git status` and quickly understand what it means.

---

# Git History

This task concerns the **current repository and worktree**.

Do not casually:

- rebase unrelated work;
- squash historical commits;
- rewrite branches;
- force-push;
- alter remote history.

If history cleanup is genuinely warranted, report it separately unless explicitly authorized.

---

# Commits

Do not create commits merely to make the repository appear clean unless project instructions explicitly require commits.

If commits are expected:

- keep repository-hygiene changes logically coherent;
- do not mix unrelated pre-existing work into cleanup commits;
- do not commit secrets;
- preserve traceability.

---

# Do Not Turn This Into a Code Refactor

This pass owns:

- Git hygiene;
- tracking;
- ignores;
- generated output;
- build output;
- repository clutter;
- local/runtime files;
- source-of-truth clarity;
- repository navigation;
- developer ergonomics.

Do not start refactoring:

- application architecture;
- UI architecture;
- state management;
- networking;
- database design;
- unrelated technical debt;
- naming;
- formatting;

simply because imperfect code is encountered.

Make the smallest code or configuration change necessary if application behavior itself is causing repository pollution.

Record substantial unrelated issues for another pass.

---

# Completion Standard

The cleanup is complete when:

1. every major category of current Git dirt has been understood;
2. legitimate existing work has been preserved;
3. legitimate untracked source is no longer being mistaken for noise;
4. generated, local, cache, runtime, and build output is intentionally tracked or ignored;
5. incorrectly tracked generated or local files have been corrected safely;
6. obvious obsolete repository clutter has been removed where justified;
7. `.gitignore` reflects the actual repository;
8. ignore rules do not conceal legitimate source;
9. authoritative source versus generated output is clear;
10. normal development and build workflows do not create unnecessary Git noise;
11. relevant generated output can be recreated;
12. repository navigation is clearer;
13. future maintainers can orient themselves quickly;
14. relevant builds, tests, generation, and validation still work apart from documented pre-existing failures;
15. Git status is substantially more understandable;
16. no valuable existing work was discarded;
17. no known regression introduced by cleanup remains;
18. all remaining modifications can be explained.

The objective is not maximum deletion.

The objective is:

> **a repository in which every meaningful file has an understandable reason to exist and an intentional relationship with Git.**

---

# Final Report

When implementation is complete, provide a concise report.

## 1. Overall Result

Summarize the repository's condition before and after the pass.

## 2. Causes of Repository Noise

Explain the major categories discovered.

Use approximate file counts where useful.

## 3. Cleanup Performed

Group meaningful changes into:

- tracking corrections;
- ignore corrections;
- generated-output cleanup;
- cache/runtime cleanup;
- build/distribution cleanup;
- obsolete artifacts;
- structural repository cleanup;
- repository-guidance improvements.

Do not dump long file lists unnecessarily.

## 4. Existing Work Preserved

Mention important pre-existing work intentionally left untouched.

## 5. Source-of-Truth Improvements

Explain important clarification between:

- authoritative source;
- generated output;
- build output;
- local state;
- deployment artifacts.

## 6. Validation

State exactly what was run and the result.

Include relevant regeneration checks.

Distinguish pre-existing failures from newly introduced failures.

## 7. Final Git State

Summarize meaningful remaining:

- modified files;
- staged files;
- deleted or renamed files;
- untracked files;
- intentionally ignored output categories.

Explain why they remain.

## 8. Remaining Repository Issues

List only meaningful repository-hygiene problems intentionally left unresolved and why.

## 9. Out-of-Scope Follow-Up

Briefly record worthwhile findings that belong to another specialized task.

Do not implement them here.

---

# Final Directive

Do not optimize for an aesthetically empty `git status`.

Optimize for a:

> **correct, intentional, low-noise, understandable repository.**

For every meaningful file or category, there should be a defensible answer to:

> **Why is this here?**

> **Should Git track it?**

> **Is this authoritative source, generated output, build output, runtime/local state, dependency material, deployment material, or obsolete clutter?**

Investigate instead of guessing.

Do not destroy legitimate work.

Do not hide problems behind broad ignore rules.

Do not confuse repository hygiene with application refactoring.

Do not stop after the first cleanup wave.

Continue:

> **investigate → classify → implement → validate → reinspect**

while clear, material, safely actionable repository-hygiene work remains.

When complete, another developer should be able to enter the repository, inspect its structure and Git state, quickly identify what is authoritative, understand what is generated or local, run normal workflows without creating mysterious noise, and begin productive work without first untangling hundreds of unexplained files.