diff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.yml
new file mode 100644
index 0000000..0870085
--- /dev/null
+++ b/.github/workflows/security-scan.yml
@@ -0,0 +1,69 @@
+name: Security Scan
+
+# Shared security-scanning workflow for the nexus-substrate org.
+# Gating job: secret scan (gitleaks) — fails the run if secrets are found.
+# Informational jobs: dependency/vuln (trivy) and SAST (semgrep) report findings
+# in the logs but do not block merges (continue-on-error), so pre-existing
+# dependency noise doesn't wedge the pipeline.
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-scan-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  secrets:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install gitleaks
+        run: |
+          set -euo pipefail
+          url=$(curl -sSfL -H "Authorization: Bearer ${{ github.token }}" \
+            https://api.github.com/repos/gitleaks/gitleaks/releases/latest \
+            | grep -o 'https://[^"]*linux_x64.tar.gz' | head -1)
+          curl -sSfL "$url" -o /tmp/gitleaks.tgz
+          tar -xzf /tmp/gitleaks.tgz -C /tmp gitleaks
+          sudo install /tmp/gitleaks /usr/local/bin/gitleaks
+          gitleaks version
+      - name: Scan working tree for secrets
+        run: gitleaks detect --no-git --source . --redact --verbose
+
+  dependencies:
+    name: Dependency & vuln scan (trivy)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Trivy filesystem scan
+        uses: aquasecurity/trivy-action@0.28.0
+        with:
+          scan-type: fs
+          scan-ref: .
+          scanners: vuln,secret,misconfig
+          severity: CRITICAL,HIGH
+          ignore-unfixed: true
+          exit-code: '0'
+          format: table
+
+  sast:
+    name: Static analysis (semgrep)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Run semgrep
+        run: |
+          pip install --quiet semgrep
+          semgrep scan --config auto --error=false --metrics=off || true
diff --git a/README.md b/README.md
index 9907f9f..f1f10fc 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 A production-grade, event-driven programmable agent runtime where **the runtime owns execution control, not the LLM**.
 
-Companion project to [nexus-agents](https://github.com/williamzujkowski/nexus-agents).
+Companion project to [nexus-agents](https://github.com/nexus-substrate/nexus-agents).
 
 ## Core Principles
 
@@ -22,7 +22,7 @@ Constraints → Interrupts → FSM/BT → Utility → Planner → LLM Advisory 
 
 ## Status
 
-**Phase: Scaffolding** — repository structure, docs, ADRs, and planning.
+**Working vertical slice** — Phases 1-3 complete with 60 passing tests covering the event bus, constraints, FSM, runtime loop, replay, and eval harness.
 
 ## Getting Started
 
@@ -57,7 +57,7 @@ console/       — CLI inspection and replay tooling
 
 ## Standards
 
-This project follows [nexus-agents CODING_STANDARDS.md](https://github.com/williamzujkowski/nexus-agents/blob/main/CODING_STANDARDS.md).
+This project follows [nexus-agents CODING_STANDARDS.md](https://github.com/nexus-substrate/nexus-agents/blob/main/CODING_STANDARDS.md).
 
 See [AGENTS.md](./AGENTS.md) for non-negotiable architectural rules.