From 8b5be740fa4c4df87b0e4167aa583dc484dc28a4 Mon Sep 17 00:00:00 2001 From: axiomlogicnexus Date: Wed, 20 May 2026 01:29:59 +0200 Subject: [PATCH] Backfill cross-lane authority and cleanup doctrine --- ...UE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md | 18 + ...MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md | 58 +++- ...ICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md | 17 + ...HIERARCHY_AND_RECONCILIATION_2026-05-20.md | 328 ++++++++++++++++++ ...REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md | 197 ++++++++--- ...D_VALIDATION_ARTIFACT_POLICY_2026-05-19.md | 6 +- 6 files changed, 580 insertions(+), 44 deletions(-) create mode 100644 docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md diff --git a/docs/HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md b/docs/HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md index e877b7e..06aa296 100644 --- a/docs/HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md +++ b/docs/HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md @@ -89,6 +89,19 @@ That means: The canonical anti-conflation doctrine now also lives in: - [HYPERTWIST_REPO_INTAKE_RETENTION_AND_PRODUCT_FIT_DOCTRINE_2026-05-14.md](C:/HyperTwist/docs/HYPERTWIST_REPO_INTAKE_RETENTION_AND_PRODUCT_FIT_DOCTRINE_2026-05-14.md:1) +- [HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md](C:/HyperTwist/docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md:1) + +Cross-lane authority note: + +- when multiple retained repos compete for one slice, `Model A` should resolve + that slice under the dedicated HyperTwist `A/R/F` authority doctrine +- capability hierarchy is license-neutral +- license posture changes route, not rank +- if the retained winner is restrictive, the consequence is clean-room, + boundary-first, or oracle-only routing rather than authority demotion +- do not compare whole repos when the real overlap is subsystem-specific +- preserve unique non-overlapping value from non-winners explicitly as adjunct, + reference, or pattern value instead of flattening it to exclusion ## Core doctrine @@ -368,6 +381,11 @@ Use the HyperTwist docs this way: - canonical closeout section order - mandatory Result taxonomy - compactness-without-information-loss rule +- `docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md`: + - license-neutral `A/R/F` hierarchy model + - slice decomposition before authority ranking + - selective retroactive backfill when a later same-family repo materially + changes an earlier contested-slice authority call - `docs/ops/HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md`: - post-packet cleanup order - rebuildable-artifact rule diff --git a/docs/HYPERTWIST_MODEL_A_MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md b/docs/HYPERTWIST_MODEL_A_MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md index 7dbbb65..b43ce75 100644 --- a/docs/HYPERTWIST_MODEL_A_MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md +++ b/docs/HYPERTWIST_MODEL_A_MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md @@ -11,6 +11,8 @@ It is the HyperTwist-local coordinator counterpart to: - [HYPERTWIST_REPO_INTAKE_RETENTION_AND_PRODUCT_FIT_DOCTRINE_2026-05-14.md](C:/HyperTwist/docs/HYPERTWIST_REPO_INTAKE_RETENTION_AND_PRODUCT_FIT_DOCTRINE_2026-05-14.md:1) - [HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md](C:/HyperTwist/docs/HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md:1) +- [HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md](C:/HyperTwist/docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md:1) +- [HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md](C:/HyperTwist/docs/ops/HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md:1) - [MODEL_B_SOURCE_ACCESS_BOUNDARY.md](C:/HyperTwist/docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md:1) ## Purpose @@ -92,6 +94,15 @@ Decide in this order: Harder route does not mean weaker donor. +Use the governing three-axis authority document when overlap is real: + +- `A` = capability authority tier +- `R` = execution route +- `F` = realization width + +Do not leave contested-slice authority in vague “stronger donor” prose when +it must be resolved precisely. + ### 6. Implementation requires explicit authority Treat a repo as implementation-authorized only when a bounded implementation @@ -122,8 +133,51 @@ When coordinating repo judgment or widening, use this order: 5. repo-specific packet authority docs 6. [HYPERTWIST_PHASE_1R_RETAINED_SET_CONTRACT_AND_HANDOFF_2026-05-13.md](C:/HyperTwist/docs/HYPERTWIST_PHASE_1R_RETAINED_SET_CONTRACT_AND_HANDOFF_2026-05-13.md:1) 7. [HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md](C:/HyperTwist/docs/HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md:1) -8. [REPO_LICENSE_TRACKING.md](C:/HyperTwist/docs/REPO_LICENSE_TRACKING.md:1) -9. [MODEL_B_SOURCE_ACCESS_BOUNDARY.md](C:/HyperTwist/docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md:1) when clean-room-sensitive work is involved +8. [HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md](C:/HyperTwist/docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md:1) +9. [REPO_LICENSE_TRACKING.md](C:/HyperTwist/docs/REPO_LICENSE_TRACKING.md:1) +10. [MODEL_B_SOURCE_ACCESS_BOUNDARY.md](C:/HyperTwist/docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md:1) when clean-room-sensitive work is involved + +## Cross-lane authority rule + +When multiple repos compete for the same retained slice: + +- capability hierarchy is license-neutral +- license posture affects route, not rank +- decompose the overlap into slices before assigning authority +- assign one `A1` per contested slice and preserve secondary non-overlapping + value from non-winners explicitly as `A2`, `A3`, or `A4` +- do not force whole-repo winner-take-all when the real overlap is + subsystem-specific +- if a later same-family repo materially changes an earlier contested-slice + authority call, reopen the earlier affected packet selectively instead of + pretending the whole corpus needs a rewrite + +For coordination that resolves real overlap, require the packet or standing +note to state: + +- exact contested slice +- candidate repos considered +- `A` tier per candidate +- `R` route per candidate where relevant +- `F` class for the retained winner +- preserved secondary value +- non-promoted families + +## Cleanup coordination rule + +Packet cleanup and worktree hygiene are governed by: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md` + +Required coordinator behavior: + +- finish packet truth first +- then clean rebuildable byproducts only +- do not weaken deep-source evaluation merely to avoid artifact growth +- do not claim a repo is clean if only packet dirt was removed but + pre-existing residue remains +- if an older operationally relied-on packet is cleanup-ambiguous, mark it for + selective backfill instead of inventing certainty ## Model A / Model B split diff --git a/docs/ops/HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md b/docs/ops/HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md index 80ad29c..831b570 100644 --- a/docs/ops/HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md +++ b/docs/ops/HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md @@ -57,6 +57,21 @@ When a narrower bounded slice is chosen: Do not leave that taxonomy implicit in general prose. +If a packet resolved, reused, or materially changed a contested slice +authority call, `Result` or `Why that call` must also surface: + +- exact contested slice +- candidate repos considered or standing candidates reused +- `A` tier per candidate for that slice +- `R` route for the retained winner where relevant +- `F` class for the retained winner +- preserved secondary value from non-winners +- exact non-promoted families + +Route that overlap language through: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md` + ## Compactness rule Compactness is allowed. Information loss is not. @@ -102,6 +117,8 @@ This closeout doctrine is the HyperTwist-local reference target for: - `C:\HyperTwist\docs\HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md` - `C:\HyperTwist\docs\HYPERTWIST_REPO_INTAKE_RETENTION_AND_PRODUCT_FIT_DOCTRINE_2026-05-14.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md` - `C:\Workspaces\HyperTwist\clean-room-specs\MODEL_OUTPUT_RULES.md` - `C:\Workspaces\HyperTwist\clean-room-specs\README.md` - repo-specific clean-room prompt-sequence and bounded-implementation prompt diff --git a/docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md b/docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md new file mode 100644 index 0000000..9cf3171 --- /dev/null +++ b/docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md @@ -0,0 +1,328 @@ +# HyperTwist Cross-Lane Authority Hierarchy And Reconciliation - 2026-05-20 + +## Status + +This document is now the governing HyperTwist authority doctrine for +cross-lane overlap, contested retained slices, and targeted reconciliation. + +If a looser prompt, packet, or standing note conflicts with this document on +authority ranking, execution routing, realization width, or selective +retroactive backfill, this document wins. + +## Purpose + +This document defines the mature decision model for cross-lane discrepancies +when two or more repos compete for the same retained capability slice. + +Its job is to keep three separate questions from being blended together: + +1. which repo is strongest for the slice +2. how that slice must be implemented +3. how much of that winning slice should actually be realized in HyperTwist + +Those are separate questions. + +## Core correction + +Capability hierarchy is license-neutral. + +License posture must not decide which repo is primary authority for a retained +slice. + +License posture decides execution route only. + +So the order is: + +1. determine the strongest slice authority on capability grounds +2. preserve secondary non-overlapping value from the other candidates +3. only then decide whether implementation is direct, boundary-first, + clean-room, oracle-only, or excluded + +If the strongest repo for a slice is restrictive, mixed, no-license, or +otherwise unsuitable for ordinary direct incorporation, it still remains the +highest capability authority for that slice. + +The consequence is not demotion. + +The consequence is boundary-first, clean-room, or oracle-only routing. + +## Three-axis model + +Every meaningful overlap decision must separate three axes. + +### Axis A - capability authority tier + +This is the hierarchy axis. + +Use these slice-local tiers: + +- `A1` - primary slice authority + - the strongest source-backed owner for the retained slice +- `A2` - adjunct donor + - not the primary owner, but still carries unique non-overlapping value that + must be preserved +- `A3` - reference authority + - useful for understanding, operator expectations, examples, or checks, but + not selected as implementation owner +- `A4` - pattern authority + - useful only for architectural patterns or heuristics, not for direct + retained ownership +- `A5` - excluded + - no retained value in the current horizon for the relevant slice + +`A1` is decided per slice, not per repo globally. + +Do not force whole-repo winner-take-all decisions when the source reality is +subsystem-specific. + +### Axis R - execution route + +This is not hierarchy. + +This is the implementation-routing axis. + +Use: + +- `R1` - direct first-party incorporation or vendored integration is allowed +- `R2` - boundary-first adapter, sidecar, or isolated integration route +- `R3` - clean-room implementation route from a restrictive or otherwise + unsafe donor +- `R4` - oracle-only or correctness-reference route +- `R5` - no implementation route in the current horizon + +Rule: + +- `A1` does not imply `R1` +- a slice can be `A1 + R3` +- that means it is the best authority, but implementation must be first-party + clean-room + +### Axis F - realization width + +This is the scope-width axis. + +Use: + +- `F1` - full bounded capability realization +- `F2` - narrower bounded slice + +Rule: + +- `A1` does not imply `F1` +- a slice can be `A1 + R1 + F2` +- or `A1 + R3 + F2` + +That means it is the best authority, but HyperTwist still intentionally takes +only the narrower bounded part. + +## Mandatory comparison scaffolds + +### Scaffold 1 - slice decomposition + +Before comparing repos, break the overlap into named slices. + +Never compare entire repos when the real competition is only one subsystem. + +If two repos only appear to overlap because the slice was defined too broadly, +refine the slice before ranking. + +### Scaffold 2 - capability comparison matrix + +For each candidate repo and each contested slice, compare on: + +1. slice completeness +2. source-backed correctness or maturity +3. validation evidence +4. composability +5. operator quality +6. unique retained value +7. boundary cleanliness + +Do not compare on license here. + +License is handled later under Axis `R`. + +### Scaffold 3 - authority resolution + +After the comparison matrix: + +- assign one `A1` per contested slice +- assign `A2` to any candidate with non-overlapping retained value that must + survive +- assign `A3` or `A4` where only reference or pattern value survives +- assign `A5` only when the slice truly adds no retained value in the current + horizon + +Default bias: + +- preserve secondary unique value +- do not collapse a losing candidate to `A5` if it still offers unique + operator, fixture, protocol, adjunct, or neighboring-slice value + +### Scaffold 4 - execution routing + +Only after `A1` is known, assign `R`. + +This is the exact point where license posture matters. + +It matters to route. + +It does not matter to hierarchy. + +### Scaffold 5 - realization width + +For the `A1` winner, decide whether the retained return is `F1` or `F2`. + +If `F2`, name: + +- the exact promoted sub-slice +- the exact families not being promoted +- which secondary repo, if any, remains the best adjunct, reference, or + pattern authority for the non-promoted remainder + +## Decision rules + +### Rule 1 - best capability wins + +The strongest source-backed slice wins `A1`. + +Not the easiest license. + +Not the easiest integration. + +Not the most convenient current worktree. + +### Rule 2 - license affects route, not rank + +If a restrictive repo is strongest for the slice: + +- it still gets `A1` +- its route becomes `R3` or `R4` +- implementation becomes clean-room or oracle-routed as appropriate + +### Rule 3 - preserve secondary value explicitly + +If repo `X` wins `A1` for a slice and repo `Y` still has unique value: + +- `Y` becomes `A2`, `A3`, or `A4` +- the packet must say exactly what survives from `Y` +- that value must not disappear merely because `X` won primary ownership + +### Rule 4 - split coarse overlaps into sub-slices + +If each repo is stronger at different sub-parts of an apparent overlap, do not +force a false single winner. + +Instead: + +- split the slice +- assign separate `A1` owners +- reconcile only the real contract between them + +### Rule 5 - avoid mushy co-ownership + +Do not default to “both own it.” + +If the overlap is real, assign: + +- one `A1` +- one or more `A2` or `A3` or `A4` + +Only use effectively shared authority when the slice is still too coarse and +must be decomposed further. + +### Rule 6 - tie-break with capability evidence, not license + +If two candidates look close, tie-break in this order: + +1. stronger slice completeness +2. stronger source-backed correctness or validation evidence +3. cleaner subsystem boundary and composability +4. stronger unique operator or workflow value +5. stronger retained adjunct coverage across neighboring slices + +If still unresolved, do not force certainty. + +Mark it as requiring targeted cross-lane reconciliation or deeper validation. + +## Required packet outputs when overlap exists + +When a repo packet or cross-lane checkpoint touches a real overlap, it must +name: + +- exact contested slice +- candidate repos considered +- `A` tier per candidate for that slice +- `R` route per candidate where relevant +- `F` class for the retained winner if implementation is plausible +- primary winner rationale +- secondary preserved value from non-winners +- exact non-promoted families +- whether further targeted cross-lane reconciliation is required + +## Required closeout behavior + +If a closeout references a repo whose retained slice competes with another +retained repo, the closeout should surface: + +- who is `A1` for the contested slice +- what survives as `A2` or `A3` or `A4` +- whether the execution route is `R1`, `R2`, `R3`, `R4`, or `R5` +- whether the realization width is `F1` or `F2` + +Do not hide the real winner behind generic donor prose when authority was +actually resolved. + +## Targeted cross-lane checkpoint trigger + +Open a targeted cross-lane reconciliation pass only when one of these is true: + +- the `A1` owner is still unresolved after slice decomposition +- the slice boundary is clear, but the API, protocol, semantic, or persistence + contract between adjacent winners is unresolved +- two prior packets contradict each other about the same contested slice +- the next implementation bound would otherwise silently widen into a + neighboring owner surface + +Do not open the checkpoint merely because: + +- two repos look similar at README level +- one repo is restrictive +- the losing repo still has preserved adjunct value + +## Relationship to existing doctrine + +This document extends, but does not replace: + +- `C:\HyperTwist\docs\HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md` +- `C:\HyperTwist\docs\HYPERTWIST_MODEL_A_MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.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` + +## Retroactive backfill rule + +Older packets do not all need full re-evaluation. + +Backfill in this order: + +1. packets or summary surfaces where contested ownership was stated only + loosely +2. packets where the current winner, adjunct, reference, or pattern split is + ambiguous +3. packets where a restrictive repo may actually be the higher capability + authority but was previously described too defensively +4. earlier same-family packets whose contested-slice authority call is + materially changed by a later same-family repo or later reconciliation pass + +Do not rewrite older packets just to paraphrase them. + +Backfill only where the hierarchy model materially changes interpretation, +implementation routing, or checkpoint gating. + +Do not invent certainty for older ambiguous packets. diff --git a/docs/ops/HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md b/docs/ops/HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md index 4e8b592..4966111 100644 --- a/docs/ops/HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md +++ b/docs/ops/HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md @@ -1,27 +1,47 @@ -# HyperTwist Packet Cleanup And Rebuildable Artifact Hygiene +# HyperTwist Packet Cleanup And Rebuildable Artifact Hygiene - 2026-05-20 -Created on `2026-05-20`. +## Status -Purpose: +This document is now the governing HyperTwist cleanup doctrine for packeted +work. -- define the default cleanup rule after bounded implementation packets, - validation-unblock packets, deep source packet evaluation, and similar - packeted work -- reduce stale build outputs, temporary worktrees, and disposable validation - byproducts without deleting authority surfaces or custody material -- make post-packet cleanup a doctrine step rather than operator memory +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. + +## 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 rule applies after packeted work such as: +This doctrine applies after packeted work such as: - bounded implementation - owner-scoped validation-unblock -- repo-local reconciliation when it generated temporary worktrees or test +- repo-local reconciliation when it produced temporary worktrees or test artifacts -- deep source packet evaluation that ran builds, installs, tests, or other +- deep source packet evaluation that ran builds, installs, tests, or similar local validation -- other packeted work that created clearly rebuildable byproducts +- other packeted work that produced clearly rebuildable byproducts It is not permission for blind sweeping. @@ -33,31 +53,37 @@ Then clean rebuildable byproducts only. Do not let cleanup destroy: -- packet docs +- authority surfaces - clean-room handoffs -- staged notes -- logs or reports that are still needed to write authority updates +- 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 clean-room handoff, packet note, commit, or exported - evidence that the packet still needs +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 - asked to keep it or a documented blocker requires temporary retention + 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 what was retained and why. +If cleanup cannot be completed safely, say exactly what was retained and why. -## Default rebuildable cleanup classes +## Protected surface classes -These are normally cleanup targets when they were created by the packet and are +### Rebuildable byproducts + +These are cleanup targets only when they were created by the packet and are not themselves authority: - `.vs` @@ -73,23 +99,58 @@ not themselves authority: - automation report exports - JSON roundtrip validation artifacts - packet-local `-AbsLog` outputs -- other clearly rebuildable validation or build outputs created inside the - temporary packet root - -For non-Unreal packet roots, the same rule applies to equivalent rebuildable -outputs such as: - -- `node_modules` - `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 -Only clean those when they were created for the packet and are not being kept -as authority. +### 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. ## Default non-targets @@ -97,6 +158,10 @@ 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` @@ -107,12 +172,14 @@ These are not routine cleanup targets unless the user explicitly asks: - reference archives - root-level research or tutorial assets - long-lived custody or provenance surfaces -- the dirty main worktree when it contains pre-existing or ambiguous residue +- 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 a serious source-backed judgment. +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: @@ -127,12 +194,15 @@ near it. ## Worktree rule -Default temporary HyperTwist packet worktrees belong under: +Default temporary HyperTwist packet worktrees belong under a non-root parent +such as: - `C:\Workspaces\HyperTwist-worktrees\...` -Do not create new ad hoc root-level packet folders such as `C:\HTB*` unless the -user explicitly approves that exact placement. +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: @@ -148,15 +218,62 @@ After cleanup: - verify the controlling repo git status - verify the workspace repo git status when the packet used the workspace repo -- if dirty state remains, distinguish packet dirt from pre-existing residue +- 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 should say, at minimum: +Packet closeouts must say, at minimum: -- what temporary packet root was used -- whether it was removed +- 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. + +## 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. + +## 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\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` diff --git a/docs/ops/HYPERTWIST_WORKTREE_PLACEMENT_AND_VALIDATION_ARTIFACT_POLICY_2026-05-19.md b/docs/ops/HYPERTWIST_WORKTREE_PLACEMENT_AND_VALIDATION_ARTIFACT_POLICY_2026-05-19.md index 60516df..da3f26f 100644 --- a/docs/ops/HYPERTWIST_WORKTREE_PLACEMENT_AND_VALIDATION_ARTIFACT_POLICY_2026-05-19.md +++ b/docs/ops/HYPERTWIST_WORKTREE_PLACEMENT_AND_VALIDATION_ARTIFACT_POLICY_2026-05-19.md @@ -11,9 +11,11 @@ Purpose: Relationship note: -- this document is the worktree-focused subset of the broader cleanup doctrine - in +- this document is a subordinate worktree-focused mirror of the broader + governing cleanup doctrine in `C:\HyperTwist\docs\ops\HYPERTWIST_PACKET_CLEANUP_AND_REBUILDABLE_ARTIFACT_HYGIENE_2026-05-20.md` +- if this document conflicts with the broader cleanup doctrine, the broader + cleanup doctrine wins - use the broader doctrine for deep source packet evaluation and other packet types that generate rebuildable artifacts outside bounded implementation