docs: reassessment — README, ROADMAP, AGENTS, cockpit spec, implementation plan

.github/workflows/ci.yml

@@ -0,0 +1,116 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # ── Shell: ShellCheck ────────────────────────────────────────────────────────
+  shellcheck:
+    name: ShellCheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Run ShellCheck
+        uses: ludeeus/action-shellcheck@master
+        with:
+          ignore_paths: tests/*
+
+  # ── Python: grid-messenger ───────────────────────────────────────────────────
+  python-lint:
+    name: Python (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - name: Ruff check
+        run: ruff check core/messenger/src/
+      - name: Ruff format check
+        run: ruff format --check core/messenger/src/
+
+  # ── Version consistency ──────────────────────────────────────────────────────
+  version-check:
+    name: Version consistency
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Compare VERSION vs install.sh
+        run: |
+          FILE_VER="$(cat VERSION)"
+          SCRIPT_VER="$(grep -oE '[0-9]+\.[0-9]+\.[0-9]+' install.sh | head -1)"
+          echo "VERSION file : ${FILE_VER}"
+          echo "install.sh   : ${SCRIPT_VER}"
+          if [[ "$FILE_VER" != "$SCRIPT_VER" ]]; then
+            echo "::error::Version mismatch: VERSION=${FILE_VER} install.sh=${SCRIPT_VER}"
+            exit 1
+          fi
+
+  # ── Bats test suite ──────────────────────────────────────────────────────────
+  bats:
+    name: Bats Tests
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Make scripts executable
+        run: |
+          chmod +x install.sh
+          find tests -type f -name "*.sh" -exec chmod +x {} \;
+      - name: Run unit tests
+        run: tests/run_tests.sh --unit
+      - name: Run functional tests
+        run: tests/run_tests.sh --functional
+      - name: Run smoke tests
+        run: tests/run_tests.sh --smoke
+
+  # ── Forbidden artifacts ──────────────────────────────────────────────────────
+  forbid-artifacts:
+    name: Forbid artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Fail if forbidden paths are tracked
+        run: |
+          set -euo pipefail
+          if git ls-files | grep -qE '(\.ssh/|\.db($|-)|.*\.sqlite|.*\.log$|\.env$)'; then
+            echo "ERROR: forbidden files are tracked:"
+            git ls-files | grep -E '(\.ssh/|\.db($|-)|.*\.sqlite|.*\.log$|\.env$)' || true
+            exit 1
+          fi
+      - name: Fail if history contains forbidden blobs
+        run: |
+          set -euo pipefail
+          if git rev-list --objects --all | grep -qE '(\.ssh/|.*\.db($|-)|.*\.sqlite|.*\.log$)'; then
+            echo "ERROR: forbidden artifacts exist in history:"
+            git rev-list --objects --all \
+              | grep -E '(\.ssh/|.*\.db($|-)|.*\.sqlite|.*\.log$)' || true
+            exit 1
+          fi
+
+  # ── CI Gate (aggregator — required by branch protection) ─────────────────────
+  gate:
+    name: CI Gate
+    runs-on: ubuntu-latest
+    needs: [shellcheck, python-lint, version-check, bats, forbid-artifacts]
+    if: always()
+    steps:
+      - name: All required checks passed
+        run: |
+          if [[ "${{ needs.shellcheck.result }}"        != "success" ]] ||
+             [[ "${{ needs.python-lint.result }}"       != "success" ]] ||
+             [[ "${{ needs.version-check.result }}"     != "success" ]] ||
+             [[ "${{ needs.bats.result }}"              != "success" ]] ||
+             [[ "${{ needs.forbid-artifacts.result }}"  != "success" ]]; then
+            echo "::error::One or more required checks failed — merge blocked."
+            exit 1
+          fi
+          echo "All required checks passed."

AGENTS.md

@@ -8,12 +8,14 @@ This repository is `faigrid`, the official realization of **fusionAIze Grid**.
 Its job is to define **where** AI-native workloads execute, under **what constraints**, with **what isolation**, through which **queues/runners**, and with which **secrets, observability, and backup patterns**.
 
 It physically provisions and structurally connects the 4+1 Node Architecture:
-1. **grid-edge**: Edge ingress workloads (Public intake, TLS, reverse proxy, SSO).
-2. **grid-core**: Trusted internal services and queued automations (n8n, orchestration helpers).
+1. **grid-edge**: Edge ingress workloads (Public intake, TLS, Caddy reverse proxy, Pi-hole DNS, SSO).
+2. **grid-core**: Trusted internal services and queued automations (n8n, openclaw, codenomad, faigate, grid-messenger).
 3. **grid-worker**: Specialized runners, local model workers (LAN-only inference), and isolated task workers.
-4. **grid-backup**: Recovery and observability layer.
+4. **grid-backup**: Recovery and observability layer (Restic, Synology).
 5. **grid-external**: Cloud model bridges and distributed extensions.
 
+Grid feeds structured runtime health signals (runner failures, service state, queue backlog) into **fusionAIze Signal** (`faisignal`) for cross-layer operational intelligence. Grid's cockpit surface and Signal's ingestion pipeline are designed to be complementary, not overlapping.
+
 In the fusionAIze ecosystem, Grid runs the compute topology. It is explicitly **decoupled** from `fusionAIzeOS`, which serves as the "team operating logic" (defining *how* humans and virtual AI coworkers collaborate, roles, and identity).
 
 **Key Tenets:**
@@ -26,8 +28,10 @@ In the fusionAIze ecosystem, Grid runs the compute topology. It is explicitly **
 
 The priority is maintaining a universal, highly secure, and easily deployable execution substrate.
 
-Do not optimize the repository around complex web frameworks, operating logic dashboards, or model routing logic (which belong in OS, Studio, or Gate).
-Optimize it around rock-solid shell orchestration (`install.sh`), state detection (`.grid-state`), cleanly isolated Workbench plugin registries (`plugins/`), runner layer definition (`docker compose`), and robust Bash-level testing (`tests/`).
+Do not optimize the repository around complex web frameworks, operating logic dashboards, or model routing logic (which belong in OS, Gate, and Lens).
+Optimize it around rock-solid shell orchestration (`install.sh`), state detection (`~/.config/faigrid/registry/`), cleanly isolated Workbench plugin registries (`plugins/`), runner layer definition (`docker compose`), and robust Bash-level testing (`tests/`).
+
+The Grid Cockpit (planned v2.0) is an exception to the "no web framework" rule — it is a lightweight, no-build, single-file HTML dashboard served by the existing Python messenger process. It stays inside Grid's scope: node health, service status, pending decisions, workbench state. It does not replicate Gate analytics or Signal correlation.
 
 ## Architecture principles