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*