tribunal-kit 1.0.0 → 2.4.0

package/.agent/skills/clean-code/SKILL.md

@@ -1,201 +1,206 @@
 ---
 name: clean-code
 description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
-allowed-tools: Read, Write, Edit
-version: 2.0
-priority: CRITICAL
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Clean Code - Pragmatic AI Coding Standards
+# Clean Code Standards
 
-> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
+> Code is read far more than it is written. Write for the next person.
+> That person is often you, six months from now, confused.
 
 ---
 
-## Core Principles
+## Core Philosophy
 
-| Principle | Rule |
-|-----------|------|
-| **SRP** | Single Responsibility - each function/class does ONE thing |
-| **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
-| **KISS** | Keep It Simple - simplest solution that works |
-| **YAGNI** | You Aren't Gonna Need It - don't build unused features |
-| **Boy Scout** | Leave code cleaner than you found it |
+Clean code is not aesthetic. It is functional. Messy code is slow to change, easy to break, and hard to debug. These standards exist to make code **safe to modify** — not to make it look clever.
 
 ---
 
-## Naming Rules
+## Naming
 
-| Element | Convention |
-|---------|------------|
-| **Variables** | Reveal intent: `userCount` not `n` |
-| **Functions** | Verb + noun: `getUserById()` not `user()` |
-| **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
-| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
+Names are the primary documentation. Choose them seriously.
 
-> **Rule:** If you need a comment to explain a name, rename it.
+**Rules:**
+- Variables and functions describe what they hold or do — not how they do it
+- Boolean names start with `is`, `has`, `can`, `should`
+- No single-letter names except loop counters (`i`, `j`) and throwaway lambdas
+- No abbreviations unless they are industry-wide (`url`, `id`, `dto`, `api`)
+- Name at the right level of abstraction — `user` not `userObjectFromDatabase`
+
+```ts
+// ❌ Unclear
+const d = new Date();
+const fn = (x) => x * 1.2;
+
+// ✅ Self-documenting
+const createdAt = new Date();
+const applyTax = (price: number) => price * 1.2;
+```
 
 ---
 
-## Function Rules
+## Functions
 
-| Rule | Description |
-|------|-------------|
-| **Small** | Max 20 lines, ideally 5-10 |
-| **One Thing** | Does one thing, does it well |
-| **One Level** | One level of abstraction per function |
-| **Few Args** | Max 3 arguments, prefer 0-2 |
-| **No Side Effects** | Don't mutate inputs unexpectedly |
+A function does one thing. If you need "and" to describe it, split it.
 
----
+- Max ~20 lines per function before questioning its scope
+- Arguments: 0–2 preferred, 3 acceptable, 4+ is a signal to use an options object
+- No boolean flags as arguments — they mean the function does two things
+- Return early to avoid nesting — guard clauses before main logic
 
-## Code Structure
+```ts
+// ❌ Flag argument
+function createUser(data: UserData, sendEmail: boolean) { ... }
 
-| Pattern | Apply |
-|---------|-------|
-| **Guard Clauses** | Early returns for edge cases |
-| **Flat > Nested** | Avoid deep nesting (max 2 levels) |
-| **Composition** | Small functions composed together |
-| **Colocation** | Keep related code close |
+// ✅ Two clear functions
+function createUser(data: UserData) { ... }
+function createUserAndNotify(data: UserData) { ... }
+```
 
 ---
 
-## AI Coding Style
+## Comments
 
-| Situation | Action |
-|-----------|--------|
-| User asks for feature | Write it directly |
-| User reports bug | Fix it, don't explain |
-| No clear requirement | Ask, don't assume |
+Comments explain **why** — not **what**.
 
----
+- Code explains what it does. A comment explaining what code does means the code is unclear — rewrite the code.
+- Comments explain intent, business rules, non-obvious constraints, and external references
+- Never leave commented-out code in a commit. Use version control.
 
-## Anti-Patterns (DON'T)
+```ts
+// ❌ Pointless comment
+// Get the user by id
+const user = await getUser(id);
 
-| ❌ Pattern | ✅ Fix |
-|-----------|-------|
-| Comment every line | Delete obvious comments |
-| Helper for one-liner | Inline the code |
-| Factory for 2 objects | Direct instantiation |
-| utils.ts with 1 function | Put code where used |
-| "First we import..." | Just write code |
-| Deep nesting | Guard clauses |
-| Magic numbers | Named constants |
-| God functions | Split by responsibility |
+// ✅ Useful comment
+// Retry up to 3 times — payment gateway times out under load
+const result = await retry(() => chargeCard(amount), 3);
+```
 
 ---
 
-## 🔴 Before Editing ANY File (THINK FIRST!)
+## Error Handling
+
+Errors are part of the contract. Don't hide them.
+
+- Every async function must handle its rejection — `try/catch` or `.catch()`
+- Log full context: what operation failed, with what input, what the error was
+- Never swallow errors silently (`catch (e) {}`)
+- User-facing error messages are different from developer error messages — don't conflate them
+
+---
 
-**Before changing a file, ask yourself:**
+## Testing Standards
 
-| Question | Why |
-|----------|-----|
-| **What imports this file?** | They might break |
-| **What does this file import?** | Interface changes |
-| **What tests cover this?** | Tests might fail |
-| **Is this a shared component?** | Multiple places affected |
+Tests make refactoring safe. Without them, every change is a gamble.
 
-**Quick Check:**
+**AAA Pattern — every test:**
 ```
-File to edit: UserService.ts
-└── Who imports this? → UserController.ts, AuthController.ts
-└── Do they need changes too? → Check function signatures
+Arrange  → set up what you need
+Act      → call the thing being tested
+Assert   → verify the outcome
 ```
 
-> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
-> 🔴 **Never leave broken imports or missing updates.**
+**Test pyramid:**
+- Unit tests: fast, isolated, abundant — test one function
+- Integration tests: slower, test how components interact
+- E2E tests: fewest, test the full user path
+
+**Rules:**
+- One assertion per concept (multiple `expect` calls OK if they verify the same outcome)
+- Tests must pass consistently — a flaky test is a broken test
+- Descriptive test names: `should return 401 when token is expired` not `test auth`
 
 ---
 
-## Summary
+## Performance
 
-| Do | Don't |
-|----|-------|
-| Write code directly | Write tutorials |
-| Let code self-document | Add obvious comments |
-| Fix bugs immediately | Explain the fix first |
-| Inline small things | Create unnecessary files |
-| Name things clearly | Use abbreviations |
-| Keep functions small | Write 100+ line functions |
+Measure first. Optimize what is actually slow.
 
-> **Remember: The user wants working code, not a programming lesson.**
+- Profile before assuming — perceived slowness is not always where you think
+- O(n²) in a list that never exceeds 10 items is not a problem worth solving
+- Premature optimization adds complexity and creates bugs
+- Core Web Vitals are the standard for frontend performance targets (2025)
 
 ---
 
-## 🔴 Self-Check Before Completing (MANDATORY)
-
-**Before saying "task complete", verify:**
+## Security Baseline (Always)
 
-| Check | Question |
-|-------|----------|
-| ✅ **Goal met?** | Did I do exactly what user asked? |
-| ✅ **Files edited?** | Did I modify all necessary files? |
-| ✅ **Code works?** | Did I test/verify the change? |
-| ✅ **No errors?** | Lint and TypeScript pass? |
-| ✅ **Nothing forgotten?** | Any edge cases missed? |
+These are not optional:
 
-> 🔴 **Rule:** If ANY check fails, fix it before completing.
+- Secrets in environment variables — never in code
+- All SQL queries parameterized — never string-interpolated
+- User input validated at every boundary — never trusted
+- Authentication checked before business logic executes
 
 ---
 
-## Verification Scripts (MANDATORY)
+## 🤖 LLM-Specific Clean Code Traps
 
-> 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.
+AI coding assistants (like you) fall into specific bad habits when writing code. These are strictly forbidden under the clean-code standard:
 
-### Agent → Script Mapping
+1. **JSDoc/Docstring Spam:** Documenting what a function does when the code is self-evident.
+    *   *❌ AI Trait:* `/** Adds two numbers. @param a First number @param b Second number @returns The sum */ function add(a, b) { return a + b; }`
+    *   *✅ Clean Code:* `function add(a: number, b: number): number { return a + b; }`
+2. **Defensive Programming Overkill:** Adding 15 `null` checks where the TypeScript compiler or the previous tier has already guaranteed validity.
+3. **Premature Abstraction:** Creating an `AbstractDataManager` factory class with interfaces to parse a simple CSV file. Code what is needed *now*.
+4. **Variable Diarrhea:** Extracting every step of a calculation into a separate `const` when a single readable line would suffice.
+5. **Apologetic Comments:** `// TODO: Refactor this later` or `// I assumed this was the right way`. If you write it, own it. If it's incomplete, flag the user.
 
-| Agent | Script | Command |
-|-------|--------|---------|
-| **frontend-specialist** | UX Audit | `python .agent/skills/frontend-design/scripts/ux_audit.py .` |
-| **frontend-specialist** | A11y Check | `python .agent/skills/frontend-design/scripts/accessibility_checker.py .` |
-| **backend-specialist** | API Validator | `python .agent/skills/api-patterns/scripts/api_validator.py .` |
-| **mobile-developer** | Mobile Audit | `python .agent/skills/mobile-design/scripts/mobile_audit.py .` |
-| **database-architect** | Schema Validate | `python .agent/skills/database-design/scripts/schema_validator.py .` |
-| **security-auditor** | Security Scan | `python .agent/skills/vulnerability-scanner/scripts/security_scan.py .` |
-| **seo-specialist** | SEO Check | `python .agent/skills/seo-fundamentals/scripts/seo_checker.py .` |
-| **seo-specialist** | GEO Check | `python .agent/skills/geo-fundamentals/scripts/geo_checker.py .` |
-| **performance-optimizer** | Lighthouse | `python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
-| **test-engineer** | Test Runner | `python .agent/skills/testing-patterns/scripts/test_runner.py .` |
-| **test-engineer** | Playwright | `python .agent/skills/webapp-testing/scripts/playwright_runner.py <url>` |
-| **Any agent** | Lint Check | `python .agent/skills/lint-and-validate/scripts/lint_runner.py .` |
-| **Any agent** | Type Coverage | `python .agent/skills/lint-and-validate/scripts/type_coverage.py .` |
-| **Any agent** | i18n Check | `python .agent/skills/i18n-localization/scripts/i18n_checker.py .` |
+---
 
-> ❌ **WRONG:** `test-engineer` running `ux_audit.py`
-> ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`
+## Output Format
 
----
+When this skill produces or reviews code, structure your output as follows:
 
-### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)
+```
+━━━ Clean Code Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Clean Code
+Language:    [detected language / framework]
+Scope:       [N files · N functions]
+─────────────────────────────────────────────────
+✅ Passed:   [checks that passed, or "All clean"]
+⚠️  Warnings: [non-blocking issues, or "None"]
+❌ Blocked:  [blocking issues requiring fix, or "None"]
+─────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [test output / lint pass / compile success]
+```
 
-**When running a validation script, you MUST:**
+**VBC (Verification-Before-Completion) is mandatory.**
+Do not mark status as VERIFIED until concrete terminal evidence is provided.
 
-1. **Run the script** and capture ALL output
-2. **Parse the output** - identify errors, warnings, and passes
-3. **Summarize to user** in this format:
 
-```markdown
-## Script Results: [script_name.py]
+---
 
-### ❌ Errors Found (X items)
-- [File:Line] Error description 1
-- [File:Line] Error description 2
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-### ⚠️ Warnings (Y items)
-- [File:Line] Warning description
+**Slash command: `/generate`, `/review-types`**
+**Active reviewers: `logic-reviewer` · `type-safety-reviewer`**
 
-### ✅ Passed (Z items)
-- Check 1 passed
-- Check 2 passed
+### ❌ Forbidden AI Tropes in Code Generation
 
-**Should I fix the X errors?**
-```
+1. **Over-engineering:** Solving a problem with 3 classes when 1 function works perfectly.
+2. **Commented-out code:** Submitting commented-out dead code, "just in case." Delete it.
+3. **Implicit `any` types:** Failing to strictly type a critical parameter or return value.
+
+### ✅ Pre-Flight Self-Audit
 
-4. **Wait for user confirmation** before fixing
-5. **After fixing** → Re-run script to confirm
+Review these questions before confirming code generation or review:
+```
+✅ Does this function do strictly ONE thing?
+✅ Have I removed all pointless comments explaining *what* the code does?
+✅ Did I use specific, business-logic naming rather than generic abbreviations?
+✅ Are all edge cases and rejections properly handled (no swallowed errors)?
+✅ Did I avoid over-engineering this solution?
+```
 
-> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
-> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
-> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.
+### 🛑 Verification-Before-Completion (VBC) Protocol
 
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Refactoring code or blindly applying "clean code" rules without verifying the code still compiles and works.
+- ✅ **Required:** You are explicitly forbidden from finalizing a refactor without providing **concrete terminal evidence** (e.g., passing unit tests logs, successful linting execution, or type-check success) proving the refactored code maintains the original behavior.

package/.agent/skills/code-review-checklist/SKILL.md

@@ -1,109 +1,206 @@
 ---
 name: code-review-checklist
 description: Code review guidelines covering code quality, security, and best practices.
-allowed-tools: Read, Glob, Grep
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Code Review Checklist
+# Code Review Standards
 
-## Quick Review Checklist
+> A code review is not a gatekeeping exercise.
+> It is a knowledge transfer session that also catches bugs.
+
+---
+
+## Review Mindset
+
+Reviews are collaborative. The goal is better code — not proof that the reviewer is smarter.
+
+**Before commenting:**
+- Understand what the code is trying to do before judging how it does it
+- Distinguish between personal preference and objective problems
+- Label your findings so the author understands the expected action
+
+**Comment label convention:**
+- `BLOCKER:` — must be fixed before merge (bug, security issue, broken behavior)
+- `CONCERN:` — likely problem that needs discussion before proceeding
+- `SUGGESTION:` — would improve the code but is not required
+- `NOTE:` — observation or question, no action needed
+
+---
+
+## What to Check
 
 ### Correctness
-- [ ] Code does what it's supposed to do
-- [ ] Edge cases handled
-- [ ] Error handling in place
-- [ ] No obvious bugs
+- Does the code do what it claims to do?
+- Are edge cases handled? (empty input, null, max value, concurrent execution)
+- Does error handling cover realistic failure modes?
+- Are there off-by-one errors? Integer overflow risks?
 
 ### Security
-- [ ] Input validated and sanitized
-- [ ] No SQL/NoSQL injection vulnerabilities
-- [ ] No XSS or CSRF vulnerabilities
-- [ ] No hardcoded secrets or sensitive credentials
-- [ ] **AI-Specific:** Protection against Prompt Injection (if applicable)
-- [ ] **AI-Specific:** Outputs are sanitized before being used in critical sinks
+- Is user input validated before it's used?
+- Are SQL queries parameterized — never string-concatenated?
+- Are secrets in environment variables — not in code?
+- Are auth checks happening before business logic executes?
+- Is the OWASP API Top 10 considered for any API routes?
+
+### Readability
+- Can you understand the intent in under 30 seconds per function?
+- Are names self-documenting at the right level of abstraction?
+- Are complex sections commented with *why*, not *what*?
+- Is nesting kept to a manageable depth (≤3 levels)?
+
+### Design
+- Is this code easy to change? Or would changing one thing break five others?
+- Are there clear boundaries between concerns?
+- Is logic duplicated anywhere that should be shared?
+- Is the new code consistent with how the rest of the codebase does similar things?
+
+### Tests
+- Are tests testing behavior or implementation details?
+- Do tests cover the happy path, edge cases, and known failure modes?
+- Do test names describe the expected behavior in plain language?
+- Would these tests catch a regression if someone broke this code?
 
 ### Performance
-- [ ] No N+1 queries
-- [ ] No unnecessary loops
-- [ ] Appropriate caching
-- [ ] Bundle size impact considered
-
-### Code Quality
-- [ ] Clear naming
-- [ ] DRY - no duplicate code
-- [ ] SOLID principles followed
-- [ ] Appropriate abstraction level
-
-### Testing
-- [ ] Unit tests for new code
-- [ ] Edge cases tested
-- [ ] Tests readable and maintainable
-
-### Documentation
-- [ ] Complex logic commented
-- [ ] Public APIs documented
-- [ ] README updated if needed
-
-## AI & LLM Review Patterns (2025)
-
-### Logic & Hallucinations
-- [ ] **Chain of Thought:** Does the logic follow a verifiable path?
-- [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
-- [ ] **External State:** Is the code making safe assumptions about file systems or networks?
-
-### Prompt Engineering Review
-```markdown
-// ❌ Vague prompt in code
-const response = await ai.generate(userInput);
-
-// ✅ Structured & Safe prompt
-const response = await ai.generate({
-  system: "You are a specialized parser...",
-  input: sanitize(userInput),
-  schema: ResponseSchema
-});
+- Are there database queries inside loops?
+- Are large datasets loaded into memory when they could be streamed?
+- Are expensive operations (network, file I/O) done unnecessarily?
+
+---
+
+## Review Process
+
+1. **Read the PR description first** — understand intent before reading code
+2. **Read tests first** — they tell you what the code is supposed to do
+3. **Read the implementation** — verify it matches what the tests describe
+4. **Run it locally for significant changes** — static reading misses runtime behavior
+
+---
+
+## Giving Feedback
+
+**Effective feedback is:**
+- Specific — references the exact line and the exact concern
+- Actionable — tells the author what to change, not just that something is wrong
+- Explanatory — gives the reasoning, not just the verdict
+
+```
+# ❌ Unhelpful
+This function is too long.
+
+# ✅ Helpful
+SUGGESTION: This function handles both data fetching and data transformation.
+Splitting into `fetchUserData()` and `transformUserData()` would make each
+half easier to test independently and reuse elsewhere.
 ```
 
-## Anti-Patterns to Flag
+---
+
+## Receiving Feedback
+
+- "We disagree" is not the same as "they're wrong"
+- If a comment is unclear, ask for clarification before defending
+- BLOCKER and CONCERN comments need resolution, not just a response
+- SUGGESTION and NOTE are optional — you can explain why you're not acting on them
+
+---
+
+## 🛑 Context Window Discipline
 
-```typescript
-// ❌ Magic numbers
-if (status === 3) { ... }
+When an AI acts as a reviewer, context bloat ruins reasoning:
 
-// ✅ Named constants
-if (status === Status.ACTIVE) { ... }
+1. **Never quote massive blocks of code back to the user.** Use line numbers or tiny 1-3 line snippets.
+2. **Never attach the entire project context to a single file review.**
+3. **Keep reviews scoped.** Do not suggest a full architecture rewrite if the PR is fixing a typo in a CSS class.
 
-// ❌ Deep nesting
-if (a) { if (b) { if (c) { ... } } }
+---
+
+## 🤖 LLM-Specific Review Traps
 
-// ✅ Early returns
-if (!a) return;
-if (!b) return;
-if (!c) return;
-// do work
+AI reviewers frequently fail by focusing on the wrong things. Avoid these strict anti-patterns:
 
-// ❌ Long functions (100+ lines)
-// ✅ Small, focused functions
+1. **Syntax Nitpicking:** Commenting on formatting, semicolons, or line length. Let `eslint` or Prettier handle this. Only comment if logic is affected.
+2. **"Clean Code" Hallucinations:** Telling the author to extract a perfectly readable 10-line function into 3 separate abstract classes.
+3. **Invented Methods:** Suggesting the author use `.toSortedMap()` when that method literally does not exist in the language or framework used.
+4. **False Bottlenecks:** Claiming an `O(n^2)` loop is a performance critical error when `n` is a configuration array guaranteed to be < 10 items.
+5. **The Compliment Sandwich:** You do not need to soften every critique with "Great job on the rest of the code!" Be direct, professional, and concise.
+
+---
 
-// ❌ any type
-const data: any = ...
+## Output Format
 
-// ✅ Proper types
-const data: UserData = ...
+When this skill completes a task, structure your output as:
+
+```
+━━━ Code Review Checklist Output ━━━━━━━━━━━━━━━━━━━━━━━━
+Task:        [what was performed]
+Result:      [outcome summary — one line]
+─────────────────────────────────────────────────
+Checks:      ✅ [N passed] · ⚠️  [N warnings] · ❌ [N blocked]
+VBC status:  PENDING → VERIFIED
+Evidence:    [link to terminal output, test result, or file diff]
 ```
 
-## Review Comments Guide
 
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review`, `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before submitting your code review findings:
+```
+✅ Did I read the tests to understand the intended behavior before reading the implementation?
+✅ Are my BLOCKER and CONCERN comments actionable and specific?
+✅ Have I verified that any alternative methods or libraries I suggested actually exist?
+✅ Have I refrained from quoting more than 3 lines of code in my response?
+✅ Is my feedback focused on logic, edge cases, and security rather than aesthetic formatting?
 ```
-// Blocking issues use 🔴
-🔴 BLOCKING: SQL injection vulnerability here
 
-// Important suggestions use 🟡
-🟡 SUGGESTION: Consider using useMemo for performance
 
-// Minor nits use 🟢
-🟢 NIT: Prefer const over let for immutable variable
+---
+
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+
+1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
+2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
+3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
+4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
 
-// Questions use ❓
-❓ QUESTION: What happens if user is null here?
+### ❌ Forbidden AI Tropes
+
+1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
+2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
+3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before confirming output:
 ```
+✅ Did I rely ONLY on real, verified tools and methods?
+✅ Is this solution appropriately scoped to the user's constraints?
+✅ Did I handle potential failure modes and edge cases?
+✅ Have I avoided generic boilerplate that doesn't add value?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.