# 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:

```text
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:

```json
{
  "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:

```powershell
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:

```text
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
powershell -ExecutionPolicy Bypass -File C:\HyperTwist\scripts\Initialize-ExternalProductWorkspace.ps1 -Product All
```

Refresh manifests from the baked-in defaults:

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

Initialize a single product:

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

Mirror every external repo listed in a manifest:

```powershell
$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:

```powershell
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
