calorie-counter/virsaitis-requirements/glossary.md

Virsaitis Glossary

Version: 2.0.0 Status: Draft Updated: 2026-02-17

---

Purpose

Defines terminology used throughout Virsaitis project to ensure consistent understanding across all stakeholders.

See also: Definition Library — authoritative definitions with consequence chains for AI governance terms.

---

A

Agent

Markdown-based behavioral control document (Agent.md) that provides governance instructions to AI assistants. Uses atomic sentence structure for 95%+ comprehension. Located in .github/agents/.

Agent Mode

VS Code feature (1.109+) enabling custom AI assistants with specialized behaviors defined by Agent files.

Atomic Sentence

Sentence expressing exactly one concept. Characteristics: single subject-verb-object, <80 characters, no compound clauses, standalone comprehensibility. Improves AI comprehension by 30%.

Audit Log

Chronological record of governance events (file access, violations, security scans) with timestamp, user, action, resource, outcome. Required for forensic analysis.

---

B

Bootstrap Paradox

Challenge where governance system creator needs override privileges to build the system itself, but production users should not have overrides. Resolved by distinguishing development phase (creator override allowed) from production phase (strict enforcement for all).

---

C

Consequence Chain

Documentation pattern showing impact progression of rule violation: RULE → IMMEDIATE CONSEQUENCE → SYSTEM CONSEQUENCE → BUSINESS CONSEQUENCE → REMEDIATION. Helps AI understand WHY rules exist.

CHIEF (Concentrated Hyper Intelligence Expert Framework)

Full title of Virsaitis Agent. Represents concentrated governance expertise for AI systems.

---

D

Defense in Depth

Security architecture with multiple independent layers: input validation, business logic validation, MCP validation, Extension validation, audit logging. If one layer fails, others still protect.

Discovery-First Workflow

11-step process preventing AI hallucination: DISCOVER → READ → SEARCH → VALIDATE → PLAN → CONFIRM → EXECUTE → TEST → UPDATE → VALIDATE → CONFIRM. Discovered facts more accurate than assumptions.

---

E

Extension

VS Code Extension component of Virsaitis. Intercepts file saves, displays shield icons, communicates with MCP server for validation. Final enforcement layer for user manual edits.

---

F

False Negative

Security scan failure where real threat not detected (e.g., secret in code but scanner misses it). Target: 0% false negatives for secret detection.

False Positive

Governance alert where no actual violation exists (e.g., legitimate code flagged as secret). Target: <5% false positives for user experience.

---

G

Governance Compliance

Percentage of operations following governance rules. Target: ≥95% compliance measured by TIER-0 violations per month.

---

H

Hub-and-Spoke Architecture

Modular governance structure with lean hub (<500 tokens) referencing focused modules (<2500 tokens each) loaded on-demand. Reduces token usage 60% vs monolithic approach.

---

I

ImplementationRef

Column in traceability.csv mapping REQ-ID to file path and line numbers where requirement code exists. Enables bidirectional traceability.

---

L

Least Privilege

Security principle where components have minimum permissions: read-only by default, write only when validated, execute never without approval. Limits blast radius of compromise.

---

M

MCP (Model Context Protocol)

Standard protocol for AI tool integration. Enables AI assistants to call TypeScript-implemented tools for validation and operations.

MCP Server

TypeScript server implementing governance validation engine. Parses Agent.md rules, validates file operations, scans for secrets, logs audit trail. Central enforcement point.

Machine-Readable Policy Block

Structured section in Agent.md with format [SECTION_NAME]\nKEY=value. Enables MCP server to parse rules programmatically.

Modular Governance

Architecture separating governance into focused modules (core-policies, agent-standards, mcp-standards, etc.) instead of monolithic file. Improves maintainability and reduces token overhead.

---

N

Notable Change

Change worthy of CHANGELOG entry. Includes: new features (Added), bug fixes (Fixed), breaking changes (Changed), security patches (Security), deprecations (Deprecated), removals (Removed).

---

P

Path Traversal

Attack using ../ sequences to access files outside intended directory. Example: ../../../../etc/passwd. Prevented by path validation and normalization.

Protected File

File governed by TIER-0 modification policy. Patterns: .github/copilot-instructions*.md, requirements/**, traceability.csv. Modification blocked without formal approval workflow.

Progressive Disclosure

Documentation pattern with 3 levels: Quick Reference (always visible), Standards & Rules (when invoked), Examples (when requested). Reduces cognitive load.

---

Q

Quality Gate

Automated checkpoint enforcing quality standards. Pre-commit: build, tests, linter, secrets. Pre-merge: coverage ≥70%, security tests 100%, docs updated. Pre-release: E2E tests, packaging, installation.

---

R

ReDoS (Regular Expression Denial of Service)

Attack using crafted input to cause exponential regex execution time via catastrophic backtracking. Example: (a+)+ with aaaaaaaaaaaaaaaaaaaaaaaa! input. Prevented by avoiding nested quantifiers and input length limits.

REQ-ID (Requirement Identifier)

Unique identifier for requirement. Format: REQ-[A-Z]{2,4}-[0-9]{3}. Examples: REQ-GOV-001 (governance), REQ-SEC-001 (security), REQ-MCP-001 (MCP server). Enables traceability.

---

S

Secret Scanning

Automated detection of hardcoded credentials in code. Patterns: API keys, AWS keys, private keys, GitHub tokens, JWT, database URLs. Target: 100% detection rate (zero false negatives).

Shield Icon

Visual indicator (🛡️) displayed in VS Code gutter or file tree for protected files. Prevents accidental modification attempts.

Skill (Agent Skill)

Native VS Code feature defining domain-specific AI expertise. Format: SKILL.md with YAML frontmatter. Virsaitis defines 6 core skills: python-development, security-controls, requirements-engineering, testing-validation, governance-compliance, typescript-development.

Smart Context Loading

Pattern where AI loads hub + relevant 2-3 modules based on task, not all modules. Example: Python task loads core-policies + agent-standards + python module only.

---

T

TDD (Test-Driven Development)

Development cycle: write failing test (red) → implement code (green) → improve design (refactor). Reduces defects 40-80%.

TestRef

Column in traceability.csv mapping REQ-ID to test file path and test names validating requirement implementation. Completes traceability bidirectional relationship.

TIER System

Four-level governance classification:

• TIER-0 (Safety-Critical): BLOCK operation, zero tolerance, formal approval workflow required
• TIER-1 (Code-Breaking): WARN + CONFIRM, minimal compromise allowed
• TIER-2 (Quality Standard): INFO + SUGGEST, acceptable tradeoffs with justification
• TIER-3 (Enhancement): Best effort, negotiable based on resources

Token Efficiency

Measure of context window usage. Monolithic governance: ~6000 tokens. Hub-and-spoke: Hub ~500 + 2-3 modules ~2000-3000 = ~2500-3500 total (60% reduction).

Traceability Matrix

CSV file mapping REQ-ID → ImplementationRef → TestRef. Enables verification that all requirements implemented and tested. Bidirectional: can find tests from requirement or requirements from code file.

---

U

Uncertainty Response Pattern

AI behavior when situation ambiguous. Response: CONFIRM_NEEDED: [specific question]. WAIT for user clarification. DO NOT guess or assume. Prevents hallucination.

---

V

Virsaitis

Latvian word meaning "Chief" or "Leader". Project name for three-layer AI governance system achieving 95%+ compliance through Agent, MCP Server, and VS Code Extension.

VSIX (Visual Studio Extension)

Package format for VS Code extensions. Contains code, dependencies, resources in single .vsix file. Installed via Extensions view or code --install-extension.

---

W

Workflow Pattern

Defined sequence of steps AI must follow. Virsaitis defines 11-step discovery-first workflow preventing hallucination and ensuring validation at each stage.

---

Acronyms

Acronym	Expansion	Definition
AC	Acceptance Criteria	Testable conditions determining requirement satisfaction
API	Application Programming Interface	Contract for software communication
CHIEF	Concentrated Hyper Intelligence Expert Framework	Full title of Virsaitis Agent
CI	Continuous Integration	Automated build/test on code commit
CSV	Comma-Separated Values	Text format for tabular data
E2E	End-to-End	Testing complete user workflow
HTTP	Hypertext Transfer Protocol	Web communication protocol
JWT	JSON Web Token	Secure token format for authentication
MCP	Model Context Protocol	Standard for AI tool integration
NFR	Non-Functional Requirement	Quality attribute (performance, scalability)
PII	Personally Identifiable Information	Data identifying individual (email, SSN)
REQ-ID	Requirement Identifier	Unique requirement reference
ReDoS	Regular Expression Denial of Service	Attack via catastrophic backtracking
TDD	Test-Driven Development	Write tests before implementation
TLS	Transport Layer Security	Cryptographic protocol for network security
VSIX	Visual Studio Extension	VS Code extension package format
YAML	YAML Ain't Markup Language	Human-readable data serialization
XSS	Cross-Site Scripting	Injection attack via malicious scripts

---

References

• Agent Standards: .github/copilot-modules/agent-standards.md
• Core Policies: .github/copilot-modules/core-policies.md
• Functional Requirements: functional-spec.md
• Traceability Matrix: traceability.csv

---

Virsaitis Glossary v2.0.0 Terminology reference for three-layer AI governance system