Andris Enins
91cd18aec6
Backend (Spring Boot 3.2 / Java 21 / PostgreSQL): - JWT auth with BCrypt password hashing - User profile + Mifflin-St Jeor BMR calculator - Food search + barcode via OpenFoodFacts API with local cache - Meal CRUD with user data isolation and ownership checks - AI photo analysis (OpenAI Vision) with confidence intervals - AI correction feedback loop for personalisation - Flyway DB migrations + RFC-7807 error responses Mobile (React Native / TypeScript): - Full navigation stack (Auth → Tabs → Home stack) - Design tokens (WCAG 2.2 AA colours, 8px grid, 48px touch targets) - 10 screens: Login, Register, Home, Search, Camera, AI Result, Edit Meal, Daily Details, History, Profile - Confidence-aware calorie display (kcal ± range) - Repeat last meal shortcut + macro tracking Docs: - docs/PLAN-AND-REQUIREMENTS.md - docs/traceability.csv (35 requirements, all Implemented)
257 lines
10 KiB
Markdown
257 lines
10 KiB
Markdown
# 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](../../.github/virsaitis-definition-library.md) — 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](../../.github/copilot-modules/agent-standards.md)
|
|
- **Core Policies**: [.github/copilot-modules/core-policies.md](../../.github/copilot-modules/core-policies.md)
|
|
- **Functional Requirements**: [functional-spec.md](functional-spec.md)
|
|
- **Traceability Matrix**: [traceability.csv](traceability.csv)
|
|
|
|
---
|
|
|
|
*Virsaitis Glossary v2.0.0*
|
|
*Terminology reference for three-layer AI governance system*
|