Compass v0.5 — whole-codebase ultrareview (158 commits)

.env.example

@@ -0,0 +1,25 @@
+# 0G Network — Aristotle Mainnet
+ZEROG_RPC_URL=https://evmrpc.0g.ai
+ZEROG_CHAIN_ID=16661
+
+# 0G Network — Galileo Testnet
+ZEROG_TESTNET_RPC_URL=https://evmrpc-testnet.0g.ai
+ZEROG_TESTNET_CHAIN_ID=16602
+
+# Deployer wallet (NEVER COMMIT REAL VALUES)
+DEPLOYER_PRIVATE_KEY=0x_REPLACE_WITH_YOUR_KEY
+
+# 0G Compute / Sealed Inference
+ZG_BROKER_PROVIDER_ADDRESS=0x_PINNED_CANONICAL_PROVIDER_ADDRESS
+ZG_BROKER_LEDGER_DEPOSIT=0.1
+
+# Privy embedded wallet (Phase 7)
+NEXT_PUBLIC_PRIVY_APP_ID=
+
+# Mux Stream / Cloudflare Stream (Phase 7.5.2)
+NEXT_PUBLIC_MUX_VIDEO_ID=
+
+# Issuer signing keys (gitignored, fixture only — Phase 4a.1)
+HELP_ISSUER_KEY_PATH=enclave/keys/help-issuer.key.json
+BETHUNE_ISSUER_KEY_PATH=enclave/keys/bethune-issuer.key.json
+HOSPITAL_ISSUER_KEY_PATH=enclave/keys/hospital-issuer.key.json

.github/CODEOWNERS

@@ -0,0 +1,34 @@
+# CODEOWNERS — automatic review request routing for Compass.
+#
+# Solo build today (Stephen Sookra); this file pre-wires future co-maintainer
+# routing so adding a teammate is a one-line change rather than a repo-wide
+# refactor. Until that day, all paths route to @StephenSook by default.
+
+# Global fallback — every change pings the maintainer.
+*                                          @StephenSook
+
+# Smart contracts (Solidity + Hardhat + Slither) — highest security blast radius.
+/contracts/                                @StephenSook
+/contracts/contracts/                      @StephenSook
+/.github/workflows/ci.yml                  @StephenSook
+
+# TEE / enclave (dstack TDX, receipt-signer, verifier).
+/enclave/                                  @StephenSook
+
+# Frontend + API routes.
+/app/                                      @StephenSook
+/app/src/app/api/                          @StephenSook
+
+# Docs + audits + threat-model — public-facing accuracy matters.
+/docs/                                     @StephenSook
+/docs/audits/                              @StephenSook
+/docs/honest-limits.md                     @StephenSook
+
+# Skills (reusable ecosystem primitives).
+/skills/                                   @StephenSook
+
+# Repository-health metadata.
+/.github/                                  @StephenSook
+/README.md                                 @StephenSook
+/SECURITY.md                               @StephenSook
+/CHANGELOG.md                              @StephenSook

.github/FUNDING.yml

@@ -0,0 +1,5 @@
+# Compass is a solo hackathon build (0G APAC 2026 Track 5).
+# No GitHub Sponsors / Patreon / OpenCollective account yet.
+# Best contact for collaboration, NGO partnership, or follow-on work
+# is direct DM on Telegram — see SUPPORT.md.
+custom: ["https://t.me/stephensookra"]

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,93 @@
+name: Bug report
+description: Something is not working the way the docs / tests / live app say it should.
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Before filing, please check the [honest-limits doc](../../docs/honest-limits.md) — some surprises are documented as known limits rather than bugs.
+
+        🔒 **Security vulnerabilities — do not file here.** Use the private reporting channel in [`SECURITY.md`](../../SECURITY.md).
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: One or two sentences. What did you observe?
+      placeholder: When I clicked "Request Eligibility" on /onboard, the receipt minted but `attestationDigest` was zero.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      description: One sentence. What should have happened?
+      placeholder: The receipt's attestationDigest should equal sha256(canonicalize(receipt)).
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: |
+        Step-by-step. Include the exact commit SHA you tested against if local, or the live frontend URL + browser if you observed it in production. If a Hardhat / Playwright / vitest test reproduces it, include that command.
+      placeholder: |
+        1. Visit https://app-psi-pied.vercel.app/onboard
+        2. Sign in via Privy (Galileo testnet)
+        3. Click "Request Eligibility"
+        4. Observe ReceiptIssued event — attestationDigest field is 0x0…
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: commit-sha
+    attributes:
+      label: Compass commit SHA
+      description: "Run: `git rev-parse HEAD`"
+      placeholder: 6b099a8b
+    validations:
+      required: false
+
+  - type: dropdown
+    id: network
+    attributes:
+      label: Network
+      options:
+        - 0G Aristotle mainnet (chainId 16661)
+        - 0G Galileo testnet (chainId 16602)
+        - Local Hardhat (chainId 31337)
+        - N/A — frontend-only bug
+    validations:
+      required: true
+
+  - type: input
+    id: browser
+    attributes:
+      label: Browser (if frontend)
+      placeholder: "Chrome 142 / Firefox 134 / Safari 18 / iOS Safari …"
+    validations:
+      required: false
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: |
+        Screenshots, error console output, on-chain tx hashes that reverted, relevant `/api/tee-status` snapshot. **Trim secrets** before pasting.
+      placeholder: tx hash, console error, /api/tee-status JSON, …
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Confirmation
+      options:
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: This is not a security vulnerability (those go to `SECURITY.md` privately).
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🔒 Report a security vulnerability (private)
+    url: https://github.com/StephenSook/Compass-OG-/security/policy
+    about: Do NOT file security issues publicly. See SECURITY.md for the private disclosure channel.
+  - name: 📖 Read the whitepaper before filing
+    url: https://github.com/StephenSook/Compass-OG-/blob/main/docs/whitepaper.pdf
+    about: 3-page technical whitepaper covering threat model, architecture, protocol, honest limits, roadmap.
+  - name: 🌐 Verify a receipt in your browser
+    url: https://app-psi-pied.vercel.app/verify
+    about: "If you suspect a receipt is invalid, run it through /verify first — no install needed."
+  - name: 📋 Honest limits (what Compass does NOT protect against)
+    url: https://github.com/StephenSook/Compass-OG-/blob/main/docs/honest-limits.md
+    about: 25-section enumeration of known limits. Check here before filing a bug — it might already be documented.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,60 @@
+name: Feature request
+description: Suggest a new capability for Compass.
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing a feature. Compass keeps a narrow scope (private eligibility on 0G) — most proposals are better as a follow-on project. Use the **Compass scope check** at the bottom to decide.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem you are trying to solve
+      description: One paragraph. Who is affected? What do they do today, and where does that fall short?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: The change you are proposing
+      description: Concrete. What would land in the codebase if this issue were closed?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered
+      description: One or two sentences each. What other approaches did you weigh, and why is this proposal preferable?
+    validations:
+      required: false
+
+  - type: textarea
+    id: honest-limits
+    attributes:
+      label: Honest limits
+      description: |
+        What this proposal does *not* solve. Compass is explicit about its limits per [`docs/honest-limits.md`](../../docs/honest-limits.md); extend that posture here.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Compass scope check
+      description: Tick all that apply.
+      options:
+        - label: This change concerns one of the populations Compass is designed to serve (migrant workers, NGO clients, intake clinicians).
+        - label: This change has a clear cryptographic correctness story — I can describe how the threat model changes if it lands.
+        - label: This change does not regress the privacy properties enumerated in `docs/architecture.md` and `docs/threat-model.md`.
+        - label: If implemented, a Playwright / Hardhat / vitest test would cover the new behavior.
+    validations:
+      required: false
+
+  - type: markdown
+    attributes:
+      value: |
+        If none of the boxes apply, this may be out of scope — please open a Discussion instead.

.github/dependabot.yml

@@ -0,0 +1,87 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /app
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: "Asia/Hong_Kong"
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - security
+    commit-message:
+      prefix: "deps(app)"
+
+  - package-ecosystem: npm
+    directory: /enclave
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: "Asia/Hong_Kong"
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - security
+      - enclave
+    commit-message:
+      prefix: "deps(enclave)"
+
+  - package-ecosystem: npm
+    directory: /contracts
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: "Asia/Hong_Kong"
+    open-pull-requests-limit: 3
+    labels:
+      - dependencies
+      - security
+      - contracts
+    commit-message:
+      prefix: "deps(contracts)"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    labels:
+      - dependencies
+      - ci
+    commit-message:
+      prefix: "ci(deps)"
+
+  - package-ecosystem: docker
+    directory: /enclave
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: "Asia/Hong_Kong"
+    labels:
+      - dependencies
+      - security
+      - enclave
+      - docker
+    commit-message:
+      prefix: "deps(enclave-image)"
+
+  - package-ecosystem: docker
+    directory: /enclave/phala
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: "Asia/Hong_Kong"
+    labels:
+      - dependencies
+      - security
+      - enclave
+      - docker
+      - phala
+    commit-message:
+      prefix: "deps(phala-image)"

.github/pull_request_template.md

@@ -0,0 +1,38 @@
+# Pull request
+
+## What this PR does
+
+(One or two sentences. Why is this change needed? What problem does it
+solve?)
+
+## Why this approach over the alternatives
+
+(One paragraph. What other paths did you consider? Why does this one
+win?)
+
+## Honest limits
+
+(What this PR does *not* solve. If you remove or weaken any guarantee
+documented in `docs/honest-limits.md`, call that out here.)
+
+## Verification
+
+- [ ] `cd contracts && npx hardhat test` — passing
+- [ ] `cd contracts && slither . --filter-paths "node_modules"` — 0 sec
+- [ ] `cd app && npm run build` — passing
+- [ ] `cd enclave && npm test` — passing
+- [ ] Playwright suite — passing or N/A (e.g. for contracts-only PRs)
+- [ ] If this PR changes a documented row in the `/about` reality
+  table, the row state and note are updated to match.
+- [ ] If this PR changes a privacy property, `docs/threat-model.md`
+  and / or `docs/honest-limits.md` are updated.
+
+## Linked issues / context
+
+Closes #
+Related: docs/architecture.md, docs/threat-model.md
+
+---
+
+For security-sensitive changes, also coordinate via the channels in
+[`SECURITY.md`](../SECURITY.md) before opening the PR.