VG-Environment/AGENTS.md

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.