feat(e90): dev-environment hardening — config consolidation, CI gates, tooling debt

.githooks/commit-msg

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# commit-msg hook: enforces Conventional Commits format
+# format: <type>(<scope>): <subject>
+set -euo pipefail
+
+msg_file="$1"
+msg=$(head -n 1 "$msg_file")
+
+# Allow merge commits or fixup/squash commits
+if echo "$msg" | grep -qE "^(Merge branch|Merge pull request|fixup!|squash!)"; then
+    exit 0
+fi
+
+# Regex for Conventional Commits
+CC_REGEX="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9_-]+\))?!?: .+$"
+
+if ! echo "$msg" | grep -qE "$CC_REGEX"; then
+    echo "❌ [hook-commits] Invalid commit message format:" >&2
+    echo "   '$msg'" >&2
+    echo "" >&2
+    echo "   Commit message must follow Conventional Commits format:" >&2
+    echo "   <type>(<scope>): <subject>" >&2
+    echo "   Example: feat(auth): add project scoping to JWT" >&2
+    echo "   Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert" >&2
+    exit 1
+fi
+
+# Check for AI attribution
+if grep -qiE "Co-authored-by:\s*(Claude|Gemini|ChatGPT|OpenAI|Anthropic|Copilot|AI|Assistant)" "$msg_file"; then
+    echo "❌ [hook-commits] AI attribution footer (Co-authored-by) is prohibited in commit message." >&2
+    exit 1
+fi
+
+exit 0

.githooks/pre-commit

@@ -44,6 +44,16 @@ if [ -n "$STAGED_SRC" ]; then
     fi
 fi
 
+# Unresolved merge-conflict markers must never be committed. One
+# implementation (scripts/check-conflict-markers.sh) backs both this hook and
+# the CI verify job.
+if [ -x scripts/check-conflict-markers.sh ]; then
+    if ! bash scripts/check-conflict-markers.sh; then
+        echo "❌ Resolve the conflict markers before committing"
+        exit 1
+    fi
+fi
+
 # Required env keys (deploy.yml REQUIRED_ENV_KEYS) must be documented in
 # .env.example — the BIGBASE_ROOT_ENCRYPTION_KEY class of config drift. This
 # mirrors the CI verify gate (scripts/check-required-env-documented.sh).

.githooks/pre-push

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Pre-push hook: blocks direct manual push to protected branch 'main'
+# unless GIT_BIGPOWERS_LAND=1 (set by automated landing scripts)
+
+set -euo pipefail
+
+protected_branch="main"
+current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || true)
+
+# Read stdin lines: <local ref> <local sha> <remote ref> <remote sha>
+while read -r local_ref local_sha remote_ref remote_sha; do
+    remote_branch=$(echo "$remote_ref" | sed 's#refs/heads/##')
+    if [ "$remote_branch" = "$protected_branch" ] || [ "$current_branch" = "$protected_branch" ]; then
+        if [ "${GIT_BIGPOWERS_LAND:-0}" != "1" ]; then
+            echo "❌ [guard-git] Direct push to protected branch '$protected_branch' is blocked." >&2
+            echo "   Use a feature branch and land via 'scripts/land-branch.sh' or set GIT_BIGPOWERS_LAND=1." >&2
+            exit 1
+        fi
+    fi
+done
+
+exit 0

.github/workflows/test-build-release.yml

@@ -282,8 +282,13 @@ jobs:
           go-version: '${{ env.GO_VERSION }}'
           cache: true
 
+      # go test applies -timeout per package binary. The deploy package is the
+      # long pole (~250-300s under -race on a loaded dev machine) and was
+      # hitting the old 300s ceiling as a timeout panic rather than a race
+      # report — a gate that fails for the wrong reason. 600s keeps 2x headroom
+      # while still catching a genuine hang; the job itself allows 20 minutes.
       - name: Race tests
-        run: go test -race -timeout 300s ./components/deploy/... ./components/functions/... ./components/realtime/... ./components/monitoring/...
+        run: go test -race -timeout 600s ./components/deploy/... ./components/functions/... ./components/realtime/... ./components/monitoring/...
 
   # ============================================================================
   # JOB: Test (E2E) — browser and API flows against an isolated server.
@@ -400,12 +405,7 @@ jobs:
         run: gitleaks detect --source . --no-git --no-banner --config .gitleaks.toml
 
       - name: Check conflict markers
-        run: |
-          if git grep -n -E '^(<<<<<<<|>>>>>>>)( |$)|^=======$' -- \
-            ':!CHANGELOG.md' ':!specs/archive/**'; then
-            echo "ERROR: unresolved merge-conflict marker found"
-            exit 1
-          fi
+        run: bash scripts/check-conflict-markers.sh
 
       # Required deploy env keys (deploy.yml REQUIRED_ENV_KEYS) must be
       # documented in .env.example — catches the BIGBASE_ROOT_ENCRYPTION_KEY
@@ -419,6 +419,12 @@ jobs:
       - name: Check MCP adapter files are up-to-date
         run: bash scripts/gen-mcp-configs.sh --check
 
+      # The gates above are only trustworthy if their detection logic is
+      # exercised — these tests drive each script's failing path against
+      # throwaway fixtures (e90s01/s02/s05/s07).
+      - name: Gate script tests
+        run: node --test scripts/*.test.cjs
+
       - name: Check Conventional Commits
         run: bash scripts/check-conventional-commits.sh
 

.gitignore

@@ -72,15 +72,16 @@ allure-history/
 .pi/
 .mimocode/
 mimocode.jsonc
-<stdin>
 .agents/mcp_config.json
 agentic-cps/
 
 # Cursor IDE local config (may contain API keys)
 .cursor/
 
-# Python bytecode
+# Python bytecode and venvs
 __pycache__/
+.venv/
+venv/
 
 # Generated docs (regenerated by gate-trace / skills)
 specs/TRACEABILITY_LATEST.md

AGENTS.md

@@ -1,3 +1,45 @@
+# BigBase — Engineering & Agent Rules
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+Single-binary, component-based BaaS platform using Entity-Component-Construct (ECC) architecture.
+Stack: Go 1.26.3 / ECC Kernel + Plugins / SQLite + PostgreSQL
+
+## Commands
+| Action | Command |
+|--------|---------|
+| Run    | `go run .` |
+| Test   | `go test ./...` |
+| Build  | `go build -o bigbase .` |
+| Lint   | `golangci-lint run ./...` |
+| Preflight | `npm run preflight` |
+| Test coverage | `go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out` |
+
+## Session Start
+Before starting work in any session:
+1. Read `CLAUDE.md` and `CONVENTIONS.md`.
+2. Read `specs/state.yaml` and `specs/release-plan.yaml`.
+3. Check active epic and story under `specs/epics/`.
+
+## Agent Rules
+- Read specs YAML (not `specs/archive/`) before writing code.
+- All planning specifications MUST be written under `specs/` before code.
+- Write minimum code that solves the stated problem.
+- Run tests after every change. Show evidence before declaring done.
+- Follow Conventional Commits format (`feat:`, `fix:`, `chore:`, etc.).
+- NEVER include `Co-authored-by` or AI attribution in commits.
+
+## Model Routing Matrix
+
+| Task Category | Optimal Model | Reason |
+| :--- | :--- | :--- |
+| **Global Planning & ADRs** | `Claude Opus 4.6 (Thinking)` or `Gemini 3.1 Pro (High)` | Deep reasoning, architecture trade-offs |
+| **Codebase Context Search** | `Claude Sonnet 4.6` or `Gemini 3.1 Pro (Low)` | Balanced context window + speed |
+| **Feature Coding & TDD Loops** | `Claude Sonnet 4.6 (Thinking)` or `Gemini 3.1 Pro (High)` | Precision coding, exact syntax execution |
+| **Verification & Utility Tasks** | `Claude Haiku 3.5` or `Gemini 3.5 Flash` | Low latency for lint/test/compile |
+| **Browser UI Testing** | `Claude Haiku 3.5` or `Gemini 3.5 Flash (Low)` | Fast image/visual processing |
+
 ## ctxo MCP Tool Usage
 
 Use ctxo MCP tools before source changes when the index is available and fresh. If ctxo is unavailable or stale, continue with LSP and repository search; do not block development on an external index.
@@ -8,7 +50,7 @@ Use ctxo MCP tools before source changes when the index is available and fresh.
 3. Only then read and edit source files
 
 ### Before Starting a Task
-| Task Type | REQUIRED First Call |
+| Task Type | First Call (when ctxo is available) |
 |---|---|
 | Fixing a bug | `get_context_for_task(taskType: "fix")` |
 | Adding/extending a feature | `get_context_for_task(taskType: "extend")` |
@@ -159,3 +201,12 @@ Env vars: `OPENSRC_HOME` (cache location), `GITHUB_TOKEN` / `GITLAB_TOKEN` / `BI
 ### The Rule
 
 **opensrc is for reading code, not docs.** When your question is "how does X work internally?" or "what does this function actually do?", reach for opensrc first. The source is the ground truth — types, docs, and blog posts are approximations. Only fall back to `web_search`, `fetch_content`, or `context7` when you need documentation, usage examples, community patterns, or repo metadata that isn't in the source.
+
+<!-- BEGIN sqz-claude-guidance (auto-installed by sqz init; remove this block to disable) -->
+
+## sqz — Context Compression (READ FIRST)
+
+sqz is installed in this project. Prefer `sqz_read_file`, `sqz_grep`, `sqz_list_dir` MCP tools
+over the built-in Read/Grep/Glob for any file > ~2KB. Repeat reads return a `§ref:HASH§` token.
+
+<!-- END sqz-claude-guidance -->

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONVENTIONS.md

@@ -1,5 +1,26 @@
 # BigBase Conventions
 
+## Commands
+| Action | Command |
+|--------|---------|
+| Run    | `go run .` |
+| Test   | `go test ./...` |
+| Build  | `go build -o bigbase .` |
+| Lint   | `golangci-lint run ./...` |
+| Preflight | `npm run preflight` |
+| Test coverage | `go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out` |
+
+## Stack Profile
+Stack Profile: none (custom Go/ECC profile per CONVENTIONS.md)
+
+## Never-Do List
+- **Never** commit secrets, private keys, or API tokens.
+- **Never** force-push (`--force` or `--force-with-lease`) to `main`.
+- **Never** include `Co-authored-by` or any AI attribution in git commits.
+- **Never** bypass access controls, permission checks, or security gates.
+- **Never** directly import between components without going through kernel event bus.
+- **Never** mutate inputs or assert on timing sleeps in tests (poll or synchronize channels).
+
 ## Architecture
 
 ### Entity-Component-Construct (ECC)
@@ -89,6 +110,11 @@ in history).
   with a short interval up to a timeout, then assert.
 - Canonical example: `waitForHostRegistration` in the deploy component tests
   (commit `336614804`) — copy that shape rather than sprinkling `time.Sleep`.
+- Audit-trail example: `waitForStatusHistory` (`components/deploy/drain_test.go`,
+  e90s04). `TransitionState` commits `status` before appending
+  `status_history`, so status and history are eventually consistent for
+  readers — poll for the transition, never read history once after seeing the
+  status.
 - Prove it: `go test -race -count=20 ./...` must run without flakes.
 
 ## Project Structure

GEMINI.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -0,0 +1,30 @@
+.PHONY: all build test test-scripts lint preflight mcp mcp-check clean
+
+all: build
+
+build:
+	go build -o bigbase .
+
+test:
+	go test ./...
+
+# Gate-script tests (bash gates driven from Node's test runner).
+test-scripts:
+	node --test scripts/*.test.cjs
+
+lint:
+	golangci-lint run ./...
+
+preflight:
+	npm run preflight
+
+# MCP adapters are generated from the canonical .mcp.json — edit that file,
+# then regenerate. `make mcp-check` is what CI runs.
+mcp:
+	bash scripts/gen-mcp-configs.sh
+
+mcp-check:
+	bash scripts/gen-mcp-configs.sh --check
+
+clean:
+	rm -f bigbase bigbase-linux-amd64 bigbase-darwin-* bigbase_linux *.test *.out coverage.out

components/deploy/deploy.go

@@ -119,6 +119,9 @@ type Deploy struct {
 	DrainTimeout        time.Duration
 	oldDeploymentsMu    sync.RWMutex
 	oldDeployments      map[string][]string
+	// draining guards against a second drain racing the first one (a
+	// deployment can be collected by two triggers before either drain ends).
+	draining            map[string]bool
 	dbDriver            string
 	dbDSN               string
 	diagnosisReader     DeployDiagnosisReader
@@ -225,6 +228,7 @@ func New(opts Options) *Deploy {
 		sm:             NewStateMachine(),
 		DrainTimeout:   drainTimeout,
 		oldDeployments: make(map[string][]string),
+		draining:       make(map[string]bool),
 		dbDriver:       opts.DBDriver,
 		dbDSN:          opts.DBDSN,
 	}