feat(core): add core/event and core/provider packages

.githooks/pre-push

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Local pre-push hook. Runs `make verify` before every push so that
+# code which would fail CI never leaves the workstation.
+#
+# Enable once per clone:
+#
+#     git config core.hooksPath .githooks
+#
+# Bypass for genuine emergencies (then explain in the PR description):
+#
+#     SKIP_VERIFY=1 git push
+#
+set -euo pipefail
+
+if [ "${SKIP_VERIFY:-}" = "1" ]; then
+    echo "[pre-push] SKIP_VERIFY=1 set; skipping make verify."
+    exit 0
+fi
+
+# Read the push refs from stdin and decide whether `make verify` is
+# worth running. Skip for branch deletes (zero local OID), and skip
+# for tag-only pushes (verify gates the source state, which is already
+# the same commit the tag points at).
+all_zero='0000000000000000000000000000000000000000'
+needs_verify=0
+while read -r local_ref local_oid _remote_ref remote_oid; do
+    [ -z "${local_ref:-}" ] && continue
+    if [ "$local_oid" = "$all_zero" ]; then
+        echo "[pre-push] Skipping verify for branch delete: $local_ref"
+        continue
+    fi
+    if [ "${local_ref#refs/tags/}" != "$local_ref" ]; then
+        echo "[pre-push] Skipping verify for tag push: $local_ref"
+        continue
+    fi
+    needs_verify=1
+    echo "[pre-push] Will verify before pushing $local_ref ($local_oid -> $remote_oid)"
+done
+
+if [ "$needs_verify" -eq 0 ]; then
+    echo "[pre-push] Nothing to verify."
+    exit 0
+fi
+
+echo
+echo "[pre-push] Running 'make verify'..."
+echo "[pre-push] Set SKIP_VERIFY=1 to bypass (do not abuse)."
+echo
+
+if ! command -v make >/dev/null 2>&1; then
+    echo "[pre-push] 'make' not found on PATH; cannot run verify gate." >&2
+    exit 1
+fi
+
+start=$(date +%s)
+if make verify; then
+    end=$(date +%s)
+    echo
+    echo "[pre-push] make verify passed in $((end - start))s. Pushing."
+    exit 0
+else
+    echo
+    echo "[pre-push] make verify FAILED. Push blocked." >&2
+    echo "[pre-push] Fix the failures, re-run 'make verify' until clean, then push again." >&2
+    exit 1
+fi

.github/workflows/ci.yml

@@ -131,7 +131,11 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage.out
           flags: core
-          fail_ci_if_error: true
+          # Set to true once the repository is registered with Codecov.
+          # See docs/ci.md "Codecov registration" for the one-time setup.
+          # Until then, upload failures are non-fatal so they cannot block
+          # an otherwise-clean PR.
+          fail_ci_if_error: false
 
   build:
     name: build (${{ matrix.goos }}/${{ matrix.goarch }})

.github/workflows/fuzz.yml

@@ -83,10 +83,15 @@ jobs:
 
       - name: Fuzz
         shell: bash
+        # Values from `inputs` and `matrix` flow through env to avoid
+        # `${{ }}` interpolation inside a shell `run:` block — the
+        # standard remediation for the run-shell-injection rule.
+        env:
+          DURATION: ${{ inputs.duration }}
+          TARGET: ${{ matrix.target }}
         run: |
-          duration="${{ inputs.duration }}"
-          : "${duration:=5m}"
-          pkg="${{ matrix.target }}"
+          duration="${DURATION:-5m}"
+          pkg="$TARGET"
           fuzz_pkg="${pkg%%::*}"
           fuzz_name="${pkg##*::}"
           echo "Fuzzing $fuzz_name in $fuzz_pkg for $duration"

CONTRIBUTING.md

@@ -34,15 +34,39 @@ pre-commit install
 ### Common tasks
 
 ```sh
+make verify   # run every check CI runs that can run locally — REQUIRED before pushing
 make build    # go build ./...
 make test     # go test -race -shuffle=on -count=1 -covermode=atomic ./...
 make lint     # golangci-lint run
 make sec      # gosec + govulncheck
 make cover    # produce coverage.out and a human-readable summary
 make tidy     # go mod tidy
+make help     # full target list
 ```
 
-`make` with no arguments runs `build`, `lint`, and `test`. Run that before pushing.
+### Before every push: `make verify`
+
+`make verify` is the canonical "ready to push" gate. It runs every check the CI pipeline runs that can run locally:
+
+- `gofmt -l`, `go mod verify`, `go mod tidy -diff`
+- `go vet`, `golangci-lint config verify`, `golangci-lint run`
+- `go test -race -shuffle=on -count=1 -covermode=atomic`
+- Cross-compile build matrix (`darwin/{amd64,arm64}`, `linux/{amd64,arm64}`, `windows/amd64`)
+- `gosec`, `govulncheck`
+- **Semgrep** in the same Docker image CI uses (skipped with a warning if Docker isn't available locally — but if Docker is available and you don't run it, you cannot prove a clean run)
+- 5s fuzz pass per `Fuzz*` target
+
+**If `make verify` fails, do not push.** Fix the failure, re-run until green.
+
+### Pre-push hook (recommended)
+
+Enable the repo's pre-push hook once per clone so `make verify` runs automatically before every `git push`:
+
+```sh
+git config core.hooksPath .githooks
+```
+
+For genuine emergencies, `SKIP_VERIFY=1 git push` bypasses the hook. Don't abuse it; if you bypass, explain why in the PR description.
 
 ## Workflow
 

Makefile

@@ -1,17 +1,53 @@
-.PHONY: all build test lint sec cover tidy fmt vet vuln licenses clean help
+# Use bash for recipes — fuzz-quick uses process substitution and `pipefail`
+# semantics that POSIX /bin/sh doesn't support.
+SHELL       := /bin/bash
+.SHELLFLAGS := -eu -o pipefail -c
 
-GO        ?= go
-GOFLAGS   ?=
-PKGS      ?= ./...
-COVERPROFILE ?= coverage.out
+.PHONY: all verify build test cover lint lint-config fmt fmt-check vet \
+        sec vuln gosec semgrep semgrep-check tidy tidy-check mod-verify \
+        build-matrix licenses fuzz-quick clean help
+
+GO            ?= go
+GOFLAGS       ?=
+PKGS          ?= ./...
+COVERPROFILE  ?= coverage.out
+SEMGREP_IMAGE ?= semgrep/semgrep@sha256:326e5f41cc972bb423b764a14febbb62bbad29ee1c01820805d077dd868fea48
+FUZZTIME      ?= 5s
+
+# Build matrix mirrors ci.yml — keep in sync.
+BUILD_MATRIX = \
+  linux/amd64 \
+  linux/arm64 \
+  darwin/amd64 \
+  darwin/arm64 \
+  windows/amd64
 
 # Dev tools are pinned via the `tool` directive in go.mod (Go 1.24+) and
 # invoked through `go tool <name>`. Run `go mod tidy` after pulling to
 # materialize them locally; no separate install step is required.
 
+# `make verify` is the canonical "ready to push" gate. It runs every
+# check CI runs that can run locally. If this passes, the odds of CI
+# failing are very low; if it fails, do not push.
+#
+# Intentionally CI-only (cannot be reproduced locally without GitHub
+# infrastructure):
+#   - codeql.yml          GitHub-hosted CodeQL analysis
+#   - scorecard.yml       OpenSSF Scorecard, weekly
+#   - dependency-review   PR-context only
+#   - trivy fs SARIF      runs locally via `trivy fs .` if installed,
+#                         but the SARIF upload is GitHub-only
+#   - codecov upload      requires CODECOV_TOKEN and the registered repo
+verify: fmt-check tidy-check mod-verify vet lint-config lint test build-matrix sec semgrep-check fuzz-quick
+	@echo ""
+	@echo "  ===================================="
+	@echo "   make verify: PASS"
+	@echo "   $$(date -u +'%Y-%m-%dT%H:%M:%SZ') on $$(uname -sm)"
+	@echo "  ===================================="
+
 all: build lint test ## Run build, lint, and test.
 
-build: ## Build all packages.
+build: ## Build all packages for the host platform.
 	@out=$$($(GO) build $(GOFLAGS) $(PKGS) 2>&1); \
 		ec=$$?; \
 		if [ -n "$$out" ]; then echo "$$out"; fi; \
@@ -20,6 +56,16 @@ build: ## Build all packages.
 		fi; \
 		exit $$ec
 
+build-matrix: ## Cross-compile across the same matrix CI builds.
+	@for target in $(BUILD_MATRIX); do \
+		os=$${target%%/*}; arch=$${target##*/}; \
+		printf '  build %-15s ... ' "$$os/$$arch"; \
+		out=$$(CGO_ENABLED=0 GOOS=$$os GOARCH=$$arch $(GO) build -trimpath $(PKGS) 2>&1); \
+		ec=$$?; \
+		if [ $$ec -ne 0 ]; then echo "FAIL"; echo "$$out"; exit $$ec; fi; \
+		echo "ok"; \
+	done
+
 test: ## Run tests with race detector, shuffle, and coverage.
 	$(GO) test -race -shuffle=on -count=1 \
 		-covermode=atomic -coverprofile=$(COVERPROFILE) \
@@ -33,28 +79,106 @@ cover: test ## Show coverage summary and write coverage.html.
 lint: ## Run golangci-lint.
 	$(GO) tool golangci-lint run $(PKGS)
 
+lint-config: ## Verify .golangci.yml against the v2 schema.
+	$(GO) tool golangci-lint config verify
+
 fmt: ## Format Go code.
 	$(GO) tool goimports -w -local github.com/plexara/plexara-agents .
 
+fmt-check: ## Fail if any Go file is unformatted.
+	@unformatted=$$(gofmt -l .); \
+	if [ -n "$$unformatted" ]; then \
+		echo "Unformatted files:"; echo "$$unformatted"; \
+		echo "Run 'make fmt' and commit."; \
+		exit 1; \
+	fi
+
 vet: ## Run go vet.
 	$(GO) vet $(PKGS)
 
-sec: vuln ## Run security scanners (gosec + govulncheck).
-	$(GO) tool gosec -quiet $(PKGS)
+sec: gosec vuln ## Run security scanners (gosec + govulncheck).
 
-vuln: ## Run govulncheck.
-	$(GO) tool govulncheck $(PKGS)
+gosec: ## Run gosec.
+	$(GO) tool gosec -quiet -no-fail $(PKGS)
 
-licenses: ## Report on transitive dependency licenses.
-	$(GO) tool go-licenses report $(PKGS)
+vuln: ## Run govulncheck (skips silently if no Go source yet).
+	@if find . -name '*.go' \
+	         -not -path './.*' \
+	         -not -path './vendor/*' \
+	         -not -path '*/testdata/*' \
+	         -print -quit | grep -q .; then \
+		$(GO) tool govulncheck $(PKGS); \
+	else \
+		echo "(no Go source yet — skipping govulncheck)"; \
+	fi
+
+semgrep: ## Run Semgrep in the same Docker image CI uses.
+	@if ! command -v docker >/dev/null 2>&1; then \
+		echo "docker not installed — cannot run semgrep locally"; \
+		exit 1; \
+	fi
+	@if ! docker info >/dev/null 2>&1; then \
+		echo "docker daemon not running — cannot run semgrep locally"; \
+		exit 1; \
+	fi
+	docker run --rm -v "$$PWD:/src" -w /src $(SEMGREP_IMAGE) \
+		semgrep \
+			--config=p/security-audit \
+			--config=p/secrets \
+			--config=p/golang \
+			--config=p/owasp-top-ten \
+			--error \
+			.
+
+semgrep-check: ## Run semgrep if Docker is available; otherwise warn and continue.
+	@if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then \
+		$(MAKE) --no-print-directory semgrep; \
+	else \
+		echo ""; \
+		echo "  WARNING: semgrep skipped (Docker not available)."; \
+		echo "  CI will run it; you cannot prove a clean run without Docker."; \
+		echo ""; \
+	fi
+
+mod-verify: ## go mod verify.
+	$(GO) mod verify
 
 tidy: ## Tidy go.mod and verify modules.
 	$(GO) mod tidy
 	$(GO) mod verify
 
+tidy-check: ## Fail if go.mod / go.sum drift from `go mod tidy`.
+	@diff=$$($(GO) mod tidy -diff); \
+	if [ -n "$$diff" ]; then \
+		echo "go.mod / go.sum drift detected; run 'make tidy' and commit."; \
+		echo "$$diff"; \
+		exit 1; \
+	fi
+
+fuzz-quick: ## Run each Fuzz* target for FUZZTIME (default 5s).
+	@found=0; \
+	while IFS= read -r pkg; do \
+		[ -z "$$pkg" ] && continue; \
+		while IFS= read -r fuzz; do \
+			[ -z "$$fuzz" ] && continue; \
+			found=1; \
+			printf '  fuzz %s/%s for %s ... ' "$$pkg" "$$fuzz" "$(FUZZTIME)"; \
+			out=$$($(GO) test "$$pkg" -run='^$$' -fuzz="^$$fuzz\$$" -fuzztime=$(FUZZTIME) 2>&1); \
+			ec=$$?; \
+			if [ $$ec -ne 0 ]; then echo "FAIL"; echo "$$out"; exit $$ec; fi; \
+			echo "ok"; \
+		done < <($(GO) test -list 'Fuzz.*' "$$pkg" 2>/dev/null | awk '/^Fuzz/'); \
+	done < <($(GO) list ./... 2>/dev/null); \
+	if [ $$found -eq 0 ]; then \
+		echo "(no Fuzz* targets discovered — skipping)"; \
+	fi
+
+licenses: ## Report on transitive dependency licenses.
+	$(GO) tool go-licenses report $(PKGS)
+
 clean: ## Remove build artifacts.
 	rm -rf bin dist
 	rm -f $(COVERPROFILE) coverage.html
 
 help: ## Show this help.
-	@awk 'BEGIN {FS = ":.*##"; printf "\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+	@awk 'BEGIN {FS = ":.*##"; printf "\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)