# HyperTwist Packet Cleanup And Rebuildable Artifact Hygiene - 2026-05-20

## Status

This document is now the governing HyperTwist cleanup doctrine for packeted
work.

It promotes and broadens earlier partial cleanup guidance that previously
lived in narrower surfaces:

- `C:\HyperTwist\docs\ops\HYPERTWIST_WORKTREE_PLACEMENT_AND_VALIDATION_ARTIFACT_POLICY_2026-05-19.md`
- the embedded worktree and cleanup guidance inside
  `C:\Workspaces\HyperTwist\clean-room-specs\MODEL_OUTPUT_RULES.md`
- the embedded worktree and cleanup guidance inside
  `C:\Workspaces\HyperTwist\clean-room-specs\README.md`
- the embedded worktree and cleanup guidance inside
  `C:\Workspaces\HyperTwist\clean-room-specs\bounded-implementation-workflow.md`

If those documents conflict with this one, this document wins.

Do not weaken any stricter repo-specific or packet-specific rule that is
explicitly documented elsewhere.

Retroactive cleanup-backfill behavior itself is governed by:

- `C:\HyperTwist\docs\ops\HYPERTWIST_RETROACTIVE_AUTHORITY_AND_CLEANUP_BACKFILL_2026-05-20.md`

## Purpose

- make post-packet cleanup an operating doctrine instead of chat memory
- preserve packet truth, authority surfaces, and custody material
- allow aggressive cleanup of rebuildable byproducts only after the packet
  truth is safely recorded
- stop temporary worktrees, validation logs, and rebuildable artifacts from
  quietly accumulating across implementation, validation-unblock, and
  deep-source packets

## Scope

This doctrine applies after packeted work such as:

- bounded implementation
- owner-scoped validation-unblock
- repo-local reconciliation when it produced temporary worktrees or test
  artifacts
- deep source packet evaluation that ran builds, installs, tests, or similar
  local validation
- other packeted work that produced clearly rebuildable byproducts

It is not permission for blind sweeping.

## Core rule

Finish the packet truth first.

Then clean rebuildable byproducts only.

Do not let cleanup destroy:

- authority surfaces
- clean-room handoffs
- staged notes that still carry active packet truth
- logs or reports still needed to write authority updates
- custody mirrors
- reference archives
- plausible user-owned dirty work

Deep-source evaluation must not be weakened merely to avoid local artifact
growth.

## Required cleanup order

1. finish the packet closeout and authority updates
2. keep any required handoff, packet note, commit, or exported evidence that
   the packet still needs
3. remove rebuildable byproducts from the temporary packet root
4. remove the temporary worktree or temporary evaluation clone unless the user
   explicitly asked to keep it or a documented blocker requires temporary
   retention
5. if a registered git worktree was deleted manually, run `git worktree prune`
   from the controlling repo
6. verify git state after cleanup

If cleanup cannot be completed safely, say exactly what was retained and why.

When reporting packet hygiene in conversational closeouts, preserve this same
sequence explicitly:

1. inventory retained non-authority artifacts
2. separate safe-to-delete rebuildables from protected evidence
3. remove only the safe ones
4. report the final hygiene state exactly per doctrine

Do not reorder or collapse those four steps into a vague summary.

## Protected surface classes

### Rebuildable byproducts

These are cleanup targets only when they were created by the packet and are
not themselves authority:

- `.vs`
- `x64`
- Unreal `Binaries`
- Unreal `DerivedDataCache`
- Unreal `Intermediate`
- Unreal `Saved`
- plugin-local `Binaries`
- plugin-local `Intermediate`
- worktree-local `logs`
- worktree-local `Saved/Logs`
- automation report exports
- JSON roundtrip validation artifacts
- packet-local `-AbsLog` outputs
- `target`
- `node_modules`
- `.next`
- `dist`
- `build`
- `out`
- `__pycache__`
- `.pytest_cache`
- `.mypy_cache`
- local virtual environments
- local caches
- other clearly rebuildable validation or build outputs created inside the
  temporary packet root

### Authority surfaces

These are packet-truth surfaces and are not routine cleanup targets:

- packet docs
- `docs`
- `docs/ops`
- `docs/refs`
- clean-room specs and clean-room staged outputs
- canonical CSVs, manifests, ledgers, trackers, and state boards
- clean-room handoffs
- staged reconciliation notes
- already-landed commits carrying packet truth

### Custody mirrors

These remain long-lived provenance surfaces and are not routine cleanup
targets merely because validation ran near them:

- `C:\HyperTwist\mirrors`
- long-lived deep-source custody roots kept for later source inspection or
  license custody

### Reference archives

These are not routine cleanup targets unless the user explicitly asks:

- `zippedreposource`
- reference archives
- root-level research or tutorial assets
- long-lived custody or provenance surfaces

### Plausible user-owned dirty work

Ambiguous dirt in a main worktree is not an automatic cleanup target.

If residue is plausibly user-owned, pre-existing, or not clearly rebuildable,
document it instead of sweeping it.

Files named `TODO.json` are always ignore-only hygiene surfaces unless the user
explicitly asks otherwise.

Treat them as operator or task-manager scratch, not as automatic packet residue
and not as routine cleanup targets.

## Default non-targets

These are not routine cleanup targets unless the user explicitly asks:

- `.git`
- committed source trees
- `C:\HyperTwist\UnrealHyperTwist`
- `C:\HyperTwist\docs`
- `C:\HyperTwist\docs\ops`
- `C:\HyperTwist\mirrors`
- `docs`
- `docs/ops`
- `docs/refs`
- `clean-room-specs`
- `clean-room-specs/outputs`
- `mirrors`
- `TODO.json`
- `zippedreposource`
- reference archives
- root-level research or tutorial assets
- long-lived custody or provenance surfaces
- dirty main worktrees containing pre-existing or ambiguous residue

## Deep source evaluation rule

Deep source packet evaluation is allowed to build, install dependencies, or run
tests when that is needed for serious source-backed judgment.

Do not weaken source evaluation merely to avoid local artifact growth.

After the packet closes:

- keep the packet docs and any required custody pointers
- keep the mirror if it is a named custody surface
- clean rebuildable byproducts created by the evaluation
- remove temporary evaluation clones or temporary evaluation worktrees that are
  no longer needed

Do not casually delete the custody mirror itself merely because validation ran
near it.

## Worktree rule

Default temporary HyperTwist packet worktrees belong under a non-root parent
such as:

- `C:\Workspaces\HyperTwist-worktrees\...`

If that parent is unsuitable, explicitly choose another non-root parent rather
than inventing a new root-level packet folder family.

Do not create new ad hoc root-level packet folders by default.

Preferred cleanup for a registered worktree:

- `git -C <controlling-repo> worktree remove <path>`

If the folder was already deleted manually:

- `git -C <controlling-repo> worktree prune`

## Verification rule

After cleanup:

- verify the controlling repo git status
- verify the workspace repo git status when the packet used the workspace repo
- distinguish packet dirt from pre-existing residue
- do not claim a repo is clean if only the packet dirt was removed but
  pre-existing residue remains

## Closeout rule

Packet closeouts must say, at minimum:

- what temporary packet root was used, or that no temporary packet root was
  used
- whether that temporary root was removed
- what artifacts were intentionally retained
- what cleanup could not be completed and why

That statement may be compact, but it must not be omitted.

Compact reporting is preferred when the hygiene state is routine:

- keep the implementation result, validation outcome, and next best move ahead
  of extended hygiene detail
- summarize retained non-authority artifact classes compactly unless a
  specific path or size is operationally important
- do not let repetitive rebuildable-path inventories dominate the closeout
  when the key packet truth is the landed phase result and validated next seam
- do not omit important phase implementation info, validation status, or the
  next deliberate roadmap move merely to save space on hygiene reporting

## Cleanup cadence

Cleanup is mandatory:

- after each completed normalized deep-source pack of `5` repos or equivalent
  `0R` batch
- after any bounded implementation, validation-unblock, or repo-local
  reconciliation packet that created a temporary worktree or substantial
  rebuildable byproducts, unless a documented blocker requires temporary
  retention

Earlier cleanup is also allowed when free-space pressure or local artifact
growth requires an emergency pass.

## Older-doc ambiguity rule

Do not silently reinterpret older packet behavior.

If an older HyperTwist packet or workflow doc is ambiguous about:

- what temporary root was used
- whether cleanup happened
- whether retained residue was intentional
- whether dirt is packet-created or pre-existing

mark that gap explicitly and backfill it selectively when the older surface is
still operationally relied on.

Do not invent certainty from memory.

Required retroactive cleanup rule:

- do not do fake whole-corpus rewrites
- do not do blind full resets
- the correct target is the relied-on ambiguity, not blanket relabeling
- cleanup backfill is comparative and operational, not cosmetic
- name the exact earlier packet, standing note, or workflow doc reopened
- state whether cleanup interpretation changed or only wording changed

## Relationship to active doctrine

This document is the HyperTwist-local cleanup authority referenced by:

- `C:\HyperTwist\docs\ops\HYPERTWIST_WORKTREE_PLACEMENT_AND_VALIDATION_ARTIFACT_POLICY_2026-05-19.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_RETROACTIVE_AUTHORITY_AND_CLEANUP_BACKFILL_2026-05-20.md`
- `C:\HyperTwist\docs\HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md`
- `C:\Workspaces\HyperTwist\clean-room-specs\MODEL_OUTPUT_RULES.md`
- `C:\Workspaces\HyperTwist\clean-room-specs\README.md`
- `C:\Workspaces\HyperTwist\clean-room-specs\bounded-implementation-workflow.md`
- `C:\Workspaces\HyperTwist\clean-room-specs\GENERIC_OPERATOR_SEQUENCE_AND_PROMPTING.md`
- `C:\Workspaces\HyperTwist\clean-room-specs\0600-phase5r-clean-room-operator-sequence-and-handoff.md`
- `C:\Workspaces\HyperTwist\clean-room-specs\0500-phase5r-restrictive-lanes.model-b-consolidation-prompt.md`
