Establish project governance and architecture principles

2026-05-27 20:17:55 +02:00
Commit fcd19ccc6e
@@ -0,0 +1,90 @@
 # AGENTS.md
 ## Project scope
 VG-Environment is a local evidence and runtime observation environment for technically reconstructing consent-related browser activity.
 The project is focused on:
 - runtime observation
 - consent-state capture
 - request observation
 - GVL/version tracking
 - evidence preservation
 - technically reproducible reconstruction
 The project is NOT focused on:
 - AI-generated interpretations
 - speculative conclusions
 - marketing-style analytics
 - legal automation
 - risk scoring
 - black-box analysis
 Observe shows:
 "What was technically observed?"
 Analysis answers:
 "What could this mean?"
 These responsibilities must remain separated.
 ---
 ## Development principles
 - Runtime stability is more important than feature count.
 - Small incremental changes are preferred over large refactors.
 - Avoid monster files.
 - Avoid architecture expansion without concrete user value.
 - Human-understandable evidence visibility is more important than technical complexity.
 - Existing runtime/evidence data should be used before adding new capture pipelines.
 - Do not turn Observe into a hidden analysis engine.
 ---
 ## Database rules
 - IndexedDB migrations must remain additive.
 - No destructive schema operations without explicit approval.
 - No DROP/TRUNCATE-style logic.
 - No automatic cleanup of evidence data.
 - Avoid DB full scans whenever possible.
 - Evidence data must not be silently modified.
 ---
 ## Git and workflow rules
 - Git control remains with the user.
 - Do not automate git operations.
 - Do not create commits automatically.
 - Do not rewrite git history.
 - Workspaces are intentional architectural boundaries.
 - Respect module and workspace responsibilities.
 ---
 ## Node.js / npm policy
 Node.js and npm are allowed only as local development and testing tools.
 Allowed examples:
 - web-ext
 - eslint
 - prettier
 - local syntax checks
 - local test scripts
 - development automation
 Strict rules:
 - Do not add npm runtime dependencies.
 - Do not import npm packages from src/.
 - Do not introduce bundlers unless explicitly requested.
 - Do not require a build step for the extension.
 - Do not commit node_modules/.
 - package.json is allowed only for devDependencies and local scripts.
 - Productive extension code must remain Vanilla JavaScript using WebExtension APIs.
 - The extension must run in Firefox without Node.js installed.
 Node.js may assist development tooling.
 It must never become part of the productive runtime architecture.
@@ -0,0 +1,159 @@
 # VG-Environment — Project Principles
 ## Core purpose
 VG-Environment is a local evidence and runtime reconstruction environment for consent-related browser activity.
 The primary project goal is NOT large-scale telemetry collection or abstract tracking analytics.
 The primary goal is:
 To technically reconstruct what was actually observed after a concrete consent decision inside the browser runtime.
 Core user question:
 "What exactly happened technically after I was shown a consent dialog and made a specific consent decision?"
 VG-Environment therefore focuses on:
 - technically observable runtime behavior
 - consent-state reconstruction
 - request observation
 - GVL/version preservation
 - evidence-oriented reproducibility
 - human-understandable technical reconstruction
 ---
 ## Evidence-first philosophy
 VG-Environment prioritizes:
 - observable technical reality
 - reproducibility
 - transparency
 - evidence preservation
 - explainability
 - low interpretation bias
 The project must avoid:
 - black-box logic
 - AI-generated assumptions
 - speculative conclusions
 - hidden heuristics
 - non-reproducible scoring systems
 - unverifiable classifications
 The browser runtime is treated as the primary source of truth.
 ---
 ## Consent-centered architecture
 VG-Environment is fundamentally consent-centered.
 The project is NOT primarily:
 - request-centered
 - statistics-centered
 - telemetry-centered
 - crawler-centered
 Requests are treated as:
 observed technical follow-up activity related to concrete consent states.
 The central reconstruction unit is therefore:
 a concrete consent event and its technically observable consequences.
 ---
 ## Observe vs Analysis
 VG-Observe is responsible for:
 - runtime visibility
 - technical observation
 - evidence capture
 - temporal reconstruction
 - technical correlation visibility
 - human-understandable evidence presentation
 VG-Observe may:
 - show technical facts
 - show observable relations
 - show temporal ordering
 - show observed request activity
 - show observed consent propagation
 VG-Observe must NOT:
 - speculate
 - classify risk
 - infer motives
 - generate legal conclusions
 - claim causality
 - invent behavioral models
 - silently interpret observations
 VG-Analysis is responsible for:
 - interpretation
 - discrepancy analysis
 - pattern analysis
 - hypothesis generation
 - deeper correlation models
 - later analytical evaluation
 The separation between Observe and Analysis is a core architectural rule.
 ---
 ## Human-understandable evidence
 The project must not devolve into:
 - raw database dumps
 - table graveyards
 - developer-only telemetry views
 Technical evidence must remain understandable to humans.
 Preferred UX principle:
 - first orientation and understandable context
 - then technical detail
 - then raw evidence/debug data
 Raw technical detail remains important,
 but must not dominate the primary user experience.
 ---
 ## Architectural direction
 VG-Environment intentionally prefers:
 - small modular structures
 - explicit logic
 - low hidden complexity
 - direct inspectability
 - Vanilla JavaScript
 - minimal runtime dependencies
 - local-first workflows
 The project intentionally avoids unnecessary:
 - framework complexity
 - bundler dependency
 - hidden build pipelines
 - runtime abstraction layers
 - architecture inflation
 Long-term maintainability and inspectability are more important than trend-driven architecture decisions.
 ---
 ## Evidence integrity
 Evidence integrity has priority over convenience.
 The system must avoid:
 - silent evidence modification
 - destructive cleanup logic
 - hidden data rewriting
 - opaque processing pipelines
 Stored observations should remain reproducible and explainable whenever possible.
 The project is designed as a technical reconstruction environment,
 not as an automated decision engine.
@@ -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.