hypertwist/docs/EXTERNAL_MIRROR_WORKSPACE_AND_SUBMODULE_HANDOFF.md

External Mirror Workspace And Submodule Handoff

Created on 2026-04-23

Purpose

This document defines the operating model for large repository fleets across:

• C:\ScriptoriumAI
• C:\HyperTwist
• C:\VectorShell

The goal is to keep:

• first-party product repos clean
• external research mirrors discoverable
• restrictive-source custody legally defensible
• clean-room handoff repeatable across sessions and models

This document is intentionally written as a handoff artifact, not just a local memo. Another model or operator should be able to pick it up later and understand:

• where mirrors live
• which mirrors are safe for direct donor work
• which mirrors are Model A only
• where scrubbed clean-room artifacts belong
• where Model B implementation work is allowed to happen

Related boundary document:

• for explicit clean-room Model B source restrictions, also read docs/MODEL_B_SOURCE_ACCESS_BOUNDARY.md

Core decision

Do not place large mirror fleets inside the main product repos.

That creates avoidable problems:

• nested Git complexity
• slower backup and sync behavior
• noisy file watchers
• heavier IDE indexing
• larger .vs state
• harder solution and agent-context management
• slower global search over mixed first-party and third-party trees
• weaker legal separation for restrictive-source work

Instead, use one external workspace root per product.

Current safe setup

The live repos remain where they are today:

• C:\ScriptoriumAI
• C:\HyperTwist
• C:\VectorShell

The external workspace scaffold exists separately under:

• C:\Workspaces\ScriptoriumAI
• C:\Workspaces\HyperTwist
• C:\Workspaces\VectorShell

This is deliberate.

Important constraint:

• the live repos were not moved into app\ yet
• app\ remains a documented future migration target
• generated artifacts point to the current live repo paths unless and until an explicit migration is approved

Why the workspace model now needs a custody split

A simple external mirrors\ folder is not enough once restrictive repos enter the process.

Two different workflows must be kept separate:

1. Direct donor or normal source-audit work
2. Restrictive-source clean-room or benchmark-oracle work

If both workflows share the same undifferentiated mirror area, later handoff becomes ambiguous.

That ambiguity is exactly what causes trouble when:

• a GPL repo is mistaken for a donor
• an all-rights-reserved repo is later seen by an implementation model
• a no-license repo is treated as if mirroring alone made it reusable
• a benchmark solver is confused with a clean-room implementation target

The workspace therefore now needs explicit separation between:

• permissive mirrors
• restrictive mirrors
• scrubbed clean-room handoff artifacts
• isolated implementation workspaces

Folder model

Each product workspace now follows this structure:

C:\Workspaces\<Product>\
  app\                          <- reserved future landing zone for the first-party repo
  mirrors\
    permissive\                <- MIT / Apache / BSD / acceptable donor mirrors
    restrictive\               <- GPL / no-license / all-rights-reserved mirrors
  clean-room-specs\            <- scrubbed Model A outputs safe for Model B handoff
  implementation-workspaces\
    model-b\                   <- isolated implementation area; must not read restrictive mirrors
    scratch\                   <- temporary safe experiments that are not authoritative
  generated\                   <- generated solutions and solution filters
  cache\                       <- clone cache, bare mirrors, temp sync state, generated lookup data
  repos.manifest.json
  README.md
  .gitignore

Meaning of each root

app\

This is a future migration target only.

Current rule:

• do not move the live repo here implicitly
• do not treat its existence as proof that migration has already happened

mirrors\permissive\

Use this root for repos that are currently acceptable for normal source reading and donor evaluation, such as:

• MIT
• Apache-2.0
• BSD
• dual-permissive combinations

These mirrors may support:

• code-level donor review
• direct integration analysis
• adapter planning
• ordinary implementation work if the final legal posture remains acceptable

mirrors\restrictive\

Use this root for repos that are not safe for ordinary code-reuse workflows, such as:

• GPL / AGPL / LGPL where direct use is not intended
• no-license repos
• all-rights-reserved repos
• any repo with unresolved or contested licensing

Critical rule:

• this root is Model A only
• a clean-room Model B must not read source from here

clean-room-specs\

This root is the safe handoff zone between exposed and unexposed work.

Expected contents:

• scrubbed behavior specifications
• black-box architecture notes
• acceptance tests
• no-copy guardrails
• benchmark-oracle usage notes

This root is what Model B may safely consume.

implementation-workspaces\model-b\

This is the isolated clean-room implementation surface.

Rules:

• do not clone restrictive mirrors here
• do not mount restrictive paths here
• do not use a session that already read restrictive source here
• use only scrubbed handoff artifacts from clean-room-specs\

implementation-workspaces\scratch\

Use this for:

• temporary experiments
• local validation harnesses
• rough working notes

Do not treat it as long-term source of truth.

Manifest control plane

Each workspace root contains:

• repos.manifest.json

This file is the control plane for:

• repository inventory
• mirror class
• workflow role
• legal posture
• source exposure rules
• generated solution artifacts

Ad hoc clone folders are not the authority.

The manifest is.

Current governance correction note

The roadmap-expansion source-exposed audit added one important operating warning:

• mirror separation is in place
• clean-room handoff discipline is in place
• but manifest parity can still lag behind actual active restrictive lanes

Current HyperTwist examples that should be kept visible in governance discussions:

• kash/cubedesk
• onionhoney/roux-trainers
• cs0x7f/cstimer
• efrantar/rob-twophase

Implication:

• the mirror workspace can be legally and operationally well-structured while still suffering from control-plane drift if active restrictive mirrors are not represented consistently enough in repos.manifest.json

Practical rule:

• when a restrictive mirror becomes:
  • an active clean-room candidate
  • an active benchmark oracle
  • or a roadmap-visible future lane
• update the manifest and the governance docs together rather than relying on mirror presence alone

2026-05-11 HyperTwist implementation-truth correction

For HyperTwist specifically, the mirror/handoff model must now carry one additional explicit truth:

• current curated shallow-eval set: 71 repos
• currently verified live in checked UnrealHyperTwist surfaces: 14
• permissive live lanes: 13
• restrictive live lane: 1
• the restrictive live lane is onionhoney/roux-trainers
• that lane is to be treated as properly clean-roomed and then implemented
• Phase 0R is now closed for the remaining 57 non-live rows
• Phase 1R is now closed as the retained-set contract and handoff layer
• the fourteen already-live rows now also have a dedicated source-backed preservation authority doc
• Phase 2R-A is now closed as the core ownership and acceptance authority for the five retained permissive anchor rows
• Phase 2R-B is now closed as the support-plane ownership and acceptance authority for the retained permissive support rows in scope
• Phase 2R-C is now closed as the residual adjunct and alternative-support ownership and acceptance authority for the final retained permissive 0R-B rows
• the current manifest and doc control plane should now distinguish:
  • 45 non-live active implementation-board rows
  • 9 retained benchmark/oracle/clean-room-later rows outside the active implementation board
  • 3 discarded active-set rows

Operational implication:

• manifest presence and selected status never equal implementation truth
• future handoffs must keep three states visibly separate:
  • landed/live now
  • selected/queued but not live
  • benchmark or reserve

Reset rule:

• do not reopen Phase 0R
• before new donor-shaped widening for HyperTwist, read:
  • docs/HYPERTWIST_LIVE_LANES_SOURCE_AND_PRESERVATION_AUDIT_2026-05-13.md for the fourteen already-live lanes
  • docs/HYPERTWIST_PHASE_1R_RETAINED_SET_CONTRACT_AND_HANDOFF_2026-05-13.md for routing
  • docs/HYPERTWIST_PHASE_2R_PACKET_2R_A_OWNERSHIP_AND_ACCEPTANCE_CONTRACT_2026-05-13.md for the five retained core permissive rows
  • docs/HYPERTWIST_PHASE_2R_PACKET_2R_B_OWNERSHIP_AND_ACCEPTANCE_CONTRACT_2026-05-13.md for the retained permissive support-plane rows in scope
  • docs/HYPERTWIST_PHASE_2R_PACKET_2R_C_OWNERSHIP_AND_ACCEPTANCE_CONTRACT_2026-05-13.md for the final retained permissive 0R-B adjunct and alternative-support rows
  • docs/HYPERTWIST_PHASE_3R_PACKET_3R_C_ECHARTS_IMPLEMENTATION_2026-05-13.md before widening the landed analytics/reporting lane again
  • docs/HYPERTWIST_PHASE_3R_PACKET_3R_D_MODEL_VIEWER_IMPLEMENTATION_2026-05-13.md before widening the landed browser presentation and asset-QA lane again
  • docs/HYPERTWIST_PHASE_3R_PACKET_3R_F_BROWSER_SPATIAL_SUPPORT_IMPLEMENTATION_2026-05-13.md before widening the landed browser spatial owner trio again
  • the relevant 0R-* packet for any non-live retained row

Manifest schema

Current schema version:

• 2

Top-level structure:

{
  "schemaVersion": 2,
  "productName": "HyperTwist",
  "generatedAtUtc": "...",
  "workspace": {
    "workspaceRoot": "...",
    "currentAppRoot": "...",
    "plannedAppRoot": "...",
    "mirrorsRoot": "...",
    "permissiveMirrorsRoot": "...",
    "restrictiveMirrorsRoot": "...",
    "cleanRoomSpecsRoot": "...",
    "implementationWorkspacesRoot": "...",
    "modelBWorkspacesRoot": "...",
    "scratchWorkspacesRoot": "...",
    "generatedRoot": "...",
    "cacheRoot": "..."
  },
  "policy": {
    "defaultIncludeMode": "root",
    "restrictiveMirrorsModelAOnly": true,
    "modelBMayReadRestrictiveMirrors": false,
    "benchmarkOracleDefaultUsage": "...",
    "cleanRoomDefaultUsage": "..."
  },
  "repositories": [
    {
      "key": "...",
      "name": "...",
      "repoUrl": "...",
      "localPath": "...",
      "purpose": "...",
      "language": "...",
      "includeMode": "root",
      "storage": "external-mirror",
      "license": "...",
      "licenseStatus": "...",
      "mirrorClass": "permissive|restrictive|in-repo|app-repo",
      "workflowRole": "...",
      "modelAAllowedSourceAccess": true,
      "modelBAllowedSourceAccess": false,
      "handoffDoc": "...",
      "notes": []
    }
  ]
}

Repository fields that matter operationally

storage

Allowed meanings:

• app-repo
• submodule
• external-mirror

mirrorClass

Allowed meanings:

• app-repo
• in-repo
• permissive
• restrictive

workflowRole

Examples:

• first-party
• pinned-dependency
• foundation-donor
• parallel-foundation-donor
• strategic-donor
• focused-donor
• training-bench
• reference-donor
• reference-only
• clean-room-candidate
• benchmark-oracle

These roles are operational and architectural. They are not just labels.

modelAAllowedSourceAccess

This answers:

• may the exposed analysis side read this source directly?

modelBAllowedSourceAccess

This answers:

• may the isolated implementation side read this source directly?

For restrictive mirrors, this should be:

• false

handoffDoc

Use this for:

• repo-specific clean-room dossier
• benchmark-oracle guidance
• or any durable handoff note another model should read before touching the repo’s outputs

Operational rule:

• for restrictive mirrors, handoffDoc should point to a workspace-safe file under clean-room-specs\
• do not point handoffDoc at raw exposed-side research notes if those notes contain source breadcrumbs, protected file paths, or other Model A-only material
• raw parse folders may remain useful for exposed-side continuity, but the manifest should direct later implementation work to the scrubbed handoff zone instead

Generated artifacts

Each workspace writes:

• generated\main.sln
• generated\catalog.sln
• generated\active.slnf

main.sln

Purpose:

• first-party code
• current app projects
• active pinned integrations represented as lightweight folders when they are not directly loadable projects

catalog.sln

Purpose:

• high-level discoverability
• workspace config visibility
• permissive and restrictive mirror group visibility
• clean-room handoff doc visibility

This is intentionally light. It is not a promise that every mirror is safe to open or edit casually.

active.slnf

Purpose:

• fast working-set entry point
• points to main.sln
• limits the default IDE surface to the current core projects

Submodule policy

Submodules are still valid, but only for mirrors that truly need to stay pinned inside the product repo.

Keep submodules when all of these are true:

• the product depends on the mirror by path
• the revision must stay pinned in the main repo
• CI or deployment needs the repo to exist inside the product tree

Do not use submodules as a substitute for the external workspace.

Practical consequences of submodules

• the parent repo stores a commit pointer, not the contents directly
• clone and bootstrap require submodule initialization
• editing happens inside the submodule repo first, then the parent repo records the new SHA

Useful commands:

git clone --recurse-submodules <repo>
git submodule sync --recursive
git submodule update --init --recursive

External mirror policy

Use external mirrors for:

• large repo intake queues
• research and evaluation mirrors
• repos that are visible but not actively edited
• repos that should not bloat the product repo
• restrictive-source custody
• benchmark-oracle custody

Mirror repos by:

• owner
• repo

Example:

C:\Workspaces\HyperTwist\mirrors\permissive\HactarCE\Hyperspeedcube
C:\Workspaces\HyperTwist\mirrors\restrictive\AviKaufman\Rubix-cube-trainer

Benchmark oracle vs clean-room implementation

These are not the same thing.

Benchmark oracle

A benchmark oracle is a repo you keep primarily for:

• correctness comparison
• regression checks
• move-optimality comparison
• expected-output generation
• performance baselining
• acceptance-test generation

A benchmark oracle does not automatically imply:

• code reuse
• direct integration
• current clean-room reimplementation

Example:

• an optimal GPL solver can be valuable as a correctness oracle without becoming a current clean-room target

Clean-room implementation candidate

A clean-room candidate is a restrictive repo whose behavior or architecture is valuable enough that you want a first-party implementation later, but with source separation.

That requires:

1. exposed Model A source reading
2. scrubbed handoff artifacts
3. isolated Model B implementation with no source access

Rule of thumb

Use benchmark-oracle when the repo’s main value is:

• proving whether your result is correct
• proving whether your solver or planner is good enough

Use clean-room-candidate when the repo’s main value is:

• a user-facing product behavior
• a planner/state architecture pattern
• a lesson flow or practice flow worth rebuilding first-party

Commands

Initialize all three workspaces:

powershell -ExecutionPolicy Bypass -File C:\HyperTwist\scripts\Initialize-ExternalProductWorkspace.ps1 -Product All

Refresh manifests from the baked-in defaults:

powershell -ExecutionPolicy Bypass -File C:\HyperTwist\scripts\Initialize-ExternalProductWorkspace.ps1 -Product All -ForceManifestRefresh

Initialize a single product:

powershell -ExecutionPolicy Bypass -File C:\VectorShell\scripts\Initialize-ExternalProductWorkspace.ps1 -Product VectorShell

Mirror every external repo listed in a manifest:

$manifest = Get-Content -Raw C:\Workspaces\HyperTwist\repos.manifest.json | ConvertFrom-Json
$repos = $manifest.repositories | Where-Object { $_.storage -eq 'external-mirror' -and -not [string]::IsNullOrWhiteSpace($_.repoUrl) }
foreach ($repo in $repos) {
  $parent = Split-Path -Path $repo.localPath -Parent
  if (-not (Test-Path -LiteralPath $parent)) {
    New-Item -ItemType Directory -Path $parent -Force | Out-Null
  }

  if (-not (Test-Path -LiteralPath $repo.localPath)) {
    git clone --depth 1 $repo.repoUrl $repo.localPath
  } else {
    git -C $repo.localPath fetch --all --tags --prune
  }
}

Validate the generated roots quickly:

Test-Path C:\Workspaces\HyperTwist\mirrors\permissive
Test-Path C:\Workspaces\HyperTwist\mirrors\restrictive
Test-Path C:\Workspaces\HyperTwist\clean-room-specs
Test-Path C:\Workspaces\HyperTwist\implementation-workspaces\model-b
Test-Path C:\Workspaces\HyperTwist\generated\main.sln
Test-Path C:\Workspaces\HyperTwist\generated\catalog.sln
Test-Path C:\Workspaces\HyperTwist\generated\active.slnf

Product notes

ScriptoriumAI

Current stance:

• external workspace scaffold exists
• app remains in C:\ScriptoriumAI
• pinned in-repo submodules remain where they already live

The submodule set still includes the retained pinned repos discussed earlier, while the external workspace is the place for future non-pinned mirror fleets.

HyperTwist

Current stance:

• external workspace scaffold exists
• app remains in C:\HyperTwist
• the discussed HyperTwist repo set should live in the external workspace and be split between permissive and restrictive roots

HyperTwist is the strongest current need for restrictive-source custody because it already contains:

• permissive donors
• GPL benchmarks
• no-license repos
• all-rights-reserved pedagogy references

VectorShell

Current stance:

• external workspace scaffold exists
• app remains in C:\VectorShell
• app-only by default for now

If VectorShell later needs a broad mirror fleet, the same permissive/restrictive split should be used from the start.

Recommended workflow

1. Add or review candidate repos in the manifest, not ad hoc in the product repo.
2. Default new candidates to external-mirror plus root.
3. Classify each mirror as permissive or restrictive immediately.
4. Mark each repo’s workflowRole explicitly.
5. Keep restrictive mirrors out of Model B workspaces.
6. Produce repo-specific Model A handoff docs for clean-room candidates.
7. Use restrictive benchmark repos as oracles where needed, but do not confuse that with implementation approval.
8. Re-run the workspace script after changing manifest defaults or project file maps.
9. When source-exposed planning finds active mirror/manifest drift, treat that as a governance task before widening implementation lanes.

What this setup does not do

It does not automatically:

• move the live repos into app\
• decide your long-term licensing strategy
• make restrictive repos safe for direct reuse
• decide which benchmarks deserve later clean-room implementation
• remove the need for deliberate handoff discipline

Those remain deliberate follow-up choices.

Handoff summary

If another model picks this up later, the key facts are:

• external workspaces are scaffolded for all three products
• live repos were intentionally left in place
• app\ is a future migration target only
• repos.manifest.json is the control plane
• permissive and restrictive mirrors are now separate by design
• restrictive mirrors are Model A only
• clean-room-specs\ is the safe handoff zone
• implementation-workspaces\model-b\ is the isolated implementation zone
• benchmark oracles and clean-room candidates must not be conflated
• manifest parity matters as much as folder placement once active restrictive lanes are in use
• large future repo fleets should go to C:\Workspaces\<Product>\mirrors, not into the product repos themselves