add CLAUDE.md and review-interactive skill for claude

.claude/skills/review-interactive/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: review-interactive
+description: Review code changes in the KPHP compiler and runtime codebase interactively
+---
+
+# Workflow
+
+## 1. Scope Definition
+
+When invoked, ask the user:
+
+1. **What to review:**
+   - Branch vs branch (e.g., `feature-branch` against `master`)
+   - Commit vs commit/branch (e.g., `abc123` against `HEAD`)
+   - Specific files or directories
+
+2. **Review mode:** Is this your own PR (self-review) or someone else's PR?
+   - **Self-review:** I will offer to apply fixes as we find them
+   - **Someone else's PR:** I will collect all findings and offer to export/push to GitHub at the end
+
+Collect the diff using `git diff` with function context (`--function-context`).
+
+## 2. Context Expansion
+
+During review, if a code chunk lacks sufficient context to evaluate properly, ask the user for permission to read the full file. Examples of when context expansion is needed:
+- Understanding class invariants or preconditions
+- Checking function signatures not shown in the diff
+- Verifying include/dependency relationships
+- Understanding the full implementation of modified functions
+- Checking for existing patterns that should be followed
+
+Ask the user: "I need to see more context in `file.cpp` to properly evaluate this change. May I read the full file?"
+
+Proceed based on user response:
+- If **yes**: Read the file and continue review with expanded context
+- If **no**: Note the limitation and continue with available context, or skip the ambiguous section
+
+## 3. Verification with clangd
+
+Use `clangd-18` to verify code correctness:
+- Run from project root: `clangd-18 --check=<path/to/file.cpp>`
+- This picks up `.clangd` config automatically (which includes the compilation database location)
+- Use to verify: includes are correct, standard library features are available, missing dependencies
+- When unsure about C++ includes or standard library usage, check with clangd before commenting
+
+## 4. Review Loop
+
+For each logical chunk of changes:
+
+1. **Analyze** the code against the rules below
+   - **Important:** Only review code that was actually modified by the author (present in the diff)
+   - Do not flag issues in pre-existing, untouched code unless it directly relates to the changes being made
+   - If you need to reference unchanged code for context, clearly distinguish it from the actual changes
+2. **Present** findings wrapped in `<findings>` tags with:
+   - File location and line numbers
+   - Severity: `suggestion`, `nit`, or `issue`
+   - Clear explanation of the concern
+   - Proposed alternative when applicable
+3. **Ask** the user for feedback on your thoughts
+4. **Adapt** based on user responses (skip similar issues if asked, dive deeper if requested)
+
+For large changes, feel free to use light humor occasionally to keep the review relaxed and enjoyable for the reviewer.
+
+## 5. External PR Review Mode
+
+When reviewing someone else's PR (as determined in Step 1):
+
+1. **Collect all findings** during the review without offering to apply fixes
+2. Present findings as structured comments for later export
+3. **At completion**, offer to:
+   - **Export to file**: Create a markdown file with all findings
+   - **Push to GitHub**: Use `gh` CLI to post review comments to the PR:
+     ```bash
+     # For each finding, create a review comment
+     gh pr review <PR-number> --comment --body "comment text" -- <file>
+
+     # Or create a single review with all comments
+     gh pr review <PR-number> --request-changes --body-file review-comments.md
+     ```
+
+## 6. Completion
+
+Summarize all findings and ask based on review mode:
+
+**For self-review:**
+- Apply any automated fixes
+- Continue reviewing other changes
+
+**For external PR review:**
+- Export findings to a file
+- Push review comments to GitHub PR
+
+---
+
+# Review Rules
+
+## General Principles
+
+Act like a senior developer who prioritizes:
+
+| Priority | Principle |
+|----------|-----------|
+| 1 | **Readability** - Clear naming, early returns, explicit error handling, meaningful comments |
+| 2 | **Standard mechanisms** - Prefer C++ standard library over custom solutions |
+| 3 | **Reusability** - Non-PHP-specific code should be written in a PHP-agnostic way |
+| 4 | **C++ best practices** - RAII, proper include hygiene (no transitive/missing includes), namespaces, fully qualified identifiers |
+| 5 | **Consistency** - Follow existing patterns in the codebase; note when a diff introduces pattern changes |
+
+## Component-Specific Rules
+
+### Compiler (`/compiler/`)
+
+- C++17 standard
+- Follow existing AST transformation patterns
+
+### All Runtimes (`/runtime-common/`, `/runtime/`, `/runtime-light/`)
+
+- All functions should be marked `noexcept` without any considerations
+- **PHP function naming**: All PHP standard library functions must use the `f$` prefix (e.g., `f$array_merge`)
+
+### Common Runtime (`/runtime-common/`)
+
+- C++17 standard
+- **Thread-safe**: All code must be safe for concurrent execution
+- **No resource ownership**: Code must not directly own system resources (files, sockets, malloc memory)
+
+### Legacy Runtime (`/runtime/`)
+
+- C++17 standard
+
+### K2 Runtime (`/runtime-light/`)
+
+- C++23 standard
+- **Thread-safe**: All code must be safe for concurrent execution
+- **No resource ownership**: Code must not directly own system resources; request them through the `k2::` interface instead
+- **Fork-aware coroutines**: When calling a coroutine, wrap the call with `kphp::forks::id_managed` unless the coroutine is a KPHP standard library function (prefixed with `f$`), which already handles this internally
+- **Braced initialization**: Always use braced initialization (e.g., `T obj{};`) unless parentheses are semantically required (e.g., `std::vector<int> v(10, 0);` for size/value construction)
+- **Log messages**: Log messages should start with a lowercase letter
+- **Type naming**: Types should begin with a lowercase letter (e.g., `task`, `component`, `buffer`). Exception: `*State` types (e.g., `InstanceState`, `ConfdataImageState`, `RpcServerInstanceState`) are currently permitted (this exception is temporary)
+- **KPHP types in ImageState/ComponentState**: KPHP types (`array`, `string`, `mixed`, `class_instance`) that are members of `*ImageState` or `*ComponentState` types must set their reference counter to `ExtraRefCnt::ForGlobalConst` to prevent data races. Prefer `kphp::core::set_reference_counter_recursive` over `obj.set_reference_counter_to`
+
+---
+
+# Output Format
+
+Use this structure for findings:
+
+```
+<findings>
+### File: `path/to/file.cpp` (lines 45-52)
+**Severity:** suggestion
+
+**Issue:** Brief description of the concern
+
+**Rationale:** Why this matters (referencing specific rules above)
+
+**Suggestion:** Concrete alternative or fix
+</findings>
+```
+
+Severity levels:
+- `issue` - Likely bug or violation of hard requirements (thread-safety, resource ownership)
+- `suggestion` - Improvement to readability, maintainability, or adherence to best practices
+- `nit` - Minor stylistic preference, optional to address

CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+KPHP is a programming language developed at VK and open-sourced in 2020.
+This repository contains the KPHP compiler, which compiles a limited subset of PHP to native binaries,
+along with two language runtimes. While KPHP focuses primarily on supporting PHP features, it also
+includes additional functionality, such as asynchronous programming, a custom RPC client and server,
+and various optimizations used at VK.
+
+Project documentation is located at `/docs/`.
+
+## Architecture Overview
+
+KPHP consists of the following components:
+
+### 1. Compiler (`/compiler/`)
+
+Translates PHP to C++ through a pipeline:
+- **Lexer** (`lexer.cpp`, `keywords.gperf`) - tokenizes PHP source
+- **Parser** (`gentree.cpp`) - builds AST from tokens
+- **AST Vertices** - defined in `vertex-desc.json`, auto-generated to `objs/generated/auto/`
+- **Pipeline passes** (`/compiler/pipes/`) - transform AST through multiple stages
+- **Type inferring** (`/compiler/inferring/`) - builds type graph and infers all variable types
+- **Code generation** (`/compiler/code-gen/`) - outputs C++ from final AST
+
+### 2. Common Runtime
+
+Implements the PHP standard library and types used by both runtimes:
+- **Types**: string, array, mixed, class_instance - all copy-on-write
+- **Functions**: all PHP functions prefixed with `f$` (e.g., `f$array_merge`)
+- **Memory management**: pre-allocated buffer with slab allocator
+
+### 3. Legacy Runtime (`/runtime/`)
+
+Implements the PHP standard library and types:
+- **Async**: resumable functions for forks/RPC
+
+Function declarations are in `/builtin-functions/kphp-full/_functions.txt`:
+```
+function array_merge ($a ::: array, ...$args) ::: ^1;
+```
+
+### 4. Server (`/server/`)
+
+Pre-fork master/worker HTTP/RPC server architecture:
+- Master process forks worker processes
+- Workers accept TCP connections on a shared port
+- Each worker handles one request at a time
+- Supports keep-alive connections
+- Signals: SIGKILL (immediate stop), SIGTERM (graceful shutdown), SIGUSR1 (log rotate)
+
+### 5. vkext (`/vkext/`)
+
+PHP extension for development that exposes the network layer and RPC/TL to plain PHP.
+
+### 6. Common (`/common/`)
+
+Shared utilities: TL parsing, RPC, crypto, allocators, containers.
+
+### 7. New Runtime (K2) (`/runtime-light/`)
+
+An alternative KPHP runtime that is asynchronous and re-entrant. It allows a single thread to switch
+between multiple requests. Each KPHP program compiles into an image represented by a dynamic library.
+A single image can produce multiple components (an image with passed arguments).
+Incoming HTTP/RPC requests are handled by isolated, stateless component instances.
+
+K2 runtime must follow these rules:
+- It must be thread-safe, as a thread may switch to executing another instance at any time
+- It must be stateless; all state is managed by the external K2 platform via the C API
+  declared at `/runtime-light/k2-platform/k2-header.h`.
+
+## Code Style
+
+- C++17 for the Legacy Runtime, C++23 for the K2 runtime
+- Use `.clang-format` and `.clangd` configs
+- Follow existing patterns in the codebase
+
+## Debugging
+
+- Use `KPHP_VERBOSITY=3` for detailed compilation output
+- C++ code is generated to `objs/generated/` (or the build directory)
+- Use `objs/bin/kphp2cpp --help` for compiler options
+- The `-M cli` mode compiles to a CLI binary instead of a server