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)
339 lines
10 KiB
Markdown
339 lines
10 KiB
Markdown
TIER-0 rules cannot be overridden. When in doubt, BLOCK the operation and ask.
|
||
|
||
# Core Policies - Virsaitis Governance
|
||
|
||
**Module**: Core Policies
|
||
**Load**: ALWAYS (required for all tasks)
|
||
**Version**: 3.0.0
|
||
**Updated**: 2026-02-17
|
||
|
||
---
|
||
|
||
## 🎯 Purpose
|
||
|
||
Defines TIER enforcement system, protected files, and fundamental governance rules that apply across all Virsaitis components.
|
||
|
||
---
|
||
|
||
## 🤖 Machine Policy
|
||
|
||
```
|
||
[ENFORCEMENT_TIERS]
|
||
TIER_0=safety_critical (BLOCK, zero_compromise)
|
||
TIER_1=code_breaking (WARN+CONFIRM, minimal_compromise)
|
||
TIER_2=quality_standards (WARN+SUGGEST, acceptable_tradeoffs)
|
||
TIER_3=enhancements (INFO, negotiable)
|
||
|
||
[PROTECTED_FILES]
|
||
PATTERN_1=.github/copilot-instructions.md
|
||
PATTERN_2=.github/copilot-modules/**/*.md
|
||
PATTERN_3=.github/agents/*.agent.md
|
||
|
||
[MODIFICATION_CONTROL]
|
||
APPROVAL_REQUIRED=true
|
||
OVERRIDE_TOKEN=required
|
||
AUDIT_LOG=all_access
|
||
```
|
||
|
||
---
|
||
|
||
## 🚨 TIER-0: Safety-Critical (NEVER VIOLATE)
|
||
|
||
### Rule 1: Protected File Modification
|
||
|
||
Governance files are the enforcement mechanism itself.
|
||
Modifying them without approval is equivalent to disabling the system.
|
||
|
||
**Protected patterns:**
|
||
- `.github/copilot-instructions.md`
|
||
- `.github/copilot-modules/**/*.md`
|
||
- `.github/agents/*.agent.md`
|
||
- `.github/virsaitis-definition-library.md`
|
||
|
||
**If a modification is attempted:**
|
||
The operation is BLOCKED. The user must use the override workflow.
|
||
Direct edits bypass all safety controls and void audit compliance.
|
||
|
||
**Override workflow:**
|
||
1. Acknowledge the user's need for the change
|
||
2. Explain: this file controls governance enforcement
|
||
3. Draft the exact change for review
|
||
4. Command: "Virsaitis: Request Override" (Extension)
|
||
5. STOP — do not proceed until override is granted
|
||
|
||
**CONSEQUENCE:**
|
||
- **Operation**: BLOCKED immediately
|
||
- **User Impact**: Must request governance override via PR workflow
|
||
- **Technical Impact**: Safety controls bypassed, audit trail broken
|
||
- **Business Impact**: Legal liability, compliance violation, deployment blocked
|
||
- **Remediation**: Create PR with written justification, await approval
|
||
|
||
---
|
||
|
||
### Rule 2: Atomic Sentence Structure (Agent.md)
|
||
|
||
**RULE:**
|
||
Agent files communicate through single-concept statements.
|
||
Compound structures degrade AI parsing accuracy by 30%.
|
||
Every sentence must stand alone without requiring context from adjacent sentences.
|
||
|
||
**REQUIRED FORMAT:**
|
||
```markdown
|
||
✅ GOOD (atomic):
|
||
You must validate file existence.
|
||
File validation prevents NotFoundError.
|
||
Run validation before modification.
|
||
|
||
❌ BAD (compound):
|
||
You must validate file existence before modification
|
||
to prevent NotFoundError, and this should be done
|
||
using the verify_file function which checks both
|
||
path and permissions.
|
||
```
|
||
|
||
**CONSEQUENCE:**
|
||
- **Operation**: Code review rejection
|
||
- **User Impact**: Agent.md changes not merged, rework required
|
||
- **Technical Impact**: AI comprehension drops, rules misinterpreted
|
||
- **Remediation**: Split compound sentences, validate one-concept-per-sentence
|
||
|
||
---
|
||
|
||
### Rule 3: Secret Management
|
||
|
||
**RULE:**
|
||
Credentials, tokens, and private keys are treated as security incidents if found in source.
|
||
|
||
**Patterns that trigger this rule:**
|
||
- Hardcoded passwords, API keys, tokens
|
||
- Database credentials in source code
|
||
- Private keys (.pem, .pfx, .key files)
|
||
- OAuth tokens, session cookies
|
||
- Environment variables with ACTUAL values (examples only)
|
||
|
||
**REQUIRED APPROACH:**
|
||
- Use environment variable REFERENCES only (e.g., `process.env.API_KEY`)
|
||
- Document secret NAMES, never VALUES
|
||
- Reference secret management services (Azure Key Vault, AWS Secrets Manager)
|
||
- Run security scan before every commit
|
||
- Get explicit user confirmation after fixing
|
||
|
||
**WHY:**
|
||
Secrets in Git history cannot be fully removed.
|
||
Exposed credentials create security incidents.
|
||
Security incidents trigger compliance violations.
|
||
Compliance violations have legal consequences.
|
||
|
||
**CONSEQUENCE:**
|
||
- **Operation**: BLOCKED, commit rejected immediately
|
||
- **User Impact**: Must rotate credential within 1 hour, incident report filed
|
||
- **Technical Impact**: Security incident triggered, audit log entry, automated alerts
|
||
- **Business Impact**: Compliance violation, potential data breach, regulatory fines
|
||
- **Remediation**: Remove secret from Git history (git-filter), rotate credential immediately, complete incident report
|
||
|
||
---
|
||
|
||
### Rule 4: MCP/Extension Tool Enforcement
|
||
|
||
**RULE:**
|
||
Use Virsaitis MCP tools for governance-critical operations.
|
||
Native VS Code tools bypass governance validation.
|
||
|
||
**TOOL MAPPING (use Virsaitis version):**
|
||
- Validate file operation → `mcp_virsaitis_validate_operation`
|
||
- Load governance rules → `mcp_virsaitis_read_governance`
|
||
- Refresh rule cache → `mcp_virsaitis_reload_cache`
|
||
- Scan for hardcoded secrets → `mcp_virsaitis_scan_secrets`
|
||
- Validate file path safety → `mcp_virsaitis_validate_path`
|
||
- Validate command safety → `mcp_virsaitis_validate_command`
|
||
- Read audit log → `mcp_virsaitis_read_audit_log`
|
||
- Post-iteration compliance → `mcp_virsaitis_iteration_complete`
|
||
|
||
> ⚡ CHECKPOINT — Is this operation TIER-0? If protected file or secret detected, BLOCK now.
|
||
|
||
**WHY:**
|
||
MCP tools include governance validation hooks.
|
||
Native tools execute without TIER checking.
|
||
Bypassing governance creates audit gaps.
|
||
|
||
**CONSEQUENCE:**
|
||
- **Operation**: Governance validation bypassed
|
||
- **User Impact**: Rules not enforced, potential errors introduced
|
||
- **Technical Impact**: Audit trail incomplete, traceability lost
|
||
- **Business Impact**: Compliance gap in audit logs
|
||
- **Remediation**: Re-run operation using MCP tools, verify governance applied
|
||
|
||
**IF MCP TOOL UNAVAILABLE:**
|
||
1. STOP operation immediately
|
||
2. Report: "Virsaitis MCP governance tool not available"
|
||
3. DO NOT use native tool as fallback
|
||
4. Request: User install/configure Virsaitis MCP server
|
||
5. Wait for MCP availability before proceeding
|
||
|
||
---
|
||
|
||
## ⚠️ TIER-1: Critical Operations
|
||
|
||
**Definition**: Operations that can break code functionality or violate critical requirements.
|
||
|
||
**Enforcement**: WARN + CONFIRM (require explicit user confirmation before proceeding)
|
||
|
||
**Examples**:
|
||
- Component-specific coding standards (indentation, encoding)
|
||
- REQ-ID traceability (every feature must reference requirement)
|
||
- CHANGELOG maintenance (every change must be documented)
|
||
- Test coverage targets (≥70% overall, 100% security-critical)
|
||
|
||
**Response Pattern**:
|
||
```
|
||
⚠️ TIER-1 VIOLATION DETECTED
|
||
|
||
RULE: [Rule name]
|
||
ISSUE: [What was violated]
|
||
CONSEQUENCE: [Impact if allowed]
|
||
|
||
CONFIRM: Do you want to proceed anyway? (yes/no)
|
||
RECOMMENDATION: [Better approach]
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 TIER-2: Quality Standards
|
||
|
||
**Definition**: Best practices that improve maintainability and quality but don't break functionality.
|
||
|
||
**Enforcement**: WARN + SUGGEST (provide warning with suggested fix, allow user to proceed)
|
||
|
||
**Examples**:
|
||
- Code quality (linting, formatting)
|
||
- Documentation completeness
|
||
- Performance optimizations
|
||
- Code comments and clarity
|
||
|
||
**Response Pattern**:
|
||
```
|
||
💡 TIER-2 RECOMMENDATION
|
||
|
||
ISSUE: [What could be improved]
|
||
SUGGESTION: [How to fix]
|
||
IMPACT: [Benefit if fixed]
|
||
|
||
PROCEEDING: [Allowing continuation with awareness]
|
||
```
|
||
|
||
---
|
||
|
||
> ⚡ CHECKPOINT — TIER-0 rules are absolute. TIER-1/2/3 below are negotiable. Don't confuse them.
|
||
|
||
## 💡 TIER-3: Enhancements
|
||
|
||
**Definition**: Optional improvements that enhance developer experience but are not required.
|
||
|
||
**Enforcement**: INFO (informational only, no blocking or warnings)
|
||
|
||
**Examples**:
|
||
- Code style preferences
|
||
- Alternative implementation approaches
|
||
- Efficiency optimizations
|
||
- Development tool suggestions
|
||
|
||
**Response Pattern**:
|
||
```
|
||
ℹ️ TIER-3 SUGGESTION
|
||
|
||
TIP: [Optional improvement]
|
||
BENEFIT: [Why it helps]
|
||
NO ACTION REQUIRED
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 Governance Hierarchy
|
||
|
||
**Precedence Order** (highest to lowest):
|
||
1. **TIER-0 Rules** → Always enforced, zero exceptions
|
||
2. **MCP Server Validation** → Technical enforcement layer
|
||
3. **Extension Interception** → User action validation
|
||
4. **Agent.md Instructions** → AI behavioral guidance
|
||
5. **Skills Modules** → Domain-specific rules
|
||
6. **Component Standards** → Language/framework conventions
|
||
|
||
---
|
||
|
||
## Key Rules From This Module
|
||
|
||
- TIER-0 operations are BLOCKED immediately. No workarounds, no exceptions.
|
||
- Protected files (.github/agents/**, .github/copilot-modules/**) require explicit approval.
|
||
- Secrets detected in code must be removed before any other action.
|
||
- When uncertain about TIER classification, escalate — do not guess.
|
||
- Definitions: `.github/virsaitis-definition-library.md`
|
||
|
||
Return to hub: `.github/copilot-instructions.md`
|
||
|
||
**Conflict Resolution**:
|
||
- Higher TIER always overrides lower TIER
|
||
- TIER-0 rules cannot be overridden by any component
|
||
- Agent.md provides context, MCP/Extension enforce technically
|
||
- Skills defer to Agent.md for TIER-0 rules
|
||
|
||
---
|
||
|
||
> ⚡ CHECKPOINT — Before implementing, did you search virsaitis-requirements/ for a REQ-ID? Discovery first.
|
||
|
||
## 🔄 Discovery-First Approach
|
||
|
||
**Core Principle**: DISCOVER, don't ASSUME. Verify file existence and content before modifying. Search for REQ-IDs before implementing. Ask when uncertain.
|
||
|
||
**Full workflow (11 steps)**: See `development-workflow.md` — the authority module for Discovery-First.
|
||
|
||
**Key rules**:
|
||
- Never assume file structure without reading
|
||
- Never invent REQ-IDs that don't exist
|
||
- Never proceed when uncertain — respond with `CONFIRM_NEEDED`
|
||
|
||
---
|
||
|
||
## 🆘 When Uncertain
|
||
|
||
**IF UNCERTAIN ABOUT:**
|
||
- File location or component ownership
|
||
- REQ-ID applicability
|
||
- Security implications
|
||
- TIER classification
|
||
- Correct tool to use
|
||
- Atomic sentence structure
|
||
|
||
**RESPOND:**
|
||
```
|
||
CONFIRM_NEEDED: [specific question]
|
||
|
||
CONTEXT: [Why clarification needed]
|
||
OPTIONS: [If applicable]
|
||
CONSEQUENCE: [Impact of wrong choice]
|
||
|
||
AWAITING: User response
|
||
```
|
||
|
||
**DO NOT:**
|
||
- Guess or assume
|
||
- Proceed with ambiguity
|
||
- Invent information
|
||
- Bypass governance
|
||
- Use fallback without confirmation
|
||
|
||
---
|
||
|
||
## 📚 Quick Reference
|
||
|
||
| TIER | Enforcement | User Action | Example |
|
||
|------|-------------|-------------|---------|
|
||
| TIER-0 | BLOCK | Cannot proc eed | Modify protected file |
|
||
| TIER-1 | WARN+CONFIRM | Must approve | Missing REQ-ID |
|
||
| TIER-2 | WARN+SUGGEST | Can proceed | Linter warning |
|
||
| TIER-3 | INFO | No action | Code style tip |
|
||
|
||
---
|
||
|
||
*Core Policies Module v3.0.0*
|
||
*Foundation for all Virsaitis governance enforcement*
|