Added docker-based testing environment for neo4j integration testing.

AGENTS.md

@@ -1,9 +1,5 @@
 # go-heartwood
 
-## Agent Skills
-- Skills are located in `~/.pi/agent/skills/`
-- Skill scripts are located in their respective skill directories under `scripts/` -- look for them there, not in this repository.
-
 ## Testing
-- Baseline: `go test -race -gcflags "all=-d=checkptr=0" ./...`
+- Baseline: `./test dev -race -gcflags "all=-d=checkptr=0" ./...`
 - `boltdb/bolt@v1.3.1` triggers a `checkptr` panic under race instrumentation; this is an upstream bug, not a project defect.

compose.yaml

@@ -0,0 +1,37 @@
+services:
+  test:
+    image: golang:1.26
+    environment:
+      CGO_ENABLED: 1
+      NEO4J_USER: neo4j
+      NEO4J_PASS: heartwood
+      NEO4J_URI: bolt://neo4j:7687
+    working_dir: /app
+    volumes:
+      - ".:/app"
+      - go-mod-cache:/go/pkg/mod
+      - go-build-cache:/root/.cache/go-build
+    depends_on:
+      neo4j:
+        condition: service_healthy
+    restart: always
+    command: "tail -f /dev/null"
+    healthcheck:
+      test: ["CMD-SHELL", "go version | grep -q 'go version'"]
+      start_period: 20s
+  neo4j:
+    image: neo4j:5
+    environment:
+      - NEO4J_AUTH=neo4j/heartwood
+    restart: always
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "cypher-shell -u neo4j -p heartwood 'RETURN 1;' 2>/dev/null | grep -q '1'",
+        ]
+      start_period: 20s
+
+volumes:
+  go-mod-cache:
+  go-build-cache:

test

@@ -0,0 +1,18 @@
+#!/bin/bash
+set -eou pipefail
+case "${1:-dev}" in
+dev) docker compose up -d --wait && docker compose exec test go test "${@:2}" ;;
+ci) docker compose run --rm test go test "${@:2}" ;;
+*)
+  echo "Usage: $0 [dev|ci] [go test arguments...]"
+  echo
+  echo "Commands:"
+  echo "    dev    Start services and run tests in the existing test container (default)."
+  echo "    ci     Execute tests in a new, one-off container and clean up."
+  echo
+  echo "Examples:"
+  echo "    $0 dev ./... -v"
+  echo "    $0 ci -run TestSpecificFunction"
+  exit 1
+  ;;
+esac