add session-start hook for Claude Code web sessions

.claude/hooks/session-start.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+set -euo pipefail
+
+# Only run in remote (web) sessions
+if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
+  exit 0
+fi
+
+# Install PHP (8.2+) if missing or below minimum version
+if ! command -v php &>/dev/null || ! php -r "exit(version_compare(PHP_VERSION, '8.2.0', '>=') ? 0 : 1);"; then
+  echo "Installing PHP..."
+  DEBIAN_FRONTEND=noninteractive apt-get update -qq
+  DEBIAN_FRONTEND=noninteractive apt-get install -y -qq \
+    php-cli php-xml php-mbstring php-zip
+fi
+
+# Install Composer if missing
+if ! command -v composer &>/dev/null; then
+  echo "Installing Composer..."
+  curl -sS https://getcomposer.org/installer \
+    | php -- --install-dir=/usr/local/bin --filename=composer
+fi
+
+# Attempt to install pcov (needed for coverage; best-effort, not fatal)
+if ! php -m 2>/dev/null | grep -q pcov; then
+  PHP_VER=$(php -r "echo PHP_MAJOR_VERSION.'.'.PHP_MINOR_VERSION;")
+  DEBIAN_FRONTEND=noninteractive apt-get install -y -qq "php${PHP_VER}-pcov" 2>/dev/null \
+    || echo "Note: pcov could not be installed - coverage reporting will be skipped"
+fi
+
+# Persist env vars for the session
+echo 'export COMPOSER_ALLOW_SUPERUSER=1' >> "$CLAUDE_ENV_FILE"
+
+# Install project dependencies
+cd "$CLAUDE_PROJECT_DIR"
+COMPOSER_ALLOW_SUPERUSER=1 composer install \
+  --no-interaction \
+  --prefer-dist \
+  --optimize-autoloader

.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.gitignore

@@ -36,5 +36,5 @@ clover.xml
 # Logs
 *.log
 
-# Claude
-.claude
+# Claude (local-only overrides - do not commit)
+.claude/settings.local.json

CLAUDE.md

@@ -66,6 +66,8 @@ This runs all quality checks in one command:
 
 Only consider your changes complete when `make check` passes with all green checks.
 
+> **Note (Claude Code web sessions):** `make check` runs linting and static analysis successfully, but test coverage (`composer test:coverage`) requires the pcov PHP extension which is not available in the web session environment. Run `make test` to verify tests pass locally, then push to CI and inspect the coverage results there.
+
 ## Core Architecture
 
 ### State Flow Execution Model

Makefile

@@ -2,9 +2,16 @@
 
 # Docker configuration
 IMAGE_NAME = stateflow-php
-DOCKER_RUN = docker run --rm -v $(PWD):/app -w /app $(IMAGE_NAME)
 DOCKER_RUN_IT = docker run --rm -it -v $(PWD):/app -v $(HOME)/.gitconfig:/home/appuser/.gitconfig:ro -v $(HOME)/.ssh/:/home/appuser/.ssh:ro -w /app $(IMAGE_NAME)
 
+# Use Docker when available and the image exists; otherwise run natively on the host PHP binary
+DOCKER_AVAILABLE := $(shell command -v docker >/dev/null 2>&1 && docker image inspect $(IMAGE_NAME) >/dev/null 2>&1 && echo true || echo false)
+ifeq ($(DOCKER_AVAILABLE),true)
+    DOCKER_RUN = docker run --rm -v $(PWD):/app -w /app $(IMAGE_NAME)
+else
+    DOCKER_RUN =
+endif
+
 help: ## Show this help message
 	@echo 'Usage: make [target]'
 	@echo ''