feat: initial implementation — all 35 requirements across phases 1-3
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)
This commit is contained in:
338
.github/copilot-modules/core-policies.md
vendored
Normal file
338
.github/copilot-modules/core-policies.md
vendored
Normal file
@@ -0,0 +1,338 @@
|
||||
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*
|
||||
Reference in New Issue
Block a user