Establish project governance and architecture principles

docs/architecture/workspace-model.md

@@ -0,0 +1,196 @@
+# VG-Environment — Workspace Model
+
+## Purpose of workspace separation
+
+VG-Environment intentionally uses multiple workspaces and chats as architectural boundaries.
+
+The separation is not organizational overhead.
+
+It exists to:
+- reduce context overload
+- protect architectural clarity
+- separate responsibilities
+- prevent feature drift
+- keep modules understandable
+- avoid uncontrolled coupling
+- maintain long-term project coherence
+
+Workspaces are therefore treated as:
+intentional architectural control structures.
+
+---
+
+## Role of orchestration
+
+Orchestration is responsible for:
+- architectural direction
+- project coherence
+- responsibility boundaries
+- long-term consistency
+- strategic prioritization
+- preventing uncontrolled feature growth
+- protecting Observe/Analysis separation
+
+Orchestration is NOT:
+- the primary implementation workspace
+- the primary Codex coding workspace
+- the place for uncontrolled experimentation
+
+Implementation decisions should follow architectural guidance,
+not replace it.
+
+---
+
+## VG-Core
+
+VG-Core contains neutral infrastructure.
+
+Examples:
+- storage infrastructure
+- export infrastructure
+- helper utilities
+- platform abstractions
+- reusable technical primitives
+- runtime-independent shared logic
+
+VG-Core should remain:
+- generic
+- reusable
+- technically neutral
+
+VG-Core must avoid:
+- Observe-specific UX logic
+- analysis heuristics
+- interpretation logic
+- feature-specific UI coupling
+
+---
+
+## VG-Observe
+
+VG-Observe is responsible for runtime visibility and technical evidence observation.
+
+Observe focuses on:
+- technically observable browser behavior
+- consent-state visibility
+- request observation
+- runtime reconstruction
+- evidence-oriented presentation
+- technical temporal relations
+
+Observe answers:
+"What was technically observed?"
+
+Observe must remain:
+- technically grounded
+- reproducible
+- explainable
+- interpretation-minimal
+
+Observe must NOT drift into:
+- speculative analysis
+- scoring systems
+- behavioral interpretation
+- legal evaluation
+- hidden heuristics
+- AI-generated assumptions
+
+Observe is evidence-oriented,
+not conclusion-oriented.
+
+---
+
+## VG-Analysis
+
+VG-Analysis is intentionally separated from Observe.
+
+Analysis is responsible for:
+- interpretation
+- discrepancy analysis
+- pattern recognition
+- higher-level correlation models
+- hypothesis generation
+- analytical reconstruction
+
+Analysis answers:
+"What could this technically mean?"
+
+Analysis may operate on:
+- aggregated observations
+- reconstructed sequences
+- comparison logic
+- repeated runtime behavior
+- later evidence evaluation
+
+Observe must not silently absorb Analysis responsibilities.
+
+---
+
+## VG-Graph
+
+VG-Graph is responsible for relationship and network visualization.
+
+Examples:
+- origin relationships
+- vendor relationships
+- consent propagation structures
+- communication topology
+- runtime interaction visualization
+
+VG-Graph should visualize existing observations,
+not invent meaning.
+
+---
+
+## VG-Block
+
+VG-Block is intentionally separated from observation logic.
+
+VG-Block may later contain:
+- blocking logic
+- rewrite/testing logic
+- intervention tooling
+- experimental runtime manipulation
+
+Observation and intervention must remain separated.
+
+A system should not silently modify the same runtime it documents.
+
+---
+
+## Workspace evolution
+
+Additional workspaces are expected over time.
+
+Workspace splitting is considered healthy when:
+- context overload increases
+- responsibilities blur
+- architecture becomes unstable
+- implementation and orchestration begin mixing
+- Observe and Analysis start overlapping
+
+Workspace separation is therefore treated as:
+a stability mechanism,
+not a workflow inconvenience.
+
+---
+
+## Long-term architectural principle
+
+VG-Environment is intended to evolve as:
+- a technically understandable
+- evidence-oriented
+- locally controlled
+- reproducible
+- inspectable
+
+runtime reconstruction environment.
+
+The project must resist:
+- uncontrolled architecture expansion
+- feature accumulation without user value
+- hidden complexity growth
+- loss of explainability
+- blurred module responsibilities
+
+Architectural clarity is considered a core project asset.