@zelari/core 0.7.10 → 0.7.11

package/dist/agents/skills/builtin/refactoring.js

@@ -1,17 +1,17 @@
 import { registerCodingSkill } from '../../skills.js';
-const CLARIFICATION_PROTOCOL = `
-
-WHEN TO ASK THE USER (clarification):
-If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
-
----QUESTION---
-{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
----END---
-
-Rules for clarifications:
-- Ask AT MOST ONE question per turn, and only when genuinely blocked.
-- Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
-- Do NOT ask for information that could be reasonably assumed or already in shared context.
+const CLARIFICATION_PROTOCOL = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a custom answer.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
 - If you can proceed with a sound documented assumption, DO SO instead of asking.`;
 const extractReusable = {
     id: 'extract-reusable',
@@ -74,27 +74,27 @@ const extractReusable = {
         },
     ],
     outputSchema: '{ duplication: { callSites: Array<{ file: string; function: string; line: number }>; differences: string[] }; proposedModule: { path: string; api: string; variants: Array<{ style: string; example: string }> }; migration: Array<{ step: string; linesToChange: number }>; benefits: string[] }',
-    systemPromptFragment: `You are finding duplicated logic and extracting a reusable module.
-
-## Methodology
-1. Use grep/semantic search to find candidate duplication (3+ similar implementations).
-2. Read each call site to understand the VARIATIONS (not just the common pattern).
-3. Design an API that accommodates ALL variations (use options pattern, not multiple functions).
-4. Specify the new module path + function signature + behavior table.
-5. List migration steps: which file + which lines change to use the new module.
-
-## Extraction principles
-- **Variations via options, not forks**: prefer formatDuration(ms, opts) over formatDurationCompact()/Full()
-- **Pure functions**: extracted modules should have no hidden state, no I/O
-- **Tests first**: write the test suite for the new module BEFORE migrating call sites
-- **Single responsibility**: extracted module does ONE thing well
-
-## Output format (JSON-typed)
-- duplication: { callSites: [{file, function, line}], differences[] }
-- proposedModule: { path, api (TS signature), variants: [{style, example}] }
-- migration: [{step, linesToChange}]
-- benefits: string[] (3-5 bullet points)
-
+    systemPromptFragment: `You are finding duplicated logic and extracting a reusable module.
+
+## Methodology
+1. Use grep/semantic search to find candidate duplication (3+ similar implementations).
+2. Read each call site to understand the VARIATIONS (not just the common pattern).
+3. Design an API that accommodates ALL variations (use options pattern, not multiple functions).
+4. Specify the new module path + function signature + behavior table.
+5. List migration steps: which file + which lines change to use the new module.
+
+## Extraction principles
+- **Variations via options, not forks**: prefer formatDuration(ms, opts) over formatDurationCompact()/Full()
+- **Pure functions**: extracted modules should have no hidden state, no I/O
+- **Tests first**: write the test suite for the new module BEFORE migrating call sites
+- **Single responsibility**: extracted module does ONE thing well
+
+## Output format (JSON-typed)
+- duplication: { callSites: [{file, function, line}], differences[] }
+- proposedModule: { path, api (TS signature), variants: [{style, example}] }
+- migration: [{step, linesToChange}]
+- benefits: string[] (3-5 bullet points)
+
 Stay under 500 words.${CLARIFICATION_PROTOCOL}`,
 };
 const simplifyConditionals = {
@@ -129,11 +129,11 @@ const simplifyConditionals = {
             output: {
                 before: { lines: 9, cyclomaticComplexity: 5 },
                 after: { lines: 6, cyclomaticComplexity: 1 },
-                refactored: `function canUserEdit(user, doc) {
-  if (user.isAdmin) return true;
-  if (doc.ownerId === user.id) return true;
-  if (doc.collaborators.includes(user.id) && !doc.locked) return true;
-  return false;
+                refactored: `function canUserEdit(user, doc) {
+  if (user.isAdmin) return true;
+  if (doc.ownerId === user.id) return true;
+  if (doc.collaborators.includes(user.id) && !doc.locked) return true;
+  return false;
 }`,
                 explanation: 'Extracted guard clauses (early returns). Eliminated 3 levels of nesting. Cyclomatic complexity dropped from 5 to 1. Logic preserved exactly.',
             },
@@ -143,34 +143,34 @@ const simplifyConditionals = {
             output: {
                 before: { lines: 7, cyclomaticComplexity: 5 },
                 after: { lines: 7, cyclomaticComplexity: 1 },
-                refactored: `const DISCOUNT_BY_TIER = { bronze: 0.05, silver: 0.10, gold: 0.15, platinum: 0.20 } as const;
-function getDiscount(tier: DiscountTier): number {
-  return DISCOUNT_BY_TIER[tier] ?? 0;
+                refactored: `const DISCOUNT_BY_TIER = { bronze: 0.05, silver: 0.10, gold: 0.15, platinum: 0.20 } as const;
+function getDiscount(tier: DiscountTier): number {
+  return DISCOUNT_BY_TIER[tier] ?? 0;
 }`,
                 explanation: 'Replaced if-else chain with const lookup table. Adding a new tier = one line in the table, no function edit. Type-safe via `as const`. Default 0 via nullish coalescing.',
             },
         },
     ],
     outputSchema: '{ before: { lines: number; cyclomaticComplexity: number }; after: { lines: number; cyclomaticComplexity: number }; refactored: string; explanation: string }',
-    systemPromptFragment: `You are reducing the complexity of conditional code.
-
-## Common patterns to apply
-1. **Guard clauses**: replace \`if (cond) { ...big block... } else { return false; }\` with \`if (!cond) return false; ...big block...\`
-2. **Lookup tables**: replace \`if/else if/else if/...\` chains with \`const TABLE = { ... } as const; return TABLE[key] ?? default\`
-3. **Boolean simplification**: apply De Morgan's laws (\`!(A && B)\` → \`!A || !B\`), extract complex predicates into named booleans
-4. **Polymorphism**: replace type-checking conditionals (\`if (type === 'A') ... else if (type === 'B') ...\`) with method dispatch
-
-## Output format (JSON-typed)
-- before: { lines, cyclomaticComplexity }
-- after: { lines, cyclomaticComplexity }
-- refactored: string (the new code)
-- explanation: string (1-2 sentences on what changed and why)
-
-## What NOT to do
-- Don't change behavior — only structure
-- Don't introduce new abstractions for one-off conditionals
-- Don't sacrifice readability for fewer lines (e.g. overly clever ternary chains)
-
+    systemPromptFragment: `You are reducing the complexity of conditional code.
+
+## Common patterns to apply
+1. **Guard clauses**: replace \`if (cond) { ...big block... } else { return false; }\` with \`if (!cond) return false; ...big block...\`
+2. **Lookup tables**: replace \`if/else if/else if/...\` chains with \`const TABLE = { ... } as const; return TABLE[key] ?? default\`
+3. **Boolean simplification**: apply De Morgan's laws (\`!(A && B)\` → \`!A || !B\`), extract complex predicates into named booleans
+4. **Polymorphism**: replace type-checking conditionals (\`if (type === 'A') ... else if (type === 'B') ...\`) with method dispatch
+
+## Output format (JSON-typed)
+- before: { lines, cyclomaticComplexity }
+- after: { lines, cyclomaticComplexity }
+- refactored: string (the new code)
+- explanation: string (1-2 sentences on what changed and why)
+
+## What NOT to do
+- Don't change behavior — only structure
+- Don't introduce new abstractions for one-off conditionals
+- Don't sacrifice readability for fewer lines (e.g. overly clever ternary chains)
+
 Stay under 400 words.${CLARIFICATION_PROTOCOL}`,
 };
 const refactorMonolith = {
@@ -229,28 +229,28 @@ const refactorMonolith = {
         },
     ],
     outputSchema: '{ currentState: { file: string; totalLines: number; responsibilities: string[] }; proposedModules: Array<{ name: string; responsibility: string; estimatedLines: number; dependsOn: string[] }>; migrationPhases: Array<{ phase: number; name: string; exitCriterion: string; durationDays: number }>; risks: Array<{ risk: string; mitigation: string }> }',
-    systemPromptFragment: `You are planning a multi-perspective decomposition of a large file.
-
-## Methodology
-1. Identify the file's CURRENT responsibilities (read the source if needed).
-2. Search prior split decisions with the retrieval tool listed in your AVAILABLE TOOLS (searchDocuments or searchRAG — never call one that is not listed), query: "<file-name-keyword>"
-3. Propose 4-8 NEW modules, each with ONE clear responsibility.
-4. Map existing functions/sections to new modules (with line numbers).
-5. Validate NO circular dependencies between proposed modules.
-6. Plan 3-5 migration phases, each independently shippable with all tests passing.
-
-## Module split principles
-- **One job per module**: if you can't describe a module's purpose in ONE sentence, split further
-- **No circular deps**: A imports B, B imports C is fine; A imports B, B imports A is not
-- **Stable abstractions**: the new module boundaries should match NATURAL responsibility seams (state vs UI vs I/O), not arbitrary line counts
-- **Testability first**: each module should be unit-testable in isolation
-
-## Output format (JSON-typed)
-- currentState: { file, totalLines, responsibilities[] }
-- proposedModules: Array<{ name, responsibility, estimatedLines, dependsOn[] }>
-- migrationPhases: Array<{ phase, name, exitCriterion, durationDays }>
-- risks: Array<{ risk, mitigation }>
-
+    systemPromptFragment: `You are planning a multi-perspective decomposition of a large file.
+
+## Methodology
+1. Identify the file's CURRENT responsibilities (read the source if needed).
+2. Search prior split decisions with the retrieval tool listed in your AVAILABLE TOOLS (searchDocuments or searchRAG — never call one that is not listed), query: "<file-name-keyword>"
+3. Propose 4-8 NEW modules, each with ONE clear responsibility.
+4. Map existing functions/sections to new modules (with line numbers).
+5. Validate NO circular dependencies between proposed modules.
+6. Plan 3-5 migration phases, each independently shippable with all tests passing.
+
+## Module split principles
+- **One job per module**: if you can't describe a module's purpose in ONE sentence, split further
+- **No circular deps**: A imports B, B imports C is fine; A imports B, B imports A is not
+- **Stable abstractions**: the new module boundaries should match NATURAL responsibility seams (state vs UI vs I/O), not arbitrary line counts
+- **Testability first**: each module should be unit-testable in isolation
+
+## Output format (JSON-typed)
+- currentState: { file, totalLines, responsibilities[] }
+- proposedModules: Array<{ name, responsibility, estimatedLines, dependsOn[] }>
+- migrationPhases: Array<{ phase, name, exitCriterion, durationDays }>
+- risks: Array<{ risk, mitigation }>
+
 Stay under 600 words. Be decisive about module boundaries — pick ONE natural split, don't present 3 equally valid options.${CLARIFICATION_PROTOCOL}`,
 };
 // Register all 3 skills at module load time in topological dependency order.

package/dist/agents/skills/builtin/review.js

@@ -1,17 +1,17 @@
 import * as skillsModule from '../../skills.js';
-const CLARIFICATION_PROTOCOL = `
-
-WHEN TO ASK THE USER (clarification):
-If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
-
----QUESTION---
-{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
----END---
-
-Rules for clarifications:
-- Ask AT MOST ONE question per turn, and only when genuinely blocked.
-- Prefer a small set of concrete "choices" (2-4). The user can still type a wave-in response.
-- Do NOT ask for information that could be reasonably assumed or already in shared context.
+const CLARIFICATION_PROTOCOL = `
+
+WHEN TO ASK THE USER (clarification):
+If a single missing fact would materially change your output (target platform, scope, a binary design choice with significant trade-offs, a constraint you cannot safely assume), pause and ask the user by appending EXACTLY this block at the end of your message:
+
+---QUESTION---
+{ "question": "One focused question", "choices": ["Option A", "Option B", "Option C"], "context": "Why this matters" }
+---END---
+
+Rules for clarifications:
+- Ask AT MOST ONE question per turn, and only when genuinely blocked.
+- Prefer a small set of concrete "choices" (2-4). The user can still type a wave-in response.
+- Do NOT ask for information that could be reasonably assumed or already in shared context.
 - If you can proceed with a sound documented assumption, DO SO instead of asking.`;
 const securityAudit = {
     id: 'security-audit',
@@ -60,34 +60,34 @@ const securityAudit = {
         },
     ],
     outputSchema: '{ owaspFindings: Array<{ category: string; severity: string; file: string; line: number; issue: string }>; cveCheck: string; secretsScan: string; priorityOrder: string[] }',
-    systemPromptFragment: `You are auditing the codebase for security vulnerabilities.
-
-## OWASP Top 10 (2021) — check each
-1. **A01 Broken Access Control**: missing role checks, IDOR vulnerabilities
-2. **A02 Cryptographic Failures**: weak hashing (MD5/SHA-1/SHA-256 for passwords), missing TLS
-3. **A03 Injection**: SQL injection, command injection, XSS (especially via unsafe dangerouslySetInnerHTML)
-4. **A04 Insecure Design**: missing rate limiting on auth endpoints
-5. **A05 Security Misconfiguration**: default credentials, exposed debug endpoints
-6. **A06 Vulnerable Components**: outdated dependencies with known CVEs (run npm audit)
-7. **A07 Identification & Auth Failures**: missing MFA, weak password policies
-8. **A08 Software & Data Integrity Failures**: missing signature verification on updates
-9. **A09 Logging & Monitoring Failures**: no audit log on sensitive operations
-10. **A10 SSRF**: user-controlled URLs fetched server-side without allowlist
-
-## CVE check
-- Run npm audit (or pip-audit, cargo audit, etc. depending on the stack)
-- Cross-reference with the GitHub Advisory Database
-
-## Secrets scan
-- grep for common patterns: API_KEY, SECRET, TOKEN, PASSWORD, BEGIN PRIVATE KEY
-- Check .env files are gitignored
-
-## Output format (JSON-typed)
-- owaspFindings: Array<{ category, severity, file, line, issue }>
-- cveCheck: string (results of dependency scan)
-- secretsScan: string (results of hardcoded secrets scan)
-- priorityOrder: string[] (numbered list, CRITICAL first)
-
+    systemPromptFragment: `You are auditing the codebase for security vulnerabilities.
+
+## OWASP Top 10 (2021) — check each
+1. **A01 Broken Access Control**: missing role checks, IDOR vulnerabilities
+2. **A02 Cryptographic Failures**: weak hashing (MD5/SHA-1/SHA-256 for passwords), missing TLS
+3. **A03 Injection**: SQL injection, command injection, XSS (especially via unsafe dangerouslySetInnerHTML)
+4. **A04 Insecure Design**: missing rate limiting on auth endpoints
+5. **A05 Security Misconfiguration**: default credentials, exposed debug endpoints
+6. **A06 Vulnerable Components**: outdated dependencies with known CVEs (run npm audit)
+7. **A07 Identification & Auth Failures**: missing MFA, weak password policies
+8. **A08 Software & Data Integrity Failures**: missing signature verification on updates
+9. **A09 Logging & Monitoring Failures**: no audit log on sensitive operations
+10. **A10 SSRF**: user-controlled URLs fetched server-side without allowlist
+
+## CVE check
+- Run npm audit (or pip-audit, cargo audit, etc. depending on the stack)
+- Cross-reference with the GitHub Advisory Database
+
+## Secrets scan
+- grep for common patterns: API_KEY, SECRET, TOKEN, PASSWORD, BEGIN PRIVATE KEY
+- Check .env files are gitignored
+
+## Output format (JSON-typed)
+- owaspFindings: Array<{ category, severity, file, line, issue }>
+- cveCheck: string (results of dependency scan)
+- secretsScan: string (results of hardcoded secrets scan)
+- priorityOrder: string[] (numbered list, CRITICAL first)
+
 Stay under 500 words.${CLARIFICATION_PROTOCOL}`,
 };
 const performanceReview = {
@@ -132,27 +132,27 @@ const performanceReview = {
         },
     ],
     outputSchema: '{ findings: Array<{ type: string; severity: string; file: string; line: number; issue: string; fix: string }>; bigO: string; expectedSpeedup: string }',
-    systemPromptFragment: `You are reviewing code for performance issues.
-
-## Common patterns to detect
-1. **N+1 queries**: loop with a DB call inside (fetch all data upfront with a JOIN)
-2. **Allocation in hot loops**: \`new SomeClass()\` inside \`for (...)\` (hoist outside)
-3. **Missing index**: SQL filter on unindexed column (add index, EXPLAIN ANALYZE)
-4. **No caching**: identical computation repeated (LRU cache, memoize)
-5. **Blocking I/O in async**: \`await fs.readFileSync(...)\` (use async readFile)
-6. **Quadratic loops**: nested loops over the same array (use hash map for O(n) lookup)
-7. **Synchronous XHR/fetch**: blocking the main thread (use async/await or worker)
-
-## Output format (JSON-typed)
-- findings: Array<{ type, severity, file, line, issue, fix }>
-- bigO: string (the complexity change after fixes)
-- expectedSpeedup: string (estimated speedup magnitude)
-
-## Anti-patterns to avoid
-- **Don't propose premature optimizations** (caching for a function called once)
-- **Don't change behavior for performance** unless explicitly asked
-- **Profile first** — don't guess where the hot path is
-
+    systemPromptFragment: `You are reviewing code for performance issues.
+
+## Common patterns to detect
+1. **N+1 queries**: loop with a DB call inside (fetch all data upfront with a JOIN)
+2. **Allocation in hot loops**: \`new SomeClass()\` inside \`for (...)\` (hoist outside)
+3. **Missing index**: SQL filter on unindexed column (add index, EXPLAIN ANALYZE)
+4. **No caching**: identical computation repeated (LRU cache, memoize)
+5. **Blocking I/O in async**: \`await fs.readFileSync(...)\` (use async readFile)
+6. **Quadratic loops**: nested loops over the same array (use hash map for O(n) lookup)
+7. **Synchronous XHR/fetch**: blocking the main thread (use async/await or worker)
+
+## Output format (JSON-typed)
+- findings: Array<{ type, severity, file, line, issue, fix }>
+- bigO: string (the complexity change after fixes)
+- expectedSpeedup: string (estimated speedup magnitude)
+
+## Anti-patterns to avoid
+- **Don't propose premature optimizations** (caching for a function called once)
+- **Don't change behavior for performance** unless explicitly asked
+- **Profile first** — don't guess where the hot path is
+
 Stay under 500 words.${CLARIFICATION_PROTOCOL}`,
 };
 const testCoverageAnalysis = {
@@ -200,26 +200,26 @@ const testCoverageAnalysis = {
         },
     ],
     outputSchema: '{ untestedBranches: Array<{ branch: string; file: string; line: number; suggestedTest: string }>; edgeCases: string[]; priorityOrder: string[] }',
-    systemPromptFragment: `You are identifying untested code branches.
-
-## Methodology
-1. **Read each branch** in the source file (if/else, switch cases, try/catch).
-2. **Identify untested branches** by reading the corresponding test file.
-3. **Suggest a SPECIFIC test** (not "add a test for X" — write the actual assertion).
-4. **Prioritize edge cases**: NaN, null, undefined, empty array, max int, negative numbers.
-5. **Prioritize error paths**: what happens when validation fails, network drops, etc.?
-
-## Output format (JSON-typed)
-- untestedBranches: Array<{ branch, file, line, suggestedTest }>
-- edgeCases: string[] (3-7 cases)
-- priorityOrder: string[] (numbered list)
-
-## Test quality principles
-- **One assertion per test** — easier to debug
-- **Specific assertion** — not \`expect(result).toBeTruthy()\` but \`expect(result).toBe('1h 23m')\`
-- **Test the boundary** — \`n=0\`, \`n=1\`, \`n=MAX_INT\`
-- **Test the failure path** — invalid input, network errors, partial data
-
+    systemPromptFragment: `You are identifying untested code branches.
+
+## Methodology
+1. **Read each branch** in the source file (if/else, switch cases, try/catch).
+2. **Identify untested branches** by reading the corresponding test file.
+3. **Suggest a SPECIFIC test** (not "add a test for X" — write the actual assertion).
+4. **Prioritize edge cases**: NaN, null, undefined, empty array, max int, negative numbers.
+5. **Prioritize error paths**: what happens when validation fails, network drops, etc.?
+
+## Output format (JSON-typed)
+- untestedBranches: Array<{ branch, file, line, suggestedTest }>
+- edgeCases: string[] (3-7 cases)
+- priorityOrder: string[] (numbered list)
+
+## Test quality principles
+- **One assertion per test** — easier to debug
+- **Specific assertion** — not \`expect(result).toBeTruthy()\` but \`expect(result).toBe('1h 23m')\`
+- **Test the boundary** — \`n=0\`, \`n=1\`, \`n=MAX_INT\`
+- **Test the failure path** — invalid input, network errors, partial data
+
 Stay under 400 words.${CLARIFICATION_PROTOCOL}`,
 };
 const codeReview = {
@@ -265,32 +265,32 @@ const codeReview = {
         },
     ],
     outputSchema: '{ findings: Array<{ role: string; severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW"; line: number; issue: string; file: string }>; consensus: string; mergeVerdict: "APPROVE" | "REQUEST_CHANGES" | "BLOCK" }',
-    systemPromptFragment: `You are conducting a multi-role code review.
-
-## Review roles
-- **oracle (correctness)**: bugs, race conditions, edge cases, error handling
-- **atlas (performance)**: O(n²) algorithms, N+1 queries, unnecessary allocations, missing caching
-- **oracle (security)**: injection, auth bypass, secrets in code, unsafe deserialization (overlaps with security-audit skill — run that first)
-- **atlas (accessibility)**: ARIA labels, keyboard nav, color contrast
-- **chairman (synthesis)**: aggregates all findings, emits verdict (APPROVE / REQUEST_CHANGES / BLOCK)
-
-## Severity levels
-- **CRITICAL**: must fix before merge (security, data loss, crash)
-- **HIGH**: should fix before merge (correctness bug, performance regression)
-- **MEDIUM**: nice to fix (code smell, minor perf)
-- **LOW**: nitpick (style, naming)
-
-## Output format (JSON-typed)
-- findings: Array<{ role, severity, line, issue, file }>
-- consensus: string (chairman's synthesis)
-- mergeVerdict: 'APPROVE' | 'REQUEST_CHANGES' | 'BLOCK'
-
-## Review principles
-- **Be specific**: cite file + line numbers
-- **Be actionable**: each finding has a concrete fix
-- **Don't bikeshed style** — note as LOW or skip
-- **Trust the author** — don't require changes that are preference, not correctness
-
+    systemPromptFragment: `You are conducting a multi-role code review.
+
+## Review roles
+- **oracle (correctness)**: bugs, race conditions, edge cases, error handling
+- **atlas (performance)**: O(n²) algorithms, N+1 queries, unnecessary allocations, missing caching
+- **oracle (security)**: injection, auth bypass, secrets in code, unsafe deserialization (overlaps with security-audit skill — run that first)
+- **atlas (accessibility)**: ARIA labels, keyboard nav, color contrast
+- **chairman (synthesis)**: aggregates all findings, emits verdict (APPROVE / REQUEST_CHANGES / BLOCK)
+
+## Severity levels
+- **CRITICAL**: must fix before merge (security, data loss, crash)
+- **HIGH**: should fix before merge (correctness bug, performance regression)
+- **MEDIUM**: nice to fix (code smell, minor perf)
+- **LOW**: nitpick (style, naming)
+
+## Output format (JSON-typed)
+- findings: Array<{ role, severity, line, issue, file }>
+- consensus: string (chairman's synthesis)
+- mergeVerdict: 'APPROVE' | 'REQUEST_CHANGES' | 'BLOCK'
+
+## Review principles
+- **Be specific**: cite file + line numbers
+- **Be actionable**: each finding has a concrete fix
+- **Don't bikeshed style** — note as LOW or skip
+- **Trust the author** — don't require changes that are preference, not correctness
+
 Stay under 600 words.${CLARIFICATION_PROTOCOL}`,
 };
 // prettier-ignore