From b578342ee569ee22e0a90814909ecf970207cad4 Mon Sep 17 00:00:00 2001 From: axiomlogicnexus Date: Thu, 21 May 2026 17:24:01 +0200 Subject: [PATCH] Sync doctrine, registry, and discovery surfaces --- ...PERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md | 119 ++++ ...HASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md | 638 ++++++++++++++++++ ...ON_AND_REMOVABILITY_DOCTRINE_2026-05-21.md | 289 ++++++++ ...NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md | 256 +++++++ ...AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md | 486 +++++++++++++ docs/ops/TOOL_ACCESS_AND_REFACTORING_LOG.md | 17 +- docs/v6_5_deep_manual_pack/HyperTwist/API.md | 13 +- .../HyperTwist/ARCHITECTURE.md | 199 +++--- .../CAPABILITY_CONSOLIDATION_DOCTRINE.md | 165 +++++ .../HyperTwist/DEVELOPMENT.md | 155 ++--- .../HyperTwist/FEATURE_REGISTRY.md | 257 +++++++ docs/v6_5_deep_manual_pack/HyperTwist/PRD.md | 81 ++- .../HyperTwist/PROVENANCE_AND_TRUST_MODEL.md | 111 +++ .../HyperTwist/ROADMAP.md | 12 + .../HyperTwist/SKILLS.md | 160 +++-- .../HyperTwist/WORKBENCH_FEATURE_TARGETS.md | 142 ++++ docs/v6_5_deep_manual_pack/README.md | 10 +- 17 files changed, 2866 insertions(+), 244 deletions(-) create mode 100644 docs/ops/HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md create mode 100644 docs/ops/HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md create mode 100644 docs/ops/HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md create mode 100644 docs/ops/HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md create mode 100644 docs/ops/HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md create mode 100644 docs/v6_5_deep_manual_pack/HyperTwist/CAPABILITY_CONSOLIDATION_DOCTRINE.md create mode 100644 docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md create mode 100644 docs/v6_5_deep_manual_pack/HyperTwist/PROVENANCE_AND_TRUST_MODEL.md create mode 100644 docs/v6_5_deep_manual_pack/HyperTwist/WORKBENCH_FEATURE_TARGETS.md diff --git a/docs/ops/HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md b/docs/ops/HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md new file mode 100644 index 0000000..791efb1 --- /dev/null +++ b/docs/ops/HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md @@ -0,0 +1,119 @@ +# HyperTwist Implementation Phase 1 Kickoff + +Created on `2026-05-21`. + +## Purpose + +This file records the current implementation-facing HyperTwist runtime truth +after the retained-set reset, the restrictive clean-room waves, and the first +`Phase 6R` widening packets. + +It exists so the repo has one short operational note that answers: + +- what real product code exists now +- which live first-party seams are already real +- which newer doctrine surfaces govern future widening +- what the next concrete packet should be + +## Verified repo-state note on `2026-05-21` + +Current verified product-side reality is: + +- first-party training/coaching/runtime surfaces are real and landed +- restrictive lanes `onionhoney/roux-trainers`, `cubing/alg.js`, + `cubing/twisty.js`, `HactarCE/2x2x2x2-Scrambler`, and `kash/cubedesk` are + already implemented through accepted bounded packets +- bounded permissive widening is already landed for: + - `HactarCE/Hyperspeedcube` + - `kkoomen/qbr` + - `vivaansinghvi07/rubix-cube-solver` + - `roice3/MagicTile` + - `ggml-org/whisper.cpp` +- no other repo should be described as implemented without explicit packet and + product-surface evidence + +## Live first-party runtime anchors + +Current first-party anchors already present in code include: + +- `UHyperTwistTrainingSubsystem` +- `UHyperTwistTrainingRuntimeLibrary` +- `UHyperTwistTrainingPanelWidget` +- `AHyperTwistTrainingSessionActor` +- `UHyperTwistCoachDashboardWidget` +- `UHyperTwistTrainingCatalogLibrary` +- `UHyperTwistTrainingTilingLibrary` +- `UHyperTwistContractLibrary` +- `UHyperTwistHttpVisionClient` +- `UHyperTwistHttpSpeechClient` +- `UHyperTwistMockSpeechClient` + +These are real first-party seams, not speculative targets. + +## What this scaffold is not + +This is not yet: + +- a full memory federation implementation +- a finished provider-neutral BYOK/profile system +- a broad live skill layer +- the fully widened speech-input / voice-output stack + +Those remain governed future capability families. + +## Governing doctrine stack for next widening + +Use these as the current governing docs: + +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\ROADMAP.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:\HyperTwist\docs\ops\HYPERTWIST_CANONICAL_COMPACT_CLOSEOUT_FORMAT_2026-05-19.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` + +## Immediate next step + +The next bounded move remains: + +1. source-backed `Phase 6R-F` `SYSTRAN/faster-whisper` preparation/control + pass +2. keep it complementary to `ggml-org/whisper.cpp` +3. keep the first widening slice bounded to Python-side transcription-service + orchestration +4. keep model/payload review separate from code-license judgment + +## Memory-specific sequencing rule + +When HyperTwist later returns to memory implementation: + +- do not open one broad "memory packet" +- follow the lane map and packet order in + `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` + +## Provider-specific sequencing rule + +Do not implement provider-specific overlays, usage surfaces, or model-profile +flows directly on top of a donor-specific schema. + +First establish the first-party provider-neutral and BYOK-capable contract in: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` + +## Skillization sequencing rule + +Do not jump directly from retained donor packets to a large live skill layer. + +First follow: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` + +Specifically: + +- `S1-A` registry and manifest contract +- `S1-B` settings/menu/off-state control +- `S2-A` permissive analyzer wrappers +- `S2-B` clean-room command-contract specs diff --git a/docs/ops/HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md b/docs/ops/HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md new file mode 100644 index 0000000..8ef784a --- /dev/null +++ b/docs/ops/HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md @@ -0,0 +1,638 @@ +# HyperTwist Memory Lane Authority And Phase Implementation Doctrine - 2026-05-21 + +## Purpose + +This doctrine gives HyperTwist one implementation-safe memory architecture. + +It exists to answer these questions precisely: + +1. what memory actually means inside HyperTwist +2. which distinct memory lanes exist +3. which lanes are already first-party owned versus still unresolved +4. how those lanes should interoperate without collapsing into one blob +5. how to implement later memory widening under HyperTwist's own phase model + +This document also exists to make later product/manual work easier. + +It gives stable internal names, user-facing labels, phase placement, and lane +descriptions that can later be extracted into product, help, or manual +surfaces without re-deriving the taxonomy from packet notes. + +## Core thesis + +HyperTwist should not ship "one memory system." + +It should ship a federation of bounded memory lanes with clear ownership, +explicit data contracts, and one-way derivation rules. + +The product becomes stronger when it combines: + +- exact training history +- trustworthy session continuity +- explicit recall +- coach-facing durable state +- curated curriculum knowledge +- human-authored notes +- provenance and trust traceability +- workspace/cockpit recall + +without confusing those layers with each other. + +The product becomes weaker when it: + +- lets summaries replace authority +- lets session continuity masquerade as cognition +- lets shared temporary context masquerade as durable memory +- lets compacted output become the only surviving state + +## Governing rules + +The following product rules are non-negotiable: + +1. memory hierarchy is slice-local, not monolithic +2. raw capture remains authoritative +3. derived memory remains derived +4. user-authored notes remain distinct from machine memory +5. session continuity remains distinct from cognitive memory +6. shared coordination memory remains distinct from durable memory +7. provenance must survive every compaction or derivation step +8. assistive compactors and reducers must remain optional and deactivatable +9. memory lanes must be removable or disableable without breaking the core +10. memory implementation route follows capability authority, not route + convenience + +Companion authorities: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` + +## Current evidence posture + +HyperTwist already contains real first-party memory-adjacent state in: + +- `HyperTwistTrainingSubsystem` +- `HyperTwistTrainingRuntimeLibrary` +- `HyperTwistTrainingPanelWidget` +- `HyperTwistCoachDashboardWidget` +- `HyperTwistTrainingPersistenceLibrary` +- `HyperTwistContractLibrary` + +That is enough to write a lane taxonomy and write-direction rules. + +It is not enough to assign strong non-first-party donor `A1` authority for +every memory lane. + +So this doctrine does both: + +- assigns first-party ownership where current product evidence is already real +- marks external donor ownership unresolved or provisional where HyperTwist has + not yet performed source-grounded same-family memory evaluation + +Do not invent certainty beyond that. + +## Canonical memory lane taxonomy + +Each lane includes: + +- internal lane name +- recommended user-facing label +- exact role +- current authority posture +- implementation rule + +### Lane 1 - identity and policy memory + +User-facing label: + +- `Preferences` +- `Training Defaults` +- `Policy` + +Role: + +- user preferences +- trust and consent posture +- retention settings +- assistive-feature opt-in/opt-out defaults +- provider profile policy + +Authority: + +- `A1 / R1 / F1` - first-party HyperTwist settings and trust surfaces + +Implementation rule: + +- keep this lane first-party owned +- donor repos are not allowed to own consent or policy + +### Lane 2 - workspace and cockpit recall memory + +User-facing label: + +- `Workspace Recall` +- `Cockpit Recall` + +Role: + +- dashboard state +- panel state +- active training selection +- recent context +- focus/inspection anchors + +Authority: + +- `A1 / R1 / F1` - first-party current training/runtime/dashboard surfaces + +Implementation rule: + +- preserve current first-party runtime/UI persistence as authority +- later memory lanes may reference these anchors, not own them + +### Lane 3 - chronicle and episodic capture memory + +User-facing label: + +- `Activity Chronicle` +- `Training Chronicle` + +Role: + +- append-only attempt history +- recognition event history +- speech transcript segments +- challenge/publication event history +- imported deck/session event grouping + +Authority: + +- `A1 / R1 / F1` - first-party repository and training-history surfaces +- external donor authority unresolved in current HyperTwist packet set + +Implementation rule: + +- append-only by default +- every higher memory lane must be able to point back to chronicle evidence + +### Lane 4 - continuity and resume memory + +User-facing label: + +- `Session Continuity` +- `Resume Packs` + +Role: + +- active run state +- resume pointers +- in-progress recognition sessions +- in-progress speech sessions +- next-step follow-up continuity + +Authority: + +- `A1 / R1 / F1` - first-party session/run continuity in current code + +Implementation rule: + +- continuity may reference chronicle and cockpit recall +- it must not replace them + +### Lane 5 - shared coordination memory + +User-facing label: + +- `Shared Context` +- `Coordination State` + +Role: + +- bounded state shared across coach, recognition, catalog, replay, and sidecar + subsystems +- scoped temporary coordination +- session-local shared context + +Authority: + +- `A1 / R1 / F2` - provisional first-party target +- stronger external donor authority unresolved in current HyperTwist packet + set + +Implementation rule: + +- keep this bounded and revocable +- do not let it absorb durable cognitive-memory responsibilities + +### Lane 6 - recall and retrieval memory + +User-facing label: + +- `Smart Recall` +- `History Search` + +Role: + +- explicit search over training history +- replay lookup +- challenge/publication lookup +- curriculum/history retrieval + +Authority: + +- `A1 / R1 / F2` - provisional first-party target +- stronger external donor authority unresolved in current HyperTwist packet + set + +Implementation rule: + +- retrieval indexes may be rebuilt +- recall results must link back to authoritative sources + +### Lane 7 - cognitive and consolidated memory + +User-facing label: + +- `Coach Memory` +- `Long-Term Training State` + +Role: + +- durable player tendencies +- follow-up signals +- goals, failures, and pattern signals +- contradiction/supersession of stale derived conclusions + +Authority: + +- `A1 / R1 / F2` - provisional first-party target informed by current coach + state +- stronger external donor authority unresolved in current HyperTwist packet + set + +Implementation rule: + +- every consolidated fact must preserve provenance links +- silent overwrite is not allowed + +### Lane 8 - knowledge and wiki memory + +User-facing label: + +- `Training Atlas` +- `Knowledge Bundle` + +Role: + +- curated curriculum +- hypercubing knowledge +- imported knowledge bundles +- method references and publication-facing knowledge + +Authority: + +- `A1 / R1 / F2` - first-party current knowledge/curriculum surfaces + +Implementation rule: + +- keep this browsable and explicitly reviewable +- do not auto-promote chronicle output into knowledge without rules + +### Lane 9 - user-authored notes memory + +User-facing label: + +- `Training Notes` +- `Notebook` + +Role: + +- human-authored notes +- annotations +- journals +- attached references + +Authority: + +- owner unresolved +- current safest posture: provisional first-party target +- no strong HyperTwist packet currently authorizes an external donor `A1` call + +Implementation rule: + +- keep notes legible and user-owned +- do not bury note content inside opaque machine-memory structures + +### Lane 10 - provenance and trust-ledger memory + +User-facing label: + +- `Memory Ledger` +- `Trust Ledger` + +Role: + +- source of a memory or recommendation +- transformation chain +- observation source +- imported bundle provenance +- confidence/supersession lineage + +Authority: + +- `A1 / R1 / F1` - first-party contract/provenance surfaces already present in + current product architecture + +Implementation rule: + +- every non-raw memory record must be able to name its parents +- derived state must never lose lineage + +### Lane 11 - derived and compacted memory + +User-facing label: + +- `Compact Views` +- `Coach Summaries` + +Role: + +- recap cards +- compact coach briefs +- token-saving context packets +- reduced session summaries + +Authority: + +- `A1 / R1 / F2` - first-party derived-state lane only + +Implementation rule: + +- derived only +- user-deactivatable +- safe to discard and regenerate +- never the sole authority path + +### Lane 12 - procedural and workflow memory + +User-facing label: + +- `Workflow Memory` +- `Session Templates` + +Role: + +- durable session templates +- follow-up routines +- queue/scheduling memory +- drill workflows + +Authority: + +- `A1 / R1 / F1` - first-party current template, follow-up, and scheduling + surfaces + +Implementation rule: + +- donor skills or prompts may inform later flows +- they must not become hidden canonical workflow memory + +## Cross-lane authority summary + +This is the current operational short form: + +- identity and policy: first-party `A1` +- workspace/cockpit recall: first-party `A1` +- chronicle capture: first-party `A1` +- continuity/resume: first-party `A1` +- shared coordination: provisional first-party `A1`, external donor unresolved +- recall/retrieval: provisional first-party `A1`, external donor unresolved +- cognitive/consolidated: provisional first-party `A1`, external donor + unresolved +- knowledge/wiki: first-party `A1` +- user-authored notes: unresolved owner, provisional first-party target +- provenance/trust ledger: first-party `A1` +- derived/compacted memory: first-party `A1` as derived lane only +- procedural/workflow memory: first-party `A1` + +This is the corrected mature model for HyperTwist's present evidence. + +No single repo owns "memory" globally. + +## Data-plane contract + +The product should use a layered data-plane contract rather than one shared +blob. + +### Authoritative planes + +These are authoritative: + +1. identity and policy store +2. workspace/cockpit recall state +3. chronicle/event history +4. continuity/resume store +5. user-authored notes +6. curated knowledge objects + +### Semi-authoritative synthesized planes + +These are authoritative only for their own lane, but must retain lineage: + +1. cognitive fact store +2. recall indexes +3. shared coordination scopes while alive + +### Derived planes + +These are never authoritative: + +1. compact summaries +2. reduced context packets +3. ranking hints +4. coach brief summaries + +## Write rules between lanes + +The safe write rules are: + +1. chronicle writes only to chronicle +2. continuity may reference chronicle and cockpit recall, but not rewrite + chronicle +3. recall indexes may ingest from chronicle, continuity, notes, knowledge, and + cognitive memory, but remain rebuildable +4. cognitive memory may ingest from chronicle and notes, but must emit + provenance links +5. knowledge memory may ingest promoted facts, but promotion rules must be + explicit +6. notes remain directly user-editable and must not be silently rewritten by + cognitive memory +7. derived memory may read from any authoritative lane but may not become the + only stored representation +8. shared coordination memory may mirror selected content temporarily, but + expiry must remain bounded + +## Recommended first-party code architecture + +Do not begin with one monolithic `MemoryManager`. + +Recommended module split: + +- `HyperTwistMemoryCore` + - ids + - lane enums + - provenance contract + - feature toggles + - policy access +- `HyperTwistMemoryChronicle` + - history/event browsing + - chronicle ingestion bridge +- `HyperTwistMemoryContinuity` + - workstream/session binding + - resume packs +- `HyperTwistMemoryRecall` + - remember/recall requests + - provenance drill-down +- `HyperTwistMemoryKnowledge` + - curriculum/knowledge navigation + - promotion/review surfaces +- `HyperTwistMemoryNotes` + - notebook/note flows +- `HyperTwistMemoryDerived` + - compact views + - optional reducers +- `HyperTwistMemoryUI` + - cockpit memory browser + - lane-specific panels + +These are target-shape families, not claims of current implementation. + +## Phase implementation strategy + +Use HyperTwist's own phase model. + +### `0R` + +Goal: + +- source-ground future external memory donors before assigning non-first-party + `A1` authority + +### `1R` + +Goal: + +- contract and ledger reset for memory before feature coding + +Required deliverables: + +1. this doctrine +2. first-party lane/entity naming +3. authoritative-versus-derived rules +4. provenance requirements +5. feature-toggle and deactivation rules + +### `2M` + +Goal: + +- preserve the current runtime truth without broad memory widening + +Meaning: + +- keep current session, repository, cockpit recall, coach summary, and + publication history surfaces stable + +### `6R-M1` - memory contracts and ledger packet + +Implement: + +- lane ids +- memory entity ids +- provenance links +- authoritative-versus-derived flags +- settings keys and feature gates + +### `6R-M2` - chronicle and continuity packet + +Implement: + +- chronicle ledger +- session grouping +- resume packs +- repo-aware continuity guards + +### `6R-M3` - recall and shared-context packet + +Implement: + +- explicit remember/recall +- history search +- provenance drill-down +- scoped shared-memory rules + +### `6R-M4` - cognitive consolidation packet + +Implement: + +- fact extraction +- goals/failures/hypotheses +- contradiction handling +- supersession +- confidence decay + +### `6R-M5` - knowledge and notes packet + +Implement: + +- curated knowledge objects +- reviewable promotion flows +- user-authored note lane if and only if ownership remains justified + +### `6R-M6` - derived memory and optional adjunct packet + +Implement last: + +- compact summaries +- reduced context packets +- optional digest views + +This packet must prove: + +- all-features-off correctness +- derived-only storage +- removability + +### Clean-room-later rule + +If a later boundary-sensitive notebook or memory donor becomes the strongest +owner for a bounded note lane, route that lane through clean-room work. + +Do not pre-authorize that route from doctrine prose alone. + +## Acceptance conditions for mature HyperTwist memory + +HyperTwist should claim strong memory only when all of these are true: + +1. raw training chronicle exists +2. exact session continuity exists +3. explicit recall exists +4. cognitive state is provenance-backed +5. curated knowledge is reviewable +6. user-authored notes remain legible and separate +7. workspace recall survives independently +8. every compacted form is derived +9. users can disable assistive memory features themselves +10. deletion and supersession semantics are explicit + +## Routing rule for future instances + +When future planning, evaluation, or implementation work touches "memory," +name the exact lane first. + +Do not use "memory" as a sufficient implementation scope by itself. + +If later source work materially changes one of the provisional or unresolved +calls above, reopen only the affected earlier packet or standing note under +the cross-lane hierarchy doctrine instead of silently revising the +architecture by chat memory. diff --git a/docs/ops/HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md b/docs/ops/HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md new file mode 100644 index 0000000..78fea45 --- /dev/null +++ b/docs/ops/HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md @@ -0,0 +1,289 @@ +# HyperTwist Optional Assistive Feature Deactivation And Removability Doctrine + +Created on `2026-05-21`. + +## Purpose + +This doctrine records one non-negotiable HyperTwist product rule: + +- compactors +- token reducers +- token strippers +- summarizers +- prompt-shaping helpers +- memory reducers +- skill packs +- auto-trigger skills +- provider-specific overlays +- usage-optimization helpers +- coach brief compressors +- and similar assistive adjuncts + +must remain optional, user-deactivatable, and removable without breaking the +core product. + +This exists to block a predictable failure mode: + +- assistive behavior gets woven into core training, recognition, coaching, or + publication flows +- later removal becomes risky +- reduced or transformed outputs become harder to bypass +- users who do not want those features receive a degraded or infantilized + product path + +That outcome is not allowed. + +## Core rule + +HyperTwist must work correctly when every assistive adjunct in this family is +disabled. + +These features may improve specific workflows. + +They must not become silent mandatory infrastructure for all users. + +## Scope + +This doctrine applies to any feature that changes, trims, compresses, +summarizes, routes, auto-loads, or auto-shapes user-facing context or system +behavior beyond the irreducible core product flow. + +Examples include: + +- compact coach briefs +- condensed replay/session summaries +- token-budget reducers for provider-backed coaching +- transcript or speech-summary reducers +- prompt-context reducers +- raw-to-summary substitution helpers +- skill loading, auto-triggering, or skill recommendation systems +- usage-optimization helpers +- context-packaging helpers +- memory compactors and reduction views + +## Product invariants + +### 1. Core-first operation + +The core product must remain usable and correct with all assistive adjuncts +off. + +That means: + +- no core training run depends on a compactor +- no core recognition loop depends on a skill pack +- no core session continuity depends on a summary reducer +- no core settings flow depends on prompt-shaping helpers + +### 2. Self-service deactivation + +Users must be able to deactivate these features themselves. + +They must not need: + +- donor knowledge +- hidden config edits +- operator intervention +- source-code changes + +Minimum expectation: + +- every user-facing assistive feature must be reachable from settings +- if it appears in a menu, toolbar, panel, or command surface, it must also + have an explicit enable/disable or equivalent control path +- a user must be able to tell whether it is on or off + +### 3. No hidden mandatory transform + +No assistive adjunct may silently replace the authoritative raw path. + +If a feature compacts, summarizes, strips, reduces, or reshapes information: + +- the raw or fuller upstream state remains authoritative +- the reduced form is derived state +- the reduced form must not become the only recoverable state unless the user + deliberately chose that mode and the boundary remains reversible + +### 4. No inferior forced outcome + +Users who disable these features must not receive a second-class product path. + +Turning them off must not break: + +- navigation +- session start/continue/finalize flows +- recognition or replay correctness +- publication or challenge flows +- persistence +- training history +- provider-backed speech/vision contracts + +### 5. No deep interweaving into the critical path + +Assistive adjuncts must not be wired directly into the irreducible core in a +way that makes later removal structurally dangerous. + +They must be introduced as bounded adjunct modules with explicit interfaces. + +### 6. Removability + +If an assistive adjunct is removed later: + +- core builds must still succeed +- core runtime must still start +- saved state must still load safely +- any derived state for that adjunct must degrade gracefully + +Removal difficulty is a design smell, not a justification for keeping the +feature mandatory. + +## Required implementation model + +### Capability registration + +Every assistive adjunct in this family should have a stable first-party +capability identity, including: + +- feature id +- family +- settings key +- optional menu path +- default state +- dependency list +- produced derived artifacts +- fallback behavior when disabled + +This must be a first-party registry concept, not scattered booleans. + +### Layer boundary + +The required architectural posture is: + +- core product surface +- optional assistive feature interface +- concrete assistive implementations + +not: + +- core product surface directly importing arbitrary reducers, summarizers, or + skill logic + +### Global and per-feature toggles + +At minimum, support: + +- a global master gate for assistive adjuncts where practical +- per-feature enable/disable controls + +Preferred next level: + +- per-profile overrides +- per-session overrides + +### Settings and menu rule + +If a feature is operator-visible, it should be operator-controllable. + +That means: + +- settings should expose durable control +- menus or command surfaces may expose immediate control +- menu visibility alone is not enough if durable settings do not exist +- hidden config-file-only control is not an acceptable default UX + +### Raw versus derived state rule + +Any compactor, reducer, summarizer, or helper must store its outputs as +derived state, not canonical state. + +Canonical state examples: + +- full training repository state +- full replay and recognition history +- full speech transcript segments +- full publication or challenge state +- full coach evidence or attempt history + +Derived state examples: + +- compact coach briefs +- condensed recall packets +- reduced context packets +- summary cards +- token-budget hints + +Derived state must be: + +- labeled as derived +- replaceable +- safe to discard +- regenerable where practical + +## Donor adoption rule + +Any donor-derived capability in these families must enter HyperTwist as an +optional assistive adjunct unless a later explicit product decision says +otherwise. + +Donor value here is not implementation authority for core mandatory behavior. + +## Memory consequence + +Compacted or reduced memory views belong only to the derived lane defined by: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` + +They must not replace: + +- raw chronicle/history +- session continuity +- user-authored notes +- curated knowledge +- provenance/ledger records + +## Testing and acceptance rule + +Any future implementation in this family should be accepted only if it passes: + +1. all-assists-off test +2. single-feature-off test +3. single-feature-on test +4. removal test +5. persisted-state compatibility test +6. raw-state availability test + +The acceptance standard is: + +- core product still works +- disabling one adjunct removes only that adjunct +- enabling it does not mutate authority state irreversibly +- removing the implementation module does not break core build or startup +- older state still loads when the adjunct is absent +- reduced output never destroys the authoritative fuller path + +## Relationship to active doctrine + +Use this doctrine with: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\WORKBENCH_FEATURE_TARGETS.md` +- `C:\Workspaces\HyperTwist\clean-room-specs\README.md` +- `C:\Workspaces\HyperTwist\clean-room-specs\MODEL_OUTPUT_RULES.md` + +## Governing consequence for future work + +Future instances must not propose or land: + +- hardwired mandatory compactors +- unavoidable skill auto-routing +- summary-only authority paths +- settings-invisible assistive behavior +- provider-specific overlays that become the only product path + +unless a later explicit doctrine supersedes this one. + +No such supersession exists now. diff --git a/docs/ops/HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md b/docs/ops/HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md new file mode 100644 index 0000000..19513f5 --- /dev/null +++ b/docs/ops/HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md @@ -0,0 +1,256 @@ +# HyperTwist Provider Neutrality And BYOK Doctrine - 2026-05-21 + +## Interpretation rule + +If HyperTwist uses the phrase `OpenAPI BYOK`, treat it as +`OpenAI-compatible custom-endpoint BYOK` unless a later HyperTwist document +defines a stricter internal meaning. + +The goal is provider-neutral model access with first-party key/profile +custody, not vendor lock-in. + +## Purpose + +This doctrine closes the gap between provider-specific donor value and the +actual product requirement for provider-neutral implementation. + +It exists to answer clearly: + +1. whether provider-specific donors are allowed to hard-wire the product to + one vendor +2. how later implementation should generalize single-provider donors +3. where OpenAI-compatible custom endpoints and BYOK fit +4. which slices must stay first-party even when adjunct provider donors are + later retained + +## Core rule + +HyperTwist must be provider-neutral at the top-level product-contract layer. + +That means: + +- no donor is allowed to force product-wide single-provider coupling +- provider-specific donor logic may survive only as bounded adapter, polling, + telemetry, UI-pattern, or workflow-pattern behavior +- operator-facing surfaces such as usage, cost, routing, health, provider + settings, or model choice must consume first-party normalized provider + contracts + +The retained donor may be provider-specific. + +The implemented product must not be. + +## Current evidence posture + +HyperTwist already contains first-party provider/session seams in current code: + +- `HyperTwistRecognitionTypes` +- `UHyperTwistHttpVisionClient` +- `UHyperTwistHttpSpeechClient` +- `UHyperTwistMockSpeechClient` +- `UHyperTwistTrainingSubsystem` + +Those seams prove that HyperTwist already owns bounded provider contracts for: + +- session config +- session open/close +- transcript/result payloads +- health/status envelopes + +Treat those as the current provisional first-party `A1` anchor for recognition +and speech-provider contracts. + +Do not let future provider donors overtake that top-level contract by +accident. + +## Core contract rules + +- HyperTwist top-level provider contract must be first-party and + provider-neutral +- provider-specific donors may contribute bounded UI, adapter, telemetry, + polling, or workflow patterns only +- no provider-specific donor may define the top-level product contract by + accident +- OpenAI-compatible custom endpoints are first-class targets +- first-party BYOK custody, provider profiles, endpoint definitions, and + model-profile mapping remain HyperTwist-owned + +## Required provider classes + +The first-party provider contract must support at least: + +1. official/direct provider integrations +2. OpenAI-compatible API endpoints +3. BYOK endpoints +4. managed gateway providers +5. local/self-hosted providers +6. bounded speech/vision sidecar services + +## Normalization rules + +The normalized provider contract should expose at least: + +- provider identity +- profile identity +- model identity +- endpoint class +- auth source +- capability flags +- usage metrics +- cost metrics +- quota/rate-limit state +- health state +- session state +- workflow-policy state + +UI layers should read that normalized state. + +They should not talk directly to one upstream provider unless they are a +bounded adapter surface. + +## Provider-lane separation + +Keep these lanes distinct: + +1. provider contract lane +2. routing/gateway lane +3. provider-profile and BYOK custody lane +4. normalized usage/cost accounting lane +5. provider-specific overlay/presentation lane +6. provider-specific local log/telemetry ingestion lane +7. admin/policy lane + +## Current authority map by slice + +### Provider contract lane + +- `A1 / R1 / F1` - first-party HyperTwist contract ownership +- current evidence anchor: + - `HyperTwistRecognitionTypes` + - `UHyperTwistHttpVisionClient` + - `UHyperTwistHttpSpeechClient` + +### Routing/gateway lane + +- current strongest owner unresolved in HyperTwist packet authority +- provisional posture: + - first-party target + - later donor evaluation may refine `A/R/F` + +### Provider-profile and BYOK custody lane + +- `A1 / R1 / F1` - first-party only + +### Normalized usage/cost accounting lane + +- owner unresolved in current HyperTwist packet set +- provisional posture: + - first-party target + - later donors may inform bounded accounting implementation + +### Provider-specific overlay/presentation lane + +- provider-specific donors, if retained later, may become `A2` adjuncts for + narrow UI patterns +- they do not own the top-level provider contract + +### Provider-specific local log/telemetry ingestion lane + +- owner unresolved in current HyperTwist packet set +- may later be informed by provider-specific donors or local runtime tooling + +### Admin/policy lane + +- `A1 / R1 / F1` - first-party only + +## BYOK rules + +BYOK must be a first-party capability, not a donor side effect. + +That means: + +- user-supplied API keys remain first-party owned +- user-supplied custom base URLs/OpenAI-compatible endpoints remain + first-party owned +- provider profiles must support: + - official providers + - OpenAI-compatible custom endpoints + - user-labeled BYOK profiles + - per-profile model lists or capability maps + - per-profile auth material + - enable/disable controls +- provider-specific adapters must plug into that first-party profile model + rather than creating parallel key custody + +## Anti-lock-in rules + +- no hard requirement on one vendor for the primary user path +- no product setting or menu may assume only one provider exists +- no core feature may require one specific provider if a normalized first-party + path is possible +- provider-specific enhancements must degrade gracefully when that provider is + disabled + +## Implementation rules + +The correct implementation order is: + +1. first-party provider contract +2. first-party provider profile and BYOK custody surfaces +3. routing and policy layer +4. normalized usage/cost event model +5. operator-facing overlay/dashboard surfaces +6. bounded provider-specific adapters where still useful + +Do not invert that order. + +If HyperTwist starts from a provider-specific overlay and only later tries to +generalize, it will accumulate brittle vendor coupling in the wrong layer. + +## Donor adoption rule + +Provider-specific donors may still be strongest for narrow slices. + +That does not let them own: + +- the top-level provider contract +- key custody +- profile ownership +- global routing language + +License posture affects route, not capability rank. + +But top-level provider contract ownership remains first-party and +provider-neutral. + +## Retroactive backfill rule + +If an earlier HyperTwist packet accidentally let a provider-specific donor +over-shape the top-level contract: + +- reopen that packet selectively +- preserve valid bounded provider-specific value +- demote contract ownership back to first-party normalized interfaces +- do not bulk-rewrite history +- do not invent certainty + +## Relationship to active doctrine + +Use this doctrine with: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\ARCHITECTURE.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\ROADMAP.md` +- `C:\Workspaces\HyperTwist\clean-room-specs\README.md` +- `C:\Workspaces\HyperTwist\clean-room-specs\MODEL_OUTPUT_RULES.md` + +## Canonical decision sentence + +Provider-specific retained repos may survive as bounded donors, but every +implemented HyperTwist usage, cost, routing, health, or settings surface must +resolve through first-party provider-neutral contracts with OpenAI-compatible +custom-endpoint and BYOK support. diff --git a/docs/ops/HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md b/docs/ops/HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md new file mode 100644 index 0000000..38e8289 --- /dev/null +++ b/docs/ops/HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md @@ -0,0 +1,486 @@ +# HyperTwist Skillization And Command Surface Doctrine - 2026-05-21 + +## Purpose + +This document defines how HyperTwist should turn retained repo value into: + +- first-party commands +- first-party operator skills +- clean-room skill specifications +- placeholder skill families + +It exists to prevent two failures: + +1. donor command surfaces quietly becoming product truth +2. trying to make every retained feature into a skill + +## Canonical rule + +HyperTwist skills must sit on top of first-party command or service contracts. + +They must not be the primary truth of a feature. + +They must not be the only way to use a feature. + +They must remain optional under the assistive-feature doctrine. + +Governing companion authorities: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\SKILLS.md` +- `C:\HyperTwist\docs\ops\TOOL_ACCESS_AND_REFACTORING_LOG.md` + +## Distinctions that must stay explicit + +### 1. Product feature + +A product feature is a durable capability of HyperTwist itself. + +Examples: + +- recognition and reconstruction +- replay and explanation +- training/coaching orchestration +- hyper puzzle catalog and topology runtime +- provider-neutral speech/vision sidecar contracts + +### 2. First-party command surface + +A command surface is the stable product-owned operational interface that +exposes a bounded capability. + +Target-shape examples: + +- `ht train ...` +- `ht recognition ...` +- `ht replay ...` +- `ht coach ...` +- `ht catalog ...` +- `ht provider ...` +- `ht memory ...` +- `ht review ...` + +These are target-shape examples, not live implementation claims. + +### 3. Skill + +A skill is an optional assistance layer that helps the model or operator apply +bounded first-party capabilities correctly. + +A skill may: + +- choose the right command sequence +- assemble context +- produce a structured plan +- enforce a workflow checklist +- summarize bounded outputs + +A skill must not replace the underlying command or service. + +### 4. Donor command reference + +This is upstream command behavior recorded for analysis or operator use in +external custody. + +It is useful design input. + +It is not the first-party HyperTwist contract. + +### 5. Clean-room skill specification + +This is a first-party specification of intended behavior derived from a +restrictive or boundary-sensitive source. + +It may describe: + +- workflow +- inputs/outputs +- safety rules +- expected first-party commands + +It must not copy donor wording into the shippable product contract. + +## Restrictive repo rule + +For restrictive, mixed-custody, or no-grant repos, HyperTwist must define its +own commands. + +That matters immediately for retained restrictive lanes such as: + +- `onionhoney/roux-trainers` +- `cubing/alg.js` +- `cubing/twisty.js` +- `HactarCE/2x2x2x2-Scrambler` +- `kash/cubedesk` + +Donor commands remain: + +- research input +- comparison input +- clean-room planning input + +They do not become the canonical HyperTwist command surface. + +## Not every feature should become a skill + +Create a skill when the capability is: + +- user- or operator-invoked +- repetitive enough to deserve workflow packaging +- multi-step enough that sequencing matters +- bounded enough to expose clear inputs and outputs +- safe to disable without breaking product truth + +Do not make a skill the primary surface for: + +- low-level storage engines +- provider transport internals +- recognition transport internals +- passive overlays that should simply read normalized state +- narrow math/runtime kernels + +## Skill status taxonomy + +Every planned HyperTwist skill should be classified as one of: + +### `Live first-party skill` + +- backed by implemented first-party commands/services +- safe to expose in live product/UI + +### `Command-contract pending` + +- feature authority is understood +- first-party capability is retained +- command contract is not yet stable enough to wrap + +### `Clean-room spec pending` + +- retained source value exists +- product-side skill may only be specified, not implemented yet +- waiting for clean-room command design or bounded reimplementation + +### `Placeholder family` + +- known useful future skill family +- not yet source-grounded or not yet worth formalizing + +## Phase implementation strategy + +Keep the `S1-S7` macro-order, but execute it through bounded sub-packets. + +### S1 - skill substrate and registry + +Build the shared base first: + +- first-party skill registry +- enable/disable state +- menu/settings exposure +- provenance/invocation logging +- command/service binding metadata +- examples and validation harness + +#### `S1-A` registry and manifest contract + +Outputs: + +- first-party skill manifest schema +- skill id, version, owner lane, and status fields +- command/service binding declaration +- permission/scope declaration +- provenance/log declaration + +Acceptance gates: + +- every skill can be described without ad hoc metadata +- disabled skills remain installed but inert + +#### `S1-B` settings, menu, and visibility controls + +Outputs: + +- global skill enable/disable master switch +- per-skill enable/disable state +- visibility grouping + +Acceptance gates: + +- core product still works with all skills off +- no skill requires prompt babysitting to disable + +#### `S1-C` invocation, provenance, and audit ledger + +Outputs: + +- invocation record format +- command/service provenance +- failure/cancel recording + +Acceptance gates: + +- skill output never becomes untraceable product truth + +#### `S1-D` authoring, examples, and validation harness + +Outputs: + +- first-party skill authoring template +- validation corpus structure +- per-skill smoke/eval contract + +Acceptance gates: + +- new skills can be added without inventing structure + +### S2 - refactor and analyzer skills + +Start with the highest-leverage engineering/tooling family. + +#### `S2-A` permissive live analyzer wrappers + +Outputs: + +- architecture scan +- policy scan +- route inspection +- watch-and-recheck + +Acceptance gates: + +- each skill maps to a stable first-party invocation pattern +- each skill can surface structured output + +#### `S2-B` clean-room command-contract spec + +Scope: + +- restrictive training/replay/coaching lanes + +Outputs: + +- first-party command-contract specs for clean-room lanes +- safety model for bounded clean-room skill work + +Acceptance gates: + +- a future skill can wrap the first-party contract without donor wording + +#### `S2-C` clean-room skill specs + +Outputs: + +- clean-room-ready skill specs +- not necessarily live implementation yet + +Acceptance gates: + +- the skills are expressible entirely in first-party terms + +### S3 - memory and continuity skills + +#### `S3-A` continuity and resume skills + +Outputs: + +- `resume-session` +- `search-history` +- `capture-note` + +Acceptance gates: + +- continuity skills read authoritative stores + +#### `S3-B` recall and compact-view skills + +Outputs: + +- `recall-memory` +- `generate-compact-view` + +Acceptance gates: + +- compact views remain optional and linked to authoritative sources + +#### `S3-C` workflow-memory capture skills + +Outputs: + +- bounded procedural-memory capture skills + +Acceptance gates: + +- workflow memory does not collapse into opaque summaries + +### S4 - browser/docs/design skills + +#### `S4-A` extraction skills + +Outputs: + +- docs extraction +- design-spec extraction + +#### `S4-B` browser diagnostics skills + +Outputs: + +- browser trace capture +- browser/API discovery + +#### `S4-C` translation/design-to-native skills + +Outputs: + +- bounded design-to-native translation skills + +### S5 - workflow and review skills + +#### `S5-A` permissive workflow/review wrappers + +Outputs: + +- proposal review +- diff review +- bounded workflow wrappers + +#### `S5-B` implementation-review and delegation specs + +Outputs: + +- implementation review +- bounded delegation specs + +#### `S5-C` plan synthesis/orchestration glue + +Outputs: + +- plan synthesis +- bounded workflow chaining + +### S6 - provider/gateway/operations skills + +#### `S6-A` provider-neutral profile/routing skills + +Outputs: + +- inspect provider profile +- setup BYOK profile +- diagnose routing + +Acceptance gates: + +- custom OpenAI-compatible endpoints remain first-class + +#### `S6-B` usage and operations audit skills + +Outputs: + +- usage audit +- topology inspection +- route/service diagnostics + +Acceptance gates: + +- provider skills read normalized first-party state + +### S7 - domain and creative skill packs + +#### `S7-A` domain-pack framework + +Outputs: + +- packaging rules +- enable/disable grouping + +#### `S7-B` first retained domain packs + +Likely families: + +- training/replay review pack +- curriculum/content pack +- media/export pack + +#### `S7-C` creative/media packs + +Outputs: + +- optional adjunct creative/media packs + +## Packet acceptance matrix + +Every skill packet should record: + +1. packet scope +2. feature/lane owner +3. `A/R/F` authority basis +4. first-party command/service dependency +5. UI/settings exposure plan +6. audit/provenance plan +7. validation cases +8. off-state behavior +9. non-goals + +If `4`, `7`, or `8` are missing, the packet is not ready. + +## Initial first-party command families to formalize + +Preferred future command families: + +- `ht analyze ...` +- `ht graph ...` +- `ht watch ...` +- `ht route ...` +- `ht review ...` +- `ht train ...` +- `ht recognition ...` +- `ht replay ...` +- `ht coach ...` +- `ht catalog ...` +- `ht memory ...` +- `ht provider ...` + +These are target-shape command families, not claims of implemented reality. + +## Immediate next skillization move + +The next correct sequence is: + +1. `S1-A` first-party skill registry and manifest contract +2. `S1-B` per-skill settings/menu exposure and off-state behavior +3. `S2-A` permissive analyzer wrappers +4. `S2-B` clean-room command-contract specs for restrictive lanes + +Broader memory, browser, workflow, provider, and domain skill widening should +wait until that base exists. + +## Product messaging rule + +Later user-facing docs may say HyperTwist has: + +- optional operator skills +- review/analyzer skills +- memory/continuity skills +- provider/ops skills +- domain skill packs + +But those claims must still respect the feature-registry tiers: + +- implemented now +- deep-source grounded retained +- shallow placeholder + +## Bottom line + +Yes, HyperTwist should grow a broad skill layer. + +But the mature path is: + +- first-party command contracts first +- skills second +- clean-room command specs for restrictive lanes +- no donor command surface promoted into product truth by accident diff --git a/docs/ops/TOOL_ACCESS_AND_REFACTORING_LOG.md b/docs/ops/TOOL_ACCESS_AND_REFACTORING_LOG.md index f1e7bea..8ab28e6 100644 --- a/docs/ops/TOOL_ACCESS_AND_REFACTORING_LOG.md +++ b/docs/ops/TOOL_ACCESS_AND_REFACTORING_LOG.md @@ -1,4 +1,19 @@ -# SCRIPTORIUM AI TOOL ACCESS & REFACTORING LOG +# SCRIPTORIUM AI TOOL ACCESS & REFACTORING LOG + +## HyperTwist current routing note + +This file is not the governing HyperTwist command-surface or skillization +authority. + +For current HyperTwist doctrine, use: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` + +Treat this file as legacy tool/refactor history, not as live HyperTwist +feature or command-contract truth. # Sentrux Architectural Refactoring Log diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/API.md b/docs/v6_5_deep_manual_pack/HyperTwist/API.md index 1004fae..f432661 100644 --- a/docs/v6_5_deep_manual_pack/HyperTwist/API.md +++ b/docs/v6_5_deep_manual_pack/HyperTwist/API.md @@ -1,4 +1,10 @@ -# HyperTwist — API.md +# HyperTwist - API.md + +Canonical companion surfaces: + +- `FEATURE_REGISTRY.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` ## API philosophy @@ -24,6 +30,11 @@ The system should remain primarily native-first and local-first where reasonable - error clustering - personalized next-step guidance +### Provider/session API +- provider-neutral speech/vision session contracts +- normalized service health +- later BYOK/profile custody and model mapping + ### Profile / progression API - user settings - training history diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/ARCHITECTURE.md b/docs/v6_5_deep_manual_pack/HyperTwist/ARCHITECTURE.md index 1ca3e06..8117e7d 100644 --- a/docs/v6_5_deep_manual_pack/HyperTwist/ARCHITECTURE.md +++ b/docs/v6_5_deep_manual_pack/HyperTwist/ARCHITECTURE.md @@ -1,83 +1,123 @@ -# HyperTwist — ARCHITECTURE.md +# HyperTwist - ARCHITECTURE.md ## Product identity -HyperTwist is an all-in-one native training environment for cubes and hypercubes. Its special strength is that it joins: +HyperTwist is a native training environment for cubes and hypercubes. + +Its special strength is that it joins: + - physical-world cube interaction and analysis - virtual simulation and higher-dimensional training -- AI-guided coaching and progression +- training/coaching orchestration +- bounded speech/voice and provider-backed sidecar contracts + +## Canonical discovery surfaces + +Use these alongside this document: + +- `FEATURE_REGISTRY.md` for normalized feature families and confidence tiers +- `CAPABILITY_CONSOLIDATION_DOCTRINE.md` for lane consolidation +- `WORKBENCH_FEATURE_TARGETS.md` for cockpit/workbench targets +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` + for memory-lane architecture +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` + for provider/BYOK architecture +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` + for current landed runtime anchors ## Runtime center -The runtime center should be Unreal Engine 5.4+. +The runtime center is Unreal Engine. -## Current landed donor truth +HyperTwist is not merely a trainer app. It wants: -HyperTwist currently has a narrow landed donor truth, not a broad one: - -- five permissive `MIT` donor lanes are already live in training materialization and owned source attribution -- one restrictive lane, `onionhoney/roux-trainers`, is already live through the current accepted clean-room implementation chain -- the remaining donor portfolio is still a retained architecture backlog, not a proven implemented architecture - -### Why Unreal fits -Unreal is justified because HyperTwist is not merely a trainer app. It wants: - high-quality rendering -- immersive puzzle manipulation -- spatial intuition for higher dimensions -- VR/MR expansion potential -- high-performance native runtime +- embodied puzzle manipulation +- replay and inspection surfaces +- higher-dimensional spatial intuition +- future XR expansion + +## Current landed architecture truth + +HyperTwist already has real first-party runtime anchors in current code: + +- `UHyperTwistTrainingSubsystem` +- `UHyperTwistTrainingRuntimeLibrary` +- `UHyperTwistTrainingPanelWidget` +- `AHyperTwistTrainingSessionActor` +- `UHyperTwistCoachDashboardWidget` +- `UHyperTwistTrainingCatalogLibrary` +- `UHyperTwistTrainingTilingLibrary` +- bounded provider/session clients for vision and speech + +Do not treat the remaining retained portfolio as already architecturally +absorbed. ## Backbone language strategy ### C++ + Use for: + - puzzle-state core -- renderer integration +- renderer/runtime integration - interaction hot paths - replay engine - native timer and analytics primitives -- projection logic -- heavy simulation work +- topology/geometry logic ### Rust or C++ -Use for: -- algorithm engines -- search and scoring -- state serialization -- progression computations -- high-throughput replay or analytics pipelines -### C# -Use only where: -- bounded profile/progression/orchestration services -- enterprise or educational admin surfaces -- durable background jobs -are clearly beneficial +Use for: + +- algorithm engines +- search/scoring +- serialization +- high-throughput replay/analytics pipelines ### Python / TypeScript + Keep bounded: -- Python for CV or model inference where still practical -- TypeScript for thin dashboard or companion UI surfaces only -## Dual-pillar architecture +- Python for sidecar inference/service orchestration when still practical +- TypeScript/web only for thin adjunct surfaces -### Pillar 1 — physical cube pipeline -- camera input -- state recognition -- confidence and correction UI -- solve reconstruction +## Canonical product lanes + +### 1. Physical cube pipeline + +- camera/frame input +- calibration +- observation capture +- reconstruction +- correction UI - replay generation -- AI commentary and drill suggestions -### Pillar 2 — hypercube simulation pipeline -- n-dimensional puzzle model -- rendering and projection -- notation teaching -- immersive manipulation -- advanced user workflows -- compatibility with known hypercubing formats where worthwhile +### 2. Training and coaching pipeline -## Subsystem proposal +- training sessions +- drills +- follow-up flows +- coach summaries +- analytics/reporting +- publication/social training surfaces + +### 3. Hyper puzzle pipeline + +- hyper puzzle catalog +- topology families +- notation/runtime contracts +- immersive/world presentation + +### 4. Speech/provider sidecar pipeline + +- speech transcript sessions +- provider-backed speech/vision health/session contracts +- later provider-neutral BYOK/profile model + +## Subsystem posture + +Recommended subsystem families remain: - `HyperTwistCore` - `HyperTwistSimulation` @@ -87,50 +127,37 @@ Keep bounded: - `HyperTwistCoach` - `HyperTwistProgression` - `HyperTwistXR` - -## Integration policy - -### Foundation candidates -Treat true simulation cores and essential logic frameworks separately from: -- wrappers -- ports -- UI frameworks -- ecosystem experiments - -### CV candidates -Likely best as bounded services or donor modules first unless one is simple and directly embeddable. - -### Trainer candidates -Often strategic donors rather than foundations. - -Current correction: - -- the currently landed trainer donor set is small and explicit -- do not treat all selected trainer repos as already architecturally absorbed - -### Hyper tools -Need to be judged for: -- algorithmic depth -- notation compatibility -- rendering value -- interoperability with the rest of the stack +- later bounded memory/provider/skill families where justified ## Provenance control plane -Architecture decisions for HyperTwist must now preserve three visibly separate layers: +Architecture decisions must preserve three visible layers: - landed/live first-party implementation -- retained donor backlog pending deep evaluation +- retained donor backlog pending bounded implementation - restrictive clean-room or benchmark/reference lanes -That provenance split is part of the architecture, not just part of legal paperwork. +That provenance split is architecture, not just legal paperwork. -## Unreal/XR posture +Companion trust surface: -HyperTwist benefits from: -- controller and hand-based manipulation -- spatial coaching overlays -- higher-dimensional explanatory projection -- embodied replay and algorithm walkthroughs +- `PROVENANCE_AND_TRUST_MODEL.md` -The immersive mode is not the whole product, but it is a major differentiator. +## Memory and provider correction + +Do not treat memory as one opaque monolith. + +Do not treat provider-specific donors as top-level contract owners. + +Those two corrections are governed by: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` + +## Skillization correction + +Do not let donor commands or optional skills become hidden product truth. + +Future skill growth must follow: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/CAPABILITY_CONSOLIDATION_DOCTRINE.md b/docs/v6_5_deep_manual_pack/HyperTwist/CAPABILITY_CONSOLIDATION_DOCTRINE.md new file mode 100644 index 0000000..c876058 --- /dev/null +++ b/docs/v6_5_deep_manual_pack/HyperTwist/CAPABILITY_CONSOLIDATION_DOCTRINE.md @@ -0,0 +1,165 @@ +# HyperTwist - CAPABILITY_CONSOLIDATION_DOCTRINE.md + +## Purpose + +Define how dozens of evaluated repos collapse into a manageable first-party +HyperTwist architecture. + +The output of the repo program is not "many repos inside the app." + +The output is a first-party capability map. + +Canonical normalized feature extraction surface: + +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md` + +## Core rule + +Consolidate by capability lane, not by donor product. + +Each retained repo should resolve into one or more of: + +- primary owner candidate +- secondary donor +- adjunct pattern donor +- clean-room-only donor +- discard/overlap + +## Canonical capability lanes + +### 1. Puzzle runtime and replay + +Includes: + +- puzzle-state runtime +- notation/semantic adapters +- replay timeline +- state serialization +- runtime verification + +### 2. Recognition and reconstruction + +Includes: + +- camera/frame ingestion +- calibration +- face observation +- reconstruction +- correction/explanation shells + +### 3. Training, coaching, and session control + +Includes: + +- training sessions +- drills +- coach flows +- follow-up state +- scheduling/queue behavior + +### 4. Catalog, curriculum, and knowledge + +Includes: + +- imported packs +- generated-mode launch +- curriculum bundles +- hypercubing knowledge/reference + +### 5. Publication, entitlement, and social training + +Includes: + +- publication projection +- leaderboard reference +- entitlement +- local social challenge state +- later admin/report only when justified + +### 6. Hyper topology and immersive expansion + +Includes: + +- hyper puzzle catalog +- topology families +- non-Euclidean interaction +- immersive/world presentation + +### 7. Speech and voice sidecars + +Includes: + +- STT session boundaries +- VAD/segmentation +- transcript/result shaping +- later TTS/narration sidecars + +### 8. Analytics, media, and export + +Includes: + +- analytics/reporting +- media export +- embedded playback +- browser-spatial adjuncts + +### 9. Provider and optional assistive control plane + +Includes: + +- provider-neutral contracts +- BYOK/profile custody +- normalized usage/cost/routing +- optional skills +- reducers/compactors + +## Cross-lane invariants + +Every lane still shares: + +- object identity +- provenance/trust +- session continuity +- replay/evidence linkage +- operator override +- packet authority + +These are not donor-owned mini-lanes. They are product invariants. + +## Ownership rule + +For each lane, prefer: + +1. one primary first-party owner +2. a small number of secondary donors +3. adjuncts only where they remove real gaps + +Avoid: + +- duplicate shells +- duplicate session systems +- duplicate provenance systems +- donor-shaped product sprawl + +## Relationship to current doctrine + +Use this consolidation doctrine with: + +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\PROVENANCE_AND_TRUST_MODEL.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\WORKBENCH_FEATURE_TARGETS.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` + +## Acceptance rule + +A donor is useful only when it clarifies one of: + +- ownership +- design pattern +- test oracle +- schema/contract +- bounded implementation target + +If it does none of those, it should not shape the product. diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md b/docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md index f01a0cc..9cec3a5 100644 --- a/docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md +++ b/docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md @@ -1,17 +1,31 @@ -# HyperTwist — DEVELOPMENT.md +# HyperTwist - DEVELOPMENT.md ## Development philosophy HyperTwist should be developed as a serious native product: + - Unreal project as the main runtime -- C++ simulation and rendering core -- Blueprints for interaction and curriculum logic -- bounded CV or analytics sidecars where needed +- C++ simulation, training, and recognition core +- bounded sidecars where they materially help - minimal web-only surface +## Canonical development authorities + +Use these before widening implementation: + +- `ROADMAP.md` for current queue truth +- `FEATURE_REGISTRY.md` for normalized feature truth +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` for + current landed runtime anchors +- `C:\HyperTwist\docs\HYPERTWIST_MODEL_A_MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md` + for implementation-state discipline +- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md` + for `A/R/F` authority resolution + ## Current development gate -Do not reopen broad donor-driven widening as if the whole retained portfolio were already settled. +Do not reopen broad donor-driven widening as if the whole retained portfolio +were already settled. State-separation rule: @@ -23,111 +37,74 @@ State-separation rule: - implementation-authorized = explicitly approved bounded build work - implemented = actually landed in first-party product surfaces -Do not let bookmark presence, queue position, or frequent mention masquerade as +Do not let bookmark presence, queue position, or docs metadata masquerade as product intent or proof of implementation. -Donor-strength rule: +## Donor-strength rule - donor strength and legal posture are separate axes -- a restrictive or boundary-sensitive repo can still be the strongest owner for a lane -- route difficulty changes how retained value may enter the product, not whether it may win technically +- a restrictive or boundary-sensitive repo can still be the strongest owner + for a lane +- route difficulty changes how retained value may enter the product, not + whether it may win technically -Current truth: +## Current live implementation truth -- `20` repos are currently verified live in checked Unreal surfaces -- `13` are permissive `MIT` or `Apache-2.0` -- `6` are boundary-sensitive lanes: `cubing/cubing.js` through the practical `MPL` adapter path, `cutelyaware/magiccube4d` through the landed attribution/provenance boundary path, `google/model-viewer/packages/shared-assets` through the landed allowlist/provenance boundary path, `PostHog/posthog` through the landed control-plane subtree-boundary path, `screenpipe/screenpipe` through the landed capture-history subtree-boundary path, and `remotion-dev/remotion` through the landed package-split commercial-boundary path -- `1` is the restrictive `onionhoney/roux-trainers` lane that is already properly clean-roomed and implemented -- `Phase 0R` is now closed for the remaining `51` non-live rows -- `Phase 1R` is now closed as the retained-set contract and handoff overhaul -- `Phase 2R` is now closed as the retained-set ownership and acceptance packet sequence -- `Phase 3R-A` is now closed as the landed `Aarav2709/KubeTimr` widening packet -- `Phase 3R-B` is now closed as the landed `Hypercubers/hypercubing.xyz` widening packet -- `Phase 3R-C` is now closed as the landed `apache/echarts` widening packet -- `Phase 3R-D` is now closed as the landed `google/model-viewer` widening packet -- `Phase 3R-E` is now closed as the landed `met4citizen/TalkingHead` widening packet -- `Phase 3R-F` is now closed as the landed `mrdoob/three.js`, `pmndrs/react-three-fiber`, and `pmndrs/xr` widening packet -- `Phase 4R-A` is now closed as the landed `cubing/cubing.js` classic-cubing adapter widening packet -- `Phase 4R-B` is now closed as the landed `cutelyaware/magiccube4d` legacy `4D` interaction/history/macro widening packet -- `Phase 4R-C` is now closed as the landed `google/model-viewer/packages/shared-assets` allowlist/provenance widening packet -- `Phase 4R-D` is now closed as the landed `PostHog/posthog` control-plane widening packet -- `Phase 4R-E` is now closed as the landed `screenpipe/screenpipe` capture/history/replay, deterministic-permission, persistence, vault-lifecycle, and timeline-review widening packet -- `Phase 4R-F` is now closed as the landed `remotion-dev/remotion` media-export, embedded playback, parser, explainer-studio, and package-split commercial-boundary widening packet +Do not use this file as the canonical count surface. + +For the current exact implemented-row counts, landed packets, and queue head, +use: + +- `ROADMAP.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` + +## Memory / provider / skillization correction + +Future widening should now follow explicit doctrine rather than generic prose: + +- memory: + `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- provider/BYOK: + `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- skillization/command surface: + `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` ## Model A interpretation rule For boundary-sensitive and restrictive rows: -- future `Model A` work should still pursue full bounded realization of the retained domain -- `do not promote` and similar wording in the `0R` packets is a boundary filter, not a cap on later source-value extraction depth -- if a retained handoff is too thin, strengthen the packet or scrubbed handoff while preserving the no-copy guardrails -Canonical doctrine doc: -- `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\HYPERTWIST_MODEL_A_MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md` +- future `Model A` work should still pursue full bounded realization of the + retained domain +- `do not promote` and similar wording in `0R` packets is a boundary filter, + not a cap on later source-value extraction depth +- if a retained handoff is too thin, strengthen the packet/scrubbed handoff + while preserving no-copy guardrails -Implementation-state scanning note: +## Suggested product module families -- routine live or product-surface scanning is no longer the default evaluation step -- assume a repo is not implemented unless explicit implementation authority says otherwise -- only verify current implementation state when the active task depends on that fact - -Next sequence: - -1. preserve the twenty landed lanes -2. preserve the landed `cubing/cubing.js` boundary-sensitive adapter lane with its `MPL` notice posture explicit -3. preserve the landed `cutelyaware/magiccube4d` boundary-sensitive lane with its attribution, upstream-link, and provenance posture explicit -4. preserve the landed `google/model-viewer/packages/shared-assets` boundary-sensitive lane with its allowlist, review-only, and local-only posture explicit -5. preserve the landed `PostHog/posthog` boundary-sensitive lane with its explicit root-`MIT`-core-versus-`ee/` subtree boundary explicit -6. preserve the landed `screenpipe/screenpipe` boundary-sensitive lane with its explicit permissive-core-versus-`ee/` subtree boundary explicit -7. preserve the landed `remotion-dev/remotion` boundary-sensitive lane with its explicit company-license and package-split boundary explicit -8. use the retained-set contract as the only legal/roadmap routing surface for non-live rows -9. keep `Aarav2709/KubeTimr`, `Hypercubers/hypercubing.xyz`, `apache/echarts`, `google/model-viewer`, `met4citizen/TalkingHead`, `cubing/cubing.js`, `cutelyaware/magiccube4d`, `google/model-viewer/packages/shared-assets`, `PostHog/posthog`, `screenpipe/screenpipe`, and `remotion-dev/remotion` on preserve-and-enhance footing through their landed packets -10. continue broader widening from `Phase 5R-A`, with optional `Phase 3R-G` comparison work only if the landed primary browser spatial stack exposes a real gap - -## Suggested repo structure - -- `HyperTwist/` - - `Source/HyperTwistCore` - - `Source/HyperTwistSimulation` - - `Source/HyperTwistRecognition` - - `Source/HyperTwistReplay` - - `Source/HyperTwistTraining` - - `Source/HyperTwistCoach` - - `Source/HyperTwistXR` -- `hypertwist-services/` - - optional CV inference service - - optional progression or coaching service -- `docs/` - - replay packet specs - - trainer logic - - notation / interchange specs - - benchmark notes +- `Source/UnrealHyperTwist/Core` +- `Source/UnrealHyperTwist/Simulation` +- `Source/UnrealHyperTwist/Recognition` +- `Source/UnrealHyperTwist/Replay` +- `Source/UnrealHyperTwist/Training` +- `Source/UnrealHyperTwist/Coach` +- `Source/UnrealHyperTwist/XR` +- later bounded memory/provider/skill families where justified ## Build order 1. preserve and document landed implementation truth -2. completed `Phase 0R` deep source evaluation reset for remaining rows -3. completed `Phase 1R` contract / handoff / provenance overhaul -4. completed retained-set ratification and packet design -5. permissive implementation waves from retained rows -6. boundary-sensitive adapter or sidecar waves -7. restrictive clean-room waves from retained rows -8. simulation core expansion from retained set -9. state and notation standardization -10. replay and export -11. physical recognition -12. trainer/progression -13. AI coach -14. immersive hyper modes -15. optimization and polish +2. respect retained-set routing and packet authority +3. widen through bounded permissive, boundary-sensitive, or clean-room packets + only +4. keep current queue truth in `ROADMAP.md` +5. route future memory/provider/skill work through their governing doctrines ## Testing - move/state correctness - replay integrity -- scramble validity -- CV uncertainty handling +- reconstruction/recognition uncertainty handling - coaching recommendation stability -- XR interaction reliability +- topology/runtime validation - progression persistence and analytics diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md b/docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md new file mode 100644 index 0000000..a0e30ec --- /dev/null +++ b/docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md @@ -0,0 +1,257 @@ +# HyperTwist - FEATURE_REGISTRY.md + +## Purpose + +This file is the canonical normalized feature extraction surface for +HyperTwist. + +It exists so later work such as: + +- manuals +- onboarding docs +- roadmap summaries +- UI copy planning +- marketing drafts +- portfolio/status summaries + +does not need to recover feature truth from packet notes, roadmap fragments, +and donor comparisons. + +This file is deliberately not only an "implemented now" list. + +It separates: + +- current implemented truth +- deep-source grounded retained capability +- shallow placeholder capability + +That separation is the important part. + +## Governing rule + +Treat this file as the normalized feature registry. + +Treat packet docs, standing notes, and current product code as the authority +behind each entry. + +If this registry and a packet disagree, the packet wins. + +If this registry and live code disagree, live code plus the current +implementation kickoff and roadmap win. + +Primary authority surfaces behind this registry: + +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\PRD.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\ARCHITECTURE.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\ROADMAP.md` +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\CAPABILITY_CONSOLIDATION_DOCTRINE.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` +- the relevant implementation packet docs + +## Status taxonomy + +Every feature entry in this registry must use one of these tiers. + +### `Implemented now` + +Meaning: + +- first-party product-surface evidence exists now +- safe to describe as current product capability + +### `Deep-source grounded retained` + +Meaning: + +- feature is source-backed and retained through repo evaluation or bounded + implementation authority +- not necessarily implemented in the live product yet +- safe to describe as retained or planned product capability +- not safe to describe as already shipped unless separate product evidence + exists + +### `Shallow placeholder` + +Meaning: + +- feature family is known from shallow intake, README signal, queue shape, or + portfolio census +- exact source-backed capability boundaries are not yet established +- not safe to market as a committed feature +- useful only as an internal stub + +## Extraction rule + +When later generating user-facing material: + +1. `Implemented now` + - may be described as present +2. `Deep-source grounded retained` + - may be described as retained, planned, or roadmap capability +3. `Shallow placeholder` + - must stay internal unless later deep-source work upgrades it + +Do not collapse those three tiers into one undifferentiated "features" voice. + +## Current implemented truth + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Native Unreal training runtime | Implemented now | first-party runtime + kickoff note | Current runtime center is real, not speculative. | +| Training session orchestration and coaching cockpit | Implemented now | current training/coaching surfaces | `UHyperTwistTrainingSubsystem`, `UHyperTwistTrainingRuntimeLibrary`, `UHyperTwistTrainingPanelWidget`, and `UHyperTwistCoachDashboardWidget` are real first-party anchors. | +| Curriculum/catalog materialization and generated-mode launch | Implemented now | first-party catalog/training surfaces | Imported training packs and generated-mode launch flows are live. | +| Classic-cube timing, drill, and training-session flows | Implemented now | landed timer/training packets | Current training surface is broader than a timer-only shell. | +| Publication/leaderboard projection and entitlement gating | Implemented now | landed `kash/cubedesk` bounded packets | Publication and entitlement are live first-party training surfaces. | +| Local social challenge bundle | Implemented now | landed `kash/cubedesk` `Bound 5` | Challenge/social training slice is real, but bounded. | +| Classic-cube calibration and ordered face observation | Implemented now | landed `qbr` packet | Calibration contract and ordered face-observation contract are live. | +| Committed-face reconstruction and final classic-net shaping | Implemented now | landed `rubix-cube-solver` packet | Reconstruction session boundary is live. | +| Hyper puzzle catalog contract | Implemented now | landed `Hyperspeedcube` `Phase 6R-A` | Narrow retained hyper-puzzle catalog slice is live. | +| Tiling topology and geometry-family contract | Implemented now | landed `MagicTile` `Phase 6R-D` | Narrow retained non-Euclidean topology slice is live. | +| Provider-backed recognition session boundary | Implemented now | first-party current code | `UHyperTwistHttpVisionClient` and normalized recognition envelopes are live first-party seams. | +| Speech transcript session boundary | Implemented now | landed `whisper.cpp` `Phase 6R-E` | Transcript sessions, utterance envelopes, and speech-health seams are live. | +| Analytics/reporting surfaces | Implemented now | landed analytics/reporting packets | Reporting is real, but bounded to accepted retained slices. | +| Browser/spatial/media adjunct surfaces | Implemented now | landed `three.js`, `react-three-fiber`, `xr`, `model-viewer`, `remotion` packets | These are implemented bounded families, not proof of unlimited browser-shell parity. | + +## Feature families + +The rest of this registry is normalized by feature family rather than donor +repo. + +### 1. Puzzle runtime, notation, and replay + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Native puzzle-state runtime | Implemented now | first-party runtime + landed donor packets | Core product identity. | +| Classic-cubing semantic/runtime adapter | Implemented now | landed `cubing/cubing.js` packet | Live adapter family. | +| Replay shell and timeline | Implemented now | landed `cubing/twisty.js` bounded packets | Replay/runtime viewer family is real. | +| Algorithm/training semantic lane | Implemented now | landed `cubing/alg.js` bounded packets | Semantic/training contract is real. | +| Hyper puzzle catalog | Implemented now | `Hyperspeedcube` bounded packet | Current realized hyper-puzzle entry slice. | +| Hyper puzzle DSL, notation/serialization, replay verification, and stats-shape | Deep-source grounded retained | `Hyperspeedcube` retained row | Still deferred after the narrow `Phase 6R-A` landing. | + +### 2. Physical recognition and reconstruction + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Calibration profile and ordered face observation | Implemented now | `qbr` bounded packet | Live bounded recognition intake. | +| Committed-face reconstruction session | Implemented now | `rubix-cube-solver` bounded packet | Live bounded reconstruction seam. | +| Provider-backed recognition service contract | Implemented now | first-party recognition client surfaces | First-party normalized recognition session boundary is real. | +| Multi-face correction/explanation shell | Deep-source grounded retained | `qbr`, `rubix-cube-solver` retained remainder | Not yet widened into the live shell. | +| Browser/webcam recognition shell | Deep-source grounded retained | `rubix-cube-solver` retained remainder | Retained, not shipped. | + +### 3. Training, coaching, and progression cockpit + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Training sessions, method drills, and coaching dashboard | Implemented now | first-party training/coaching surfaces | Current live cockpit anchor. | +| Follow-up templates, session queues, and coach summaries | Implemented now | first-party current code | Real first-party orchestration surface. | +| Embodied companion/narration adjunct | Implemented now | landed `TalkingHead` packet | Live bounded avatar/narration family. | +| Broader long-horizon coach memory and cognitive state | Deep-source grounded retained | first-party target + memory doctrine | Doctrine-governed future widening; not yet a mature memory system. | + +### 4. Catalog, curriculum, and knowledge + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Imported training catalog packs | Implemented now | first-party current code | Already in product. | +| Hypercubing knowledge/reference bundle | Implemented now | landed knowledge packet + first-party consumption | Live knowledge family. | +| Curated training atlas / wiki-like memory | Deep-source grounded retained | first-party target + memory doctrine | Not yet source-grounded enough for stronger external-lane ownership. | + +### 5. Publication, leaderboard, entitlement, and social training + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Publication/leaderboard projection | Implemented now | landed `kash/cubedesk` `Bound 4` | Live bounded slice. | +| Entitlement gating | Implemented now | landed `kash/cubedesk` `Bound 4` | Live bounded slice. | +| Local social challenge bundle | Implemented now | landed `kash/cubedesk` `Bound 5` | Live bounded slice. | +| Broader admin/report lane | Deep-source grounded retained | repo-local justification required | `Bound 6` is deferred and not currently justified for implementation. | + +### 6. Hyper puzzle topology and non-Euclidean runtime + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Legacy `4D` interaction/history/macro/provenance boundary | Implemented now | landed `magiccube4d` packet | Already part of current product truth. | +| Tiling topology and geometry-family contract | Implemented now | landed `MagicTile` packet | New bounded widening is live. | +| Transform-aware macro remapping and broad non-Euclidean interaction shell | Deep-source grounded retained | `MagicTile` retained remainder | Not yet promoted into live broad interaction ownership. | + +### 7. Speech input and voice sidecars + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Speech transcript session boundary | Implemented now | landed `whisper.cpp` packet | Current bounded STT truth. | +| Provider-backed speech session health and transcript envelopes | Implemented now | first-party speech client surfaces | Current first-party speech seam. | +| Python transcription-service orchestration | Deep-source grounded retained | `faster-whisper` queue head | Next bounded queue move, not yet implemented. | +| Voice output / narration sidecars | Deep-source grounded retained | `piper`, `coqui-ai/TTS` retained rows | Retained for later bounded work. | +| Broad live microphone shell and downloadable payload shipping | Deep-source grounded retained | speech stack retained remainder | Explicitly deferred. | + +### 8. Provider-neutral AI/provider routing + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| First-party provider-neutral speech/vision contract | Implemented now | first-party recognition/speech client seams | Current bounded provider/session truth. | +| Provider-neutral BYOK/profile model | Deep-source grounded retained | doctrine-defined first-party target | Not yet fully realized in code. | +| OpenAI-compatible custom endpoint support | Deep-source grounded retained | doctrine-defined first-party target | First-class target, not yet fully realized in code. | +| Normalized usage/cost/routing surface | Deep-source grounded retained | doctrine-defined first-party target | Retained governance target, not live product truth yet. | +| Provider-specific overlays | Shallow placeholder | future provider-family work only | Keep internal until source-grounded and normalized. | + +### 9. Memory, continuity, notes, and provenance + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| Session continuity and workspace recall fragments | Implemented now | first-party runtime/training surfaces | Real but not yet a full memory federation. | +| Provenance-aware training/replay/publication state | Implemented now | first-party contract/provenance surfaces | Existing product truth. | +| Layered memory federation | Deep-source grounded retained | memory doctrine | Governing taxonomy exists; lane widening remains future work. | +| User-authored note lane | Deep-source grounded retained | memory doctrine, owner unresolved | Do not describe as shipped. | +| Compact memory views / reducers | Deep-source grounded retained | optional-assistive + memory doctrine | Must remain derived and optional. | + +### 10. Skills and optional assistive layer + +| Feature | Status | Primary authority | Notes | +|---|---|---|---| +| First-party skill registry and enable/disable governance | Deep-source grounded retained | skillization doctrine | Required base; not implemented yet. | +| Review/analyzer skill family | Deep-source grounded retained | skillization doctrine | Planned after substrate and off-state controls. | +| Memory/continuity skill family | Deep-source grounded retained | skillization + memory doctrine | Retained, not implemented. | +| Provider/ops skill family | Deep-source grounded retained | skillization + provider doctrine | Retained, not implemented. | +| Domain/creative skill packs | Shallow placeholder | skillization doctrine only | Keep internal until source-grounded. | + +## Shallow-known placeholder families + +These are intentionally coarse placeholders. + +They exist because the portfolio already signals the family strongly enough +that later extraction work should not forget it. + +They are not yet source-grounded enough to promote as retained product +capabilities. + +| Placeholder family | Current status | Use rule | +|---|---|---| +| Provider-specific overlay/dashboard variants | Shallow placeholder | Internal stub only until normalized and source-grounded. | +| Broader memory-donor families not yet evaluated for HyperTwist | Shallow placeholder | Internal stub only. | +| Broad skill-pack catalog beyond initial governance target | Shallow placeholder | Internal stub only. | +| Broader assistant-platform or agent-control families | Shallow placeholder | Internal stub only. | + +## Maintenance rule + +When a new packet materially adds or changes a normalized feature: + +1. update the relevant family row here +2. upgrade any affected placeholder if it becomes source-grounded +3. preserve the status-tier distinction +4. do not silently promote a placeholder into retained or implemented truth + +## Summary + +This file is the shortest path from packet authority to later user-facing +explanation. + +It should be the default extraction surface for: + +- manuals +- onboarding +- help surfaces +- roadmap summaries +- product copy drafts + +provided the status taxonomy above is preserved exactly. diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/PRD.md b/docs/v6_5_deep_manual_pack/HyperTwist/PRD.md index ead5ebc..47811ae 100644 --- a/docs/v6_5_deep_manual_pack/HyperTwist/PRD.md +++ b/docs/v6_5_deep_manual_pack/HyperTwist/PRD.md @@ -1,24 +1,48 @@ -# HyperTwist — PRD.md +# HyperTwist - PRD.md ## Product definition -HyperTwist is a native cube and hypercube training environment that combines recognition, replay, simulation, coaching, and immersive instruction. +HyperTwist is a native cube and hypercube training environment that combines: + +- physical recognition and reconstruction +- replay and explanation +- training/coaching orchestration +- hyper puzzle simulation +- publication/social training surfaces +- bounded voice/speech sidecars + +## Canonical discovery surfaces + +Use these before expanding or describing product truth: + +- `FEATURE_REGISTRY.md` for normalized feature extraction and confidence tiers +- `ROADMAP.md` for current sequencing truth +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` for + current landed runtime anchors +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` + for memory lane taxonomy and sequencing +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` + for provider-neutral/BYOK rules +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` + for skill-layer rollout ## Current product-state truth -The current product should be described carefully: +The current product must be described carefully. -- HyperTwist already has real first-party owned implementation -- but only a small subset of the retained repo portfolio is currently verified as live in checked Unreal surfaces -- that live set is six repos wide: - - five permissive `MIT` lanes - - one restrictive lane, `onionhoney/roux-trainers`, already properly clean-roomed and implemented +HyperTwist already has real first-party owned implementation, but later +manual/marketing work must distinguish: -This means product planning must distinguish: +- implemented now +- deep-source grounded retained capability +- shallow placeholder capability -- what is already landed -- what is still retained for evaluation -- what is still only a future, benchmark, or discard candidate +The canonical normalized surface for that distinction is: + +- `FEATURE_REGISTRY.md` + +Do not infer product truth from donor presence, queue position, or prompt-pack +presence. ## Users @@ -33,23 +57,32 @@ This means product planning must distinguish: - weak solve analysis in existing tools - separation between physical practice and virtual analysis -- insufficient serious support for higher-dimensional practice -- fragmented training, timing, simulation, and replay tools +- insufficient support for higher-dimensional practice +- fragmented training, timing, recognition, replay, and coaching flows ## Core feature families -- physical cube recognition -- solve reconstruction and replay -- algorithm and drill training -- AI coaching -- hypercube simulation -- progression and analytics -- immersive training -- export and sharing +- physical cube recognition and reconstruction +- replay and state explanation +- algorithm/drill training and session control +- coaching/progression +- hyper puzzle catalog/topology/runtime +- publication/challenge/social training surfaces +- analytics/reporting and provenance +- bounded speech/voice sidecars + +## Product guardrails + +- packet docs and live code beat summaries when conflicts exist +- provider-specific donor patterns must not define the top-level provider + contract +- compacted or assistive-transformed outputs must remain derived, not + authoritative +- skills must remain optional assistive layers, not mandatory product truth ## Success criteria - users measurably improve faster - higher-dimensional users take the platform seriously -- the physical and virtual pillars reinforce each other -- the product feels native, polished, and coherent +- physical and virtual practice reinforce each other +- the product feels native, rigorous, and coherent diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/PROVENANCE_AND_TRUST_MODEL.md b/docs/v6_5_deep_manual_pack/HyperTwist/PROVENANCE_AND_TRUST_MODEL.md new file mode 100644 index 0000000..64bbbad --- /dev/null +++ b/docs/v6_5_deep_manual_pack/HyperTwist/PROVENANCE_AND_TRUST_MODEL.md @@ -0,0 +1,111 @@ +# HyperTwist - PROVENANCE_AND_TRUST_MODEL.md + +## Purpose + +Define how provenance, custody, and trust state should appear inside +HyperTwist. + +This is not only a reporting/export concern. It is a training, replay, +recognition, coaching, and publication concern. + +## Core rule + +Any action-bearing, evidence-bearing, or recommendation-bearing object should +be able to answer: + +- what is this +- where did it come from +- who/what produced it +- when +- under what custody class +- what trust caveats apply +- how it links to replay/evidence/state history + +## Minimum visible provenance fields + +Where relevant, HyperTwist should preserve and surface: + +- object identity +- source repo/path/artifact origin +- producer/service/tool identity +- timestamp and session/run identity +- custody class +- approval/correction history +- warning/partiality state +- replay/evidence linkage + +## Custody classes + +HyperTwist should be able to distinguish at least: + +- first-party authoritative +- permissive donor-derived +- boundary-sensitive first-party derived +- restrictive clean-room-derived +- external live service output +- user-authored +- unresolved/untrusted + +## Trust posture examples + +Typical trust/state markers include: + +- observed +- inferred +- corrected +- replayable +- verified +- derived +- externally supplied +- approval required +- stale +- disconnected + +## Product implication + +Provenance/trust is not a late reporting embellishment. + +It should influence: + +- recognition correction surfaces +- replay/history views +- coaching explanations +- challenge/publication surfaces +- import/export/report builders +- compact memory views + +## Derived compacted state rule + +If HyperTwist introduces compacted, reduced, summarized, or otherwise +assistive-transformed variants of a raw object, those variants should surface +as derived state rather than replacing the authoritative source object. + +The governing authorities are: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` + +Companion extraction surface: + +- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\FEATURE_REGISTRY.md` + +## Memory-specific consequence + +The memory doctrine defines provenance/trust-ledger memory as a distinct lane +and requires provenance to survive: + +- chronicle capture +- continuity/resume packets +- cognitive coach-state consolidation +- knowledge promotion +- derived compact views + +## Redaction and publication + +Publication surfaces should preserve enough provenance to remain auditable +while still allowing: + +- redaction +- audience scoping +- clean-room-safe publication +- policy-bound evidence export diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md b/docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md index 214509f..266945f 100644 --- a/docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md +++ b/docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md @@ -2,6 +2,18 @@ Status update on `2026-05-21`: +Canonical discovery surfaces for roadmap interpretation: + +- `FEATURE_REGISTRY.md` for normalized feature families and confidence tiers +- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` for + current landed runtime anchors +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` + for memory-lane sequencing +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` + for provider/BYOK sequencing +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` + for skill-layer sequencing + - the canonical HyperTwist repo-row portfolio is now treated as `75` rows, not `71` - currently implemented rows are now `28`, not `20` - four of the additional current implemented rows are the later-landed restrictive clean-room lanes: diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/SKILLS.md b/docs/v6_5_deep_manual_pack/HyperTwist/SKILLS.md index 9dd0cea..31ed23a 100644 --- a/docs/v6_5_deep_manual_pack/HyperTwist/SKILLS.md +++ b/docs/v6_5_deep_manual_pack/HyperTwist/SKILLS.md @@ -1,52 +1,130 @@ -# HyperTwist — SKILLS.md +# HyperTwist - SKILLS.md -## Core competencies +## Purpose + +This file is the HyperTwist-facing discovery surface for skill families and +skill governance. + +It is not a claim that HyperTwist already ships a broad live skill layer. + +Use the governing doctrine for rollout, command-surface rules, and off-state +requirements: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` + +Companion doctrines: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md` +- `FEATURE_REGISTRY.md` + +## Product rule + +Skills are optional assistive layers. + +They must: + +- sit on top of first-party commands/services +- remain user-deactivatable +- remain removable +- never become the primary truth of a feature + +## Current status tiers + +Use the feature-registry confidence split here too: + +- `Implemented now` +- `Deep-source grounded retained` +- `Shallow placeholder` + +Do not present a planned skill family as a shipped skill layer. + +## Highest-priority retained skill families + +These are retained doctrine-level families, not live implementation claims. + +### First-party skill substrate and governance + +Status: + +- Deep-source grounded retained + +Includes: + +- skill registry/manifest +- enable/disable controls +- provenance/invocation ledger +- validation harness + +### Analyzer and review skills + +Status: + +- Deep-source grounded retained + +Includes: + +- architecture/repo analysis wrappers +- review/diff/plan helpers +- bounded workflow wrappers + +### Memory and continuity skills + +Status: + +- Deep-source grounded retained + +Includes: + +- resume/session skills +- recall/search skills +- compact-view skills + +### Provider and operations skills + +Status: + +- Deep-source grounded retained + +Includes: + +- provider-profile inspection +- BYOK setup +- routing/usage diagnostics + +### Domain skill packs + +Status: + +- Shallow placeholder + +Includes: + +- replay/training packs +- curriculum packs +- media/export packs + +## Core competencies for HyperTwist work + +A coding model working on HyperTwist should still be able to: -A coding model working on HyperTwist must be able to: - inspect simulation engines - understand move/state notation - inspect replay and trainer code -- inspect CV recognition stacks -- reason about user progression systems +- inspect recognition stacks +- reason about progression/coaching systems - distinguish educational UX from simulation correctness - propose Unreal-native implementation paths -## Work products +## Immediate next move -For each meaningful repo or subsystem, produce: -- capability summary -- integration mode -- training value -- coaching value -- performance implications -- whether it belongs to physical or hyper pipeline -- what would justify native integration vs sidecar use +The next correct skillization sequence is: -## Domain skills +1. skill registry/manifest contract +2. settings/menu/off-state controls +3. permissive analyzer wrappers +4. clean-room command-contract specs for restrictive lanes -### Simulation -- move representation -- scramble generation -- solver or state engine analysis -- replay model design -- notation and interoperability - -### Recognition -- camera assumptions -- color classification -- uncertainty handling -- state reconstruction -- performance and device assumptions - -### Training -- spaced or repeated practice logic -- progression systems -- analytics -- curriculum scaffolds -- personalized recommendations - -### Immersion -- Unreal scene management -- puzzle manipulation -- XR interactions -- projection and explanatory overlays +Broader memory, provider, and domain skill widening should wait until that +base exists. diff --git a/docs/v6_5_deep_manual_pack/HyperTwist/WORKBENCH_FEATURE_TARGETS.md b/docs/v6_5_deep_manual_pack/HyperTwist/WORKBENCH_FEATURE_TARGETS.md new file mode 100644 index 0000000..22a387f --- /dev/null +++ b/docs/v6_5_deep_manual_pack/HyperTwist/WORKBENCH_FEATURE_TARGETS.md @@ -0,0 +1,142 @@ +# HyperTwist - WORKBENCH_FEATURE_TARGETS.md + +## Purpose + +Translate mature workbench capability into clean HyperTwist cockpit targets +without turning HyperTwist into a generic IDE clone or a generic admin +dashboard. + +This file exists because HyperTwist now clearly has an operator/workbench side +in addition to its puzzle/training runtime, and that value must be described +concretely enough that future implementation and repo evaluation do not +underweight it. + +## Core adoption rule + +Adopt capability families, not another product's identity. + +That means: + +- reuse serious workbench ergonomics where they materially help training, + coaching, review, or diagnostics +- do not copy another product literally +- do not let workbench behavior demote the Unreal-native training runtime + +## Visual divergence rule + +HyperTwist should adopt workbench capability without adopting a pane-saturated +generic enterprise shell. + +The target feeling is: + +- focused +- work-first +- training-first +- replay-aware +- inspection-friendly + +not: + +- a generic boxed IDE +- a web admin dashboard with puzzle art attached + +## Canonical workbench targets + +### 1. Unified command and navigation layer + +HyperTwist should have: + +- one command palette +- one object jump/search surface +- recent-context and return-to-context behavior +- search across runs, decks, replays, coach cases, challenge sessions, + content packs, and settings + +### 2. Explorer, bookmarks, and scratch adjuncts + +HyperTwist should support: + +- deck/content explorers +- preview-open behavior for non-destructive inspection +- bookmark lists and mnemonic anchors +- scratch notes/queries/temporary evidence + +### 3. Diff, review, and local recovery + +HyperTwist should support: + +- structured diff/review for training state where useful +- replay comparison +- local-history-style recovery for relevant operator surfaces +- labels before risky apply/import/publish operations + +### 4. Run, session, and live diagnostics + +HyperTwist should support: + +- session management as first-class cockpit value +- service dashboards for recognition, speech, imports, and coaching helpers +- interactive diagnostics tied to one run/session context + +### 5. Testing, coverage, and profiling + +HyperTwist engineering surfaces should support: + +- validation cockpit behavior +- saved test sessions per packet/subsystem +- coverage/profiling/memory surfaces for runtime hot paths + +Important distinction: + +- engineering memory profiling here concerns runtime resources +- product memory lanes are governed separately by the memory doctrine + +### 6. Terminal, external tools, and bounded sidecars + +HyperTwist should support: + +- bounded tool launch +- context-aware sidecar/service inspection +- explicit remote/session governance rather than ad hoc shell escapes + +### 7. Settings, extensions, and optional adjunct governance + +HyperTwist should support: + +- strong settings organization +- separation between user-local and project/shared preferences where relevant +- explicit extension/adjunct governance +- self-service enable/disable control for optional assistive features + +Governing doctrines: + +- `C:\HyperTwist\docs\ops\HYPERTWIST_OPTIONAL_ASSISTIVE_FEATURE_DEACTIVATION_AND_REMOVABILITY_DOCTRINE_2026-05-21.md` +- `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` + +## Mapping into HyperTwist doctrine + +These targets should shape: + +- `PRD.md` +- `ARCHITECTURE.md` +- `ROADMAP.md` +- `FEATURE_REGISTRY.md` +- `CAPABILITY_CONSOLIDATION_DOCTRINE.md` +- `API.md` +- `DEVELOPMENT.md` + +## Guardrail + +The cockpit must remain subordinate to the actual product identity. + +The target is: + +- one training runtime +- one operator cockpit +- many bounded tools + +not: + +- an Unreal skin over a generic IDE +- a detached browser admin panel +- a pile of unrelated panes pretending to cooperate diff --git a/docs/v6_5_deep_manual_pack/README.md b/docs/v6_5_deep_manual_pack/README.md index 94b9f50..1467ecb 100644 --- a/docs/v6_5_deep_manual_pack/README.md +++ b/docs/v6_5_deep_manual_pack/README.md @@ -14,12 +14,18 @@ This pack expands the split v6.4 docs into a more exhaustive project-specific ma ## Authority order 1. `repo_portfolio_unified_v6_3.*` and companion matrices remain repo-row source of truth 2. top-level current-state correction docs such as `HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md`, `HT_REPO_INCORPORATION_AUDIT_2026-05-11.md`, `HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md`, and `HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md` govern current live-truth interpretation for HyperTwist -3. this v6.5 deep manual pack governs project-level architecture and implementation posture -4. v6.4 and earlier project markdowns are lineage and rollback reference only +3. this v6.5 deep manual pack governs project-level architecture and implementation posture, with + `HyperTwist/FEATURE_REGISTRY.md` as the normalized feature extraction surface +4. `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` governs the short + current-runtime implementation readout and pointers to memory/provider/skill doctrines +5. the HyperTwist memory, provider-neutrality, optional-assistive, and skillization doctrine docs + under `C:\HyperTwist\docs\ops\` govern those cross-cutting lanes +6. v6.4 and earlier project markdowns are lineage and rollback reference only ## Project folders Each project contains: - AGENTS.md +- FEATURE_REGISTRY.md - SKILLS.md - ARCHITECTURE.md - API.md