Establish project governance and architecture principles
Dieser Commit ist enthalten in:
@@ -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.
|
||||
In neuem Issue referenzieren
Einen Benutzer sperren