@vetala/vetala 0.1.0-beta

package/skill/code-review/references/impact_detection.md

@@ -0,0 +1,149 @@
+# Impact Detection
+
+Techniques for identifying side effects, consumer impact, and contract compatibility of code changes.
+
+## Change Surface Identification
+
+Changed entities are analyzed by role:
+
+- **Behavioral units**: Functions, methods, handlers, jobs, workflows
+- **Data contracts**: Request/response payloads, persisted schemas, serialized structures
+- **Operational contracts**: Runtime entrypoints, scheduled tasks, event names, configuration keys
+
+## Symbol Exposure Analysis
+
+Exposure is classified by externally consumable surface:
+
+| Exposure Type | Description | Typical Evidence |
+|---------------|-------------|------------------|
+| **Externally Consumable Interface** | Contracts consumed across module/service boundaries | Public exports, API descriptors, protocol definitions |
+| **Module/Package Public Surface** | Symbols intended for downstream consumers | Re-export files, package entrypoint files, public manifest mappings |
+| **Runtime Entrypoint Contract** | Startup, routing, eventing, or job invocation interfaces | Route maps, event registration, scheduler/worker bindings |
+
+## Dependency Tracing
+
+### Exact Symbol Lookup
+```bash
+rg -F "<symbol_name>(" .
+```
+- **Purpose**: Finds direct executable call sites for changed callable symbols
+
+### Broader Reference Lookup
+```bash
+rg "<symbol_name>" .
+```
+- **Purpose**: Finds textual references when exact call patterns are insufficient
+
+### Boundary/Entrypoint Lookup
+```bash
+rg "<entrypoint_or_contract_name>" .
+```
+- **Purpose**: Identifies where a changed contract is wired into runtime behavior
+
+### Exposure Lookup
+```bash
+rg "<public_surface_indicator>.*<symbol_name>|<symbol_name>.*<public_surface_indicator>" .
+```
+- **Purpose**: Confirms whether changed entities are reachable from external consumers
+
+## Consumer Counting
+
+Consumer impact is computed in two steps:
+
+1. **Raw Match Count**
+- Count all matches from broad search to establish initial reference volume
+
+2. **Normalized Consumer Count**
+- Include: production runtime references and executable call sites
+- Exclude: definition lines, comments/doc-only references, test-only references, generated files, vendor/third_party code
+- Deduplicate multiple references from the same logical consumer location
+
+> Normalized Consumer Count is the authoritative signal for impact and breaking-change severity.
+
+## Evidence Confidence Model
+
+| Confidence | Score Range | Characteristics |
+|------------|-------------|-----------------|
+| **High** | `>= 0.8` | Multiple direct executable references with call-path confirmation |
+| **Medium** | `0.5 - 0.79` | References exist but aliasing/re-export/indirection leaves partial uncertainty |
+| **Low** | `< 0.5` | Evidence depends on strings, reflection, dynamic dispatch, or incomplete traceability |
+
+### Verification Status Mapping
+
+| Verification Status | Criteria |
+|---------------------|----------|
+| **Verified** | High-confidence evidence with executable reference path |
+| **Partially Verified** | Medium-confidence evidence with unresolved indirection |
+| **Unverifiable** | Low-confidence evidence where static tracing cannot prove runtime linkage |
+
+Unverifiable findings are included explicitly in the review report under analysis limitations.
+
+## Impact Categories
+
+### Direct Impact
+- **Callers/Invokers**: Executable consumers that directly invoke changed behavior
+- **Contract Consumers**: Components that parse, validate, or depend on changed contracts
+- **Runtime Integrations**: Route/event/job bindings mapped to changed interfaces
+
+### Indirect Impact
+- **Transitive Consumers**: Callers downstream from direct consumers
+- **Shared State Dependents**: Components reading or writing affected shared state
+- **Operational Coupling**: Alerting, retry, caching, and fallback layers coupled to changed behavior
+
+## Behavioral Test Coverage Check
+
+Coverage analysis evaluates changed behavior units, not only file presence.
+
+1. Map changed behavior units from the patch
+2. Identify tests asserting those behaviors (success path, failure path, boundary conditions)
+3. Classify coverage:
+- **Covered**: Relevant assertions exist for changed behavior
+- **Partially Covered**: Assertions exist but miss critical branch/edge path
+- **Not Covered**: No relevant assertions found
+
+### Risk Escalation for Missing Coverage
+
+| Coverage Status | Escalation Guidance |
+|-----------------|---------------------|
+| **Covered** | No automatic escalation |
+| **Partially Covered** | Consider one-level risk increase when change is high impact |
+| **Not Covered** | Increase risk level for behavior/regression findings |
+
+## Breaking Change Detection (Generic)
+
+Breaking-change checks are contract-oriented and language-agnostic.
+
+| Contract Change Type | Breaking? | Detection Signal |
+|----------------------|-----------|------------------|
+| **Required input increased** | Yes | New mandatory field/argument/parameter requirement |
+| **Accepted value domain narrowed** | Yes | Removed valid values, stricter validation without compatibility path |
+| **Output contract changed incompatibly** | Yes | Removed/renamed output fields or changed semantic guarantees |
+| **Endpoint/operation signature changed** | Yes | Path/method/operation name or invocation shape changed |
+| **Externally consumed member removed/renamed** | Yes | Consumer-visible symbol removed or renamed without compatibility layer |
+| **Additive backward-compatible extension** | No (usually) | Optional additions preserving existing consumer behavior |
+
+### Decision Signal
+
+- If a breaking contract change has normalized consumers > 0, classify at least as **Critical candidate**
+- Final severity considers impact magnitude, confidence, and critical-domain context
+
+## Risk Indicators
+
+| Indicator | Base Risk | Description |
+|-----------|-----------|-------------|
+| **No Behavioral Coverage** | High | Changed behavior lacks relevant tests |
+| **High Normalized Consumers** | High | Change affects many runtime consumers |
+| **Exposed Public Surface** | High | Change is reachable by external consumers |
+| **Shared State Mutation** | High | Global or shared state semantics are modified |
+| **Data Shape Change** | High | Persisted or exchanged contract changed |
+| **Config Contract Change** | Medium | Runtime config keys/semantics changed |
+
+## Analysis Limitations
+
+Static/textual analysis has known limits:
+
+- Dynamic invocation, reflection, and runtime plugin loading
+- Indirection through aliases, generated wiring, or external orchestration
+- Cross-repository consumers not present in current workspace
+
+These are recorded as confidence reductions and/or `Unverifiable` findings.

package/skill/code-review/references/output_format.md

@@ -0,0 +1,137 @@
+# Output Format
+
+Structure and formatting specification for production-ready code review results.
+
+## Review Report Structure
+
+```
+## Review Summary
+- **Target**: <commit_hash | start_hash~end_hash>
+- **Author**: <name>
+- **Files Changed**: <count>
+- **Lines**: +<added> / -<deleted>
+
+## Findings
+
+### Critical (<count>)
+...
+
+### Major (<count>)
+...
+
+### Minor (<count>)
+...
+
+### Nit (<count>)
+...
+
+## Analysis Limitations
+- <unverifiable area or analysis constraint>
+
+## Risk Context
+- **Critical Domains Affected**: <none | list>
+- **Weighted Risk Score**: <numeric_score>
+
+## Decision Rationale
+- <why this verdict was selected>
+
+## Verdict
+<APPROVE | REQUEST_CHANGES | COMMENT>
+```
+
+## Finding Entry Format
+
+```
+#### [<severity>] <title>
+- **File**: `<file_path>:<line_number>`
+- **Issue**: <description>
+- **Evidence**: <specific code/path/behavioral evidence>
+- **Impact**: <user/service/data/operational impact>
+- **Confidence**: <0.0-1.0>
+- **Verification Status**: <Verified | Partially Verified | Unverifiable>
+- **Suggestion**: <at least one remediation direction>
+```
+
+### Example Entry
+```
+#### [Major] Incompatible output contract for downstream consumer
+- **File**: `service/account/response_mapper.ext:118`
+- **Issue**: Response field `accountStatus` was renamed to `status` without compatibility mapping
+- **Evidence**: Consumer adapters still reference `accountStatus` in runtime parsing logic
+- **Impact**: Downstream consumers may fail to parse responses, causing request failures
+- **Confidence**: 0.86
+- **Verification Status**: Verified
+- **Suggestion**: Add compatibility mapping or versioned response contract before removing old field
+```
+
+## Verdict Criteria
+
+Verdict selection combines count-based baseline rules and risk-weighted adjustments.
+
+### Baseline Rules (Count-Based)
+
+| Verdict | Condition |
+|---------|-----------|
+| **REQUEST_CHANGES** | Any Critical finding exists |
+| **REQUEST_CHANGES** | 3+ Major findings exist |
+| **COMMENT** | Major findings exist (1-2) |
+| **COMMENT** | 5+ Minor findings exist |
+| **APPROVE** | Only Minor/Nit findings or none |
+
+### Weighted Risk Model
+
+- **Severity Weights**: Critical=10, Major=5, Minor=2, Nit=1
+- **Confidence Factor**: High=1.0, Medium=0.7, Low=0.4
+- **Critical Domain Bonus**: +4 per finding impacting authentication/authorization, payment/billing, data integrity/migration, or availability/reliability
+
+`Weighted Risk Score = Sum((Severity Weight * Confidence Factor) + Critical Domain Bonus)`
+
+### Risk-Aware Verdict Adjustments
+
+| Condition | Adjustment |
+|-----------|------------|
+| Any Verified Critical finding | REQUEST_CHANGES |
+| Weighted Risk Score >= 12 with medium-or-higher confidence evidence | REQUEST_CHANGES |
+| Weighted Risk Score 6-11 | COMMENT (unless baseline already requests changes) |
+| Weighted Risk Score <= 5 and no Major+ findings | APPROVE candidate |
+
+### Confidence-Aware Handling
+
+| Evidence Shape | Handling |
+|----------------|----------|
+| High confidence + high impact | Keep or escalate severity as reported |
+| Medium confidence + medium/high impact | Keep severity, include verification note |
+| Low confidence finding | Avoid automatic escalation; request manual verification in rationale |
+
+## Grouping Options
+
+### By Severity (Default)
+Findings are grouped under severity headers.
+
+### By File
+```
+## path/to/file.ext
+- [Major] Contract incompatibility (L118)
+- [Minor] Error context is underspecified (L44)
+```
+
+## Positive Feedback
+
+Include a `Highlights` section when clearly justified by the patch quality.
+
+```
+## Highlights
+- <description of a notable positive practice>
+```
+
+## Summary Statistics
+
+| Metric | Description |
+|--------|-------------|
+| **Total Findings** | Sum of all severity counts |
+| **Critical Count** | Number of critical issues |
+| **Major Count** | Number of major issues |
+| **Minor Count** | Number of minor issues |
+| **Nit Count** | Number of nit issues |
+| **Weighted Risk Score** | Risk-weighted score using severity and confidence factors |
+| **Unverifiable Count** | Number of findings marked as `Unverifiable` |

package/skill/code-review/references/severity_criteria.md

@@ -0,0 +1,100 @@
+# Severity Criteria
+
+Classification criteria for code review findings by severity level, with confidence-aware interpretation.
+
+## Severity Levels
+
+## Critical
+
+Issues with immediate high risk to system integrity, security, availability, or external contract compatibility.
+
+| Category | Examples |
+|----------|----------|
+| **Security Exposure** | Injection vectors, credential leakage, authorization bypass |
+| **Data Integrity Failure** | Corruption, irreversible mutation, destructive migration without safe path |
+| **Availability Risk** | Crash loops, deadlock potential, unbounded resource exhaustion |
+| **Externally Breaking Contract** | Incompatible changes on consumed public/runtime interfaces |
+| **Rollback Gap in High-Risk Change** | No rollback/mitigation path for high-impact operational changes |
+
+### Indicators
+- Sensitive operation without required access control
+- Destructive schema/data change without compatibility or rollback path
+- Consumer-visible contract removed or renamed while consumers exist
+- Critical monitoring/remediation controls removed during risky behavior changes
+
+## Major
+
+Issues that cause incorrect behavior, major reliability degradation, or high operational cost.
+
+| Category | Examples |
+|----------|----------|
+| **Behavioral Defects** | Incorrect branch logic, boundary errors, invalid fallback behavior |
+| **Performance Degradation** | Unbounded processing, repeated expensive operations, excessive I/O |
+| **Error Handling Gaps** | Swallowed failures, incorrect retry boundaries, misclassified errors |
+| **Concurrency/Race Risk** | Inconsistent shared-state access, missing synchronization strategy |
+| **Observability Regression** | Loss of diagnostic context, reduced signal for incident response |
+| **Configuration Semantics Drift** | Runtime config meaning changed without compatibility handling |
+
+### Indicators
+- Changed behavior lacks reliable failure-path handling
+- Operationally expensive path triggered without guardrails
+- Logging/metrics signal required for detection or triage is significantly reduced
+- Consumer-impacting change exists but evidence or impact is below Critical threshold
+
+## Minor
+
+Issues affecting maintainability, readability, or medium-term quality.
+
+| Category | Examples |
+|----------|----------|
+| **Maintainability** | Excessive complexity, duplicated logic, unclear module boundaries |
+| **Readability** | Ambiguous naming, difficult control flow, poor local context |
+| **Design Hygiene** | Tight coupling, low-cohesion utility placement |
+
+### Indicators
+- Complex change with limited local explanation
+- Duplication likely to drift over time
+- Readability issues that increase future defect risk
+
+## Nit
+
+Low-impact polish and consistency suggestions.
+
+| Category | Examples |
+|----------|----------|
+| **Style Consistency** | Formatting or local style drift |
+| **Naming Polish** | Naming clarity improvements with negligible behavioral impact |
+| **Comment Hygiene** | Outdated comments or missing short contextual notes |
+
+### Indicators
+- Cosmetic inconsistency without runtime impact
+- Minor naming or organization cleanup opportunities
+
+## Confidence Axis
+
+Confidence qualifies how strongly evidence supports a finding.
+
+| Confidence Tier | Score Range | Interpretation |
+|-----------------|-------------|----------------|
+| **High** | `>= 0.8` | Strong direct evidence; severity can be acted on directly |
+| **Medium** | `0.5 - 0.79` | Credible but partially indirect evidence; include verification notes |
+| **Low** | `< 0.5` | Weak or indirect evidence; avoid automatic escalation |
+
+## Critical vs Major Boundary Guidance
+
+| Decision Factor | Critical Lean | Major Lean |
+|-----------------|--------------|------------|
+| **Data Risk** | Data loss/corruption likely or irreversible | Data inconsistency possible but recoverable |
+| **Business Logic Impact** | Core transaction/authorization correctness is broken | Limited-path incorrect behavior without systemic failure |
+| **Rollback/Mitigation** | No safe rollback path for high-impact change | Rollback or mitigation exists and is practical |
+| **Observability Effect** | Incident detection/containment capability critically degraded | Detection degraded but still operationally manageable |
+
+## Escalation Conditions
+
+A Major finding is considered a `REQUEST_CHANGES` candidate when all conditions hold:
+
+- Impacts at least one critical domain (`authentication/authorization`, `payment/billing`, `data integrity/migration`, `availability/reliability`)
+- Impact is high for users, service continuity, or data correctness
+- Confidence is Medium or High (`>= 0.5`)
+
+If confidence is Low, keep the finding non-escalated and request manual verification.

package/skill/code-security-audit/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: code-security-audit
+description: Performs OWASP-based code security audits on any codebase. Analyzes source code against ASVS 5.0.0 verification requirements, API Security Top 10 2023 risk patterns, OWASP CheatSheet secure coding practices, and WSTG testing methodologies. Input is a codebase to review; output is a detailed Markdown security audit report. Use when the user requests a security audit, security review, vulnerability assessment, or code security analysis.
+---
+
+# Code Security Audit Capabilities
+
+OWASP 4-source integrated code security audit system for universal codebase analysis.
+
+## Knowledge Sources
+
+- **OWASP ASVS 5.0.0**: 345 verification requirements across 17 security domains (L1/L2/L3)
+- **OWASP API Security Top 10 2023**: 10 API-specific risk categories with code-level indicators
+- **OWASP CheatSheet Series**: 109 practical secure coding cheat sheets for remediation guidance
+- **OWASP WSTG (Web Security Testing Guide)**: 12 testing categories with 120+ test scenarios
+
+## Source Roles
+
+| Source | Role | Usage |
+|--------|------|-------|
+| ASVS 5.0.0 | Verification requirements baseline | Defines what to check — structured requirements per domain |
+| API Security Top 10 2023 | Risk taxonomy | Defines what to look for — API-specific threat patterns |
+| CheatSheet Series | Implementation guidance | Defines how to fix — secure coding patterns and practices |
+| WSTG | Test methodology | Defines how to verify — concrete test scenarios per vulnerability |
+
+## Domains
+
+- **Input Handling** (V1, V2, V5): Encoding, sanitization, injection prevention, validation, file handling
+- **Authentication & Session** (V6, V7, V9, V10): Auth mechanisms, session management, token handling, OAuth/OIDC
+- **Authorization** (V8): Object-level, function-level, property-level access control
+- **Cryptography** (V11, V12): Storage encryption, key management, TLS configuration
+- **API Security** (V4, V17): REST/GraphQL/WebSocket/WebRTC security, rate limiting, resource consumption
+- **Data Protection** (V14): Sensitive data exposure, privacy controls, client-side data
+- **Configuration** (V13, V16): Security headers, CORS, error handling, logging, deployment hardening
+- **Secure Coding** (V3, V15): Web frontend security, architecture patterns, defensive coding, concurrency safety
+
+## Input Contract
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Codebase path** | Yes | The current workspace or repository the agent is operating in. Defaults to the active codebase; users may narrow scope to specific directories or files (e.g., `src/auth/`, `api/controllers/`) |
+| **Audit level** | No | ASVS verification level (default: **L2**). See level definitions below |
+| **Focus areas** | No | Security domains to prioritize. See focus area catalog below |
+| **Tech context** | No | Language, framework, or architecture notes for targeted analysis |
+
+### Audit Levels (OWASP ASVS 5.0.0)
+
+| Level | Target Application | Requirements | Description |
+|-------|-------------------|-------------|-------------|
+| **L1** | All applications | ~86 | Essential baseline — covers critical vulnerabilities that are typically exploitable and must be addressed in every application (e.g., SQL injection, OS command injection, basic auth checks) |
+| **L2** | Applications handling sensitive data (PII, financial, health) | ~230 | Standard security — includes L1 plus defense-in-depth controls such as SSRF protection, template injection prevention, secure session management, and proper cryptographic usage |
+| **L3** | Mission-critical systems (banking, healthcare, military, infrastructure) | ~345 | Comprehensive defense — includes L1+L2 plus advanced controls such as formula injection prevention, full input canonicalization, and exhaustive cryptographic verification |
+
+### Focus Area Catalog
+
+| Focus Area | Domains | Example Checks |
+|------------|---------|----------------|
+| **authentication** | V6, V7, V9, V10 | Password storage, MFA, OAuth/OIDC flow, credential rotation |
+| **authorization** | V8 | Object-level (BOLA), function-level, property-level access control |
+| **injection** | V1, V2 | SQLi, XSS, command injection, LDAP/XPath injection, template injection, XXE |
+| **cryptography** | V11, V12 | Weak algorithms, key management, TLS configuration, secret storage |
+| **api-security** | V4, V17 | Rate limiting, resource consumption, REST/GraphQL/WebSocket security |
+| **session** | V7, V9, V10 | Token handling, session fixation, cookie attributes, JWT validation, CSRF |
+| **file-handling** | V5 | Path traversal, unrestricted upload, file type validation, storage security |
+| **data-protection** | V14 | Sensitive data exposure, privacy controls, client-side data leakage |
+| **configuration** | V13, V16 | Security headers, CORS, error handling, logging, deployment hardening |
+| **secure-coding** | V3, V15 | Frontend security, concurrency safety, architecture patterns, defensive coding |
+
+## Preconditions
+
+- Codebase is accessible and readable
+- Agent has file search and read capabilities
+- If codebase structure cannot be determined, the agent reports limitations in the audit output
+
+## Core Capabilities
+
+- **Codebase Reconnaissance**: Identifies technology stack, frameworks, entry points, and security-relevant file areas
+- **Domain-Scoped Analysis**: Systematically audits code across all 8 security domains
+- **ASVS Requirement Verification**: Checks code against applicable ASVS 5.0.0 requirements at the specified level
+- **Vulnerability Pattern Detection**: Identifies known vulnerable code patterns from the integrated knowledge base
+- **Cross-Source Correlation**: Maps findings to ASVS requirements, API Top 10 risks, CheatSheet guidance, and WSTG test IDs
+- **Severity Classification**: Rates findings as Critical/High/Medium/Low with evidence and confidence
+- **Remediation Guidance**: Provides concrete fix patterns sourced from CheatSheet Series
+- **Structured Report Generation**: Produces a comprehensive Markdown audit report
+
+## Audit Workflow
+
+```
+1. Reconnaissance    → Identify stack, structure, entry points
+2. Scope Definition  → Select applicable ASVS domains and level
+3. Domain Analysis   → Audit each security domain systematically
+4. Finding Synthesis → Deduplicate, correlate across sources, assign severity
+5. Remediation Map   → Attach fix patterns per finding
+6. Report Generation → Produce structured Markdown report
+```
+
+## Output Contract
+
+The audit produces a Markdown report containing:
+
+- **Executive Summary**: Overall risk posture, critical findings count, audit scope
+- **Findings Table**: Each finding with severity, ASVS ID, CWE, evidence, and remediation
+- **Domain Reports**: Per-domain detailed analysis with code references
+- **Remediation Roadmap**: Prioritized fix recommendations
+- **Audit Metadata**: Scope, level, limitations, methodology notes
+
+## Severity Levels
+
+| Level | Criteria |
+|-------|----------|
+| **Critical** | Exploitable vulnerability with direct security impact (RCE, SQLi, auth bypass, data breach) |
+| **High** | Significant security weakness requiring prompt remediation (broken access control, weak crypto, SSRF) |
+| **Medium** | Security concern with conditional exploitability (missing headers, verbose errors, weak validation) |
+| **Low** | Defense-in-depth improvement or best practice deviation (logging gaps, minor config issues) |
+| **Info** | Observation or recommendation with no direct security impact |
+
+## Technical References
+
+- **[audit_process.md](references/audit_process.md)**: Complete step-by-step audit methodology and reconnaissance procedures
+- **[security_domains.md](references/security_domains.md)**: All 17 ASVS domains with code-audit-relevant requirements and cross-source mappings
+- **[vulnerability_patterns.md](references/vulnerability_patterns.md)**: Concrete code-level vulnerability patterns organized by category
+- **[remediation_patterns.md](references/remediation_patterns.md)**: Secure coding fix patterns from CheatSheet Series
+- **[report_format.md](references/report_format.md)**: Detailed Markdown report structure and finding schema