From 9be7d04f39d0df57e7717caf619dd2f7a2256857 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 18:56:34 +0000 Subject: [PATCH 01/24] chore(build): standardize package manager and verification commands --- package.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 63916664..b17680b1 100644 --- a/package.json +++ b/package.json @@ -2,14 +2,17 @@ "name": "gem-enterprise", "private": true, "version": "1.0.0", + "packageManager": "pnpm@10.28.0", "scripts": { "dev": "next dev", "build": "node scripts/vercel-build.mjs", "start": "next start", "lint": "eslint src --ext .ts,.tsx --max-warnings=0", + "typecheck": "tsc --noEmit", "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage", + "verify": "pnpm run db:generate && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build", "db:generate": "prisma generate", "db:push": "prisma db push", "db:migrate": "prisma migrate dev", @@ -117,4 +120,4 @@ "typescript": "^5.8.3", "vitest": "^4.1.0" } -} \ No newline at end of file +} From d627396b792eb82c5601b659a2fb7468415081cb Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 18:56:44 +0000 Subject: [PATCH 02/24] ci: add one deterministic verification gate for agents and humans --- .github/workflows/ci.yml | 94 +++++++++++++++------------------------- 1 file changed, 36 insertions(+), 58 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f2e3867f..0f338dc0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,50 +1,39 @@ -name: CI (Tests & Validation Only - Vercel Handles Deployment) +name: Build Verification on: pull_request: branches: [main] + push: + branches: [main] + workflow_dispatch: -jobs: - test: - name: Unit Tests - runs-on: ubuntu-22.04 - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Install pnpm - uses: pnpm/action-setup@v4 - with: - version: 9 - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: 20 - cache: pnpm - - - name: Install dependencies - run: pnpm install --frozen-lockfile - - - name: Generate Prisma client - run: pnpm run db:generate - env: - POSTGRES_PRISMA_URL: postgresql://ci:ci@localhost:5432/gem_ci - POSTGRES_URL_NON_POOLING: postgresql://ci:ci@localhost:5432/gem_ci +permissions: + contents: read - - name: Run unit tests - run: pnpm test - env: - NODE_ENV: test - JWT_SECRET: ci-test-secret-min-32-characters-long-placeholder - POSTGRES_PRISMA_URL: postgresql://ci:ci@localhost:5432/gem_ci - POSTGRES_URL_NON_POOLING: postgresql://ci:ci@localhost:5432/gem_ci +concurrency: + group: build-verification-${{ github.ref }} + cancel-in-progress: true - lint-and-build: - name: Lint & Build +jobs: + verify: + name: Lint, Typecheck, Test, Build runs-on: ubuntu-22.04 - needs: test + timeout-minutes: 30 + + env: + NODE_ENV: test + JWT_SECRET: ci-test-secret-min-32-characters-long-placeholder + POSTGRES_PRISMA_URL: postgresql://ci:ci@localhost:5432/gem_ci + POSTGRES_URL_NON_POOLING: postgresql://ci:ci@localhost:5432/gem_ci + NEXT_PUBLIC_APP_URL: https://www.gemcybersecurityassist.com + NEXT_PUBLIC_APP_NAME: GEM Enterprise + NEXT_PUBLIC_AI_DISCLOSURE_TEXT: GEM Concierge is an AI assistant. Responses are informational and require human review for sensitive decisions. + AUDIT_ENABLED: "true" + SMTP_HOST: "" + SMTP_PORT: "587" + SMTP_USER: "" + SMTP_PASS: "" + CRON_SECRET: ci-cron-secret steps: - name: Checkout @@ -53,7 +42,7 @@ jobs: - name: Install pnpm uses: pnpm/action-setup@v4 with: - version: 9 + version: 10.28.0 - name: Setup Node.js uses: actions/setup-node@v4 @@ -66,26 +55,15 @@ jobs: - name: Generate Prisma client run: pnpm run db:generate - env: - POSTGRES_PRISMA_URL: postgresql://ci:ci@localhost:5432/gem_ci - POSTGRES_URL_NON_POOLING: postgresql://ci:ci@localhost:5432/gem_ci - name: Lint run: pnpm run lint - - name: Build + - name: Typecheck + run: pnpm run typecheck + + - name: Unit tests + run: pnpm run test + + - name: Production build run: pnpm run build - env: - POSTGRES_PRISMA_URL: postgresql://ci:ci@localhost:5432/gem_ci - POSTGRES_URL_NON_POOLING: postgresql://ci:ci@localhost:5432/gem_ci - JWT_SECRET: ${{ secrets.JWT_SECRET || 'ci-build-secret-min-32-characters-long' }} - NEXT_PUBLIC_APP_URL: https://gem-enterprise.vercel.app - NEXT_PUBLIC_APP_NAME: GEM Enterprise - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - NEXT_PUBLIC_AI_DISCLOSURE_TEXT: ${{ secrets.NEXT_PUBLIC_AI_DISCLOSURE_TEXT || 'GEM Concierge is an AI assistant. Responses are for informational purposes only.' }} - AUDIT_ENABLED: 'true' - SMTP_HOST: '' - SMTP_PORT: '587' - SMTP_USER: '' - SMTP_PASS: '' - CRON_SECRET: ci-cron-secret From df5c518e9fcb7f2612978d9d5cda7d7f2208f3ba Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 18:56:52 +0000 Subject: [PATCH 03/24] ci: remove duplicate Vercel production deployment workflow --- .github/workflows/main.yml | 42 -------------------------------------- 1 file changed, 42 deletions(-) delete mode 100644 .github/workflows/main.yml diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml deleted file mode 100644 index 22264994..00000000 --- a/.github/workflows/main.yml +++ /dev/null @@ -1,42 +0,0 @@ -name: Deploy to Vercel Production - -on: - push: - branches: - - main - workflow_dispatch: - -permissions: - contents: read - -jobs: - deploy: - name: Deploy to Vercel - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - uses: pnpm/action-setup@v4 - with: - version: 9 - - - uses: actions/setup-node@v4 - with: - node-version: '20' - cache: pnpm - - - name: Install dependencies - run: pnpm install --frozen-lockfile - - - name: Generate Prisma client - run: pnpm run db:generate - env: - POSTGRES_PRISMA_URL: postgresql://ci:ci@localhost/gem - POSTGRES_URL_NON_POOLING: postgresql://ci:ci@localhost/gem - - - name: Deploy to Vercel Production - run: npx vercel --prod --token $VERCEL_TOKEN --yes - env: - VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }} - VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} - VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} From f378e0e87830aa65cc2a18849c300b9b04fcca5f Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 18:57:21 +0000 Subject: [PATCH 04/24] docs(agent): define controlled agent-first delivery rules --- AGENTS.md | 199 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 125 insertions(+), 74 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b13ac679..0139b0a6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,83 +1,134 @@ # GEM Enterprise — Agent Instructions ## Project Overview -GEM Enterprise is a cybersecurity, financial security, asset recovery, and real estate protection platform. -- **Domain**: gemcybersecurityassist.com -- **Repository**: github.com/support371/gem-enterprise -- **Branch**: fix/stabilize-and-finalize-330047221298805619 -- **Deployed on**: Vercel + +GEM Enterprise is a controlled-access platform for cybersecurity, compliance, financial-security coordination, product and service enquiries, and property-risk support. + +- **Production domain:** `https://www.gemcybersecurityassist.com` +- **Repository:** `support371/gem-enterprise` +- **Default branch:** `main` +- **Canonical host:** Vercel project `support371-gem-enterprise` +- **Deployment method:** Vercel Git integration deploys `main`; agents must not run a second `vercel --prod` deployment from CI. +- **Current operating mode:** controlled production launch. Sensitive or provider-dependent features fail closed until verified. ## Tech Stack -- **Framework**: Next.js 16 (App Router) -- **Language**: TypeScript (strict mode should be enabled) -- **Database**: PostgreSQL via Prisma 5 ORM -- **Auth**: Custom JWT using `jose` library + `bcryptjs` for password hashing -- **Session**: Cookie-based (`gem_session`), httpOnly, 7-day expiry -- **UI**: Tailwind CSS + shadcn/ui components -- **Charts**: Recharts -- **AI**: Anthropic Claude API via direct integration (NOT Vercel AI SDK) -- **Email**: Resend (when configured) -- **Payments**: Stripe (when configured) -- **Package Manager**: pnpm (NEVER use npm or yarn) -- **Testing**: Vitest (unit) + Playwright (E2E) - -## Architecture Rules — DO NOT VIOLATE -1. **Auth system**: The auth implementation is in `src/lib/auth.ts`. Do NOT replace it with NextAuth, Supabase Auth, Clerk, or any other auth library. Extend the existing JWT implementation. -2. **Database**: All models go in `prisma/schema.prisma`. Use `db` import from `src/lib/db.ts` for all database access. Never use raw SQL. -3. **Package manager**: Use `pnpm` for all commands. Never reference npm or yarn. -4. **API validation**: All API route inputs must be validated with Zod schemas. Never trust raw `req.json()`. -5. **Audit logging**: All admin and sensitive actions must call `emitAuditLog()` from `src/lib/audit.ts`. -6. **Evidence retention**: Compliance-sensitive data follows 7-year retention per `src/lib/evidence.ts`. -7. **Roles**: The system has 5 roles: client, analyst, admin, super_admin, internal. Never allow role escalation to super_admin or internal via API. -8. **AI consent**: All AI interactions require user consent via `ConsentRecord` model before proceeding. -9. **File organization**: Pages go in `src/app/`, API routes in `src/app/api/`, shared libraries in `src/lib/`, React components in `src/components/`, hooks in `src/hooks/`. -10. **Styling**: Match the existing dark theme. Use Tailwind utility classes. Do not add custom CSS files. - -## Key Files Reference -- `src/lib/auth.ts` — JWT sign/verify, session management, KYC-gated routing -- `src/lib/db.ts` — Prisma client singleton -- `src/lib/audit.ts` — Audit logging with `emitAuditLog()` -- `src/lib/evidence.ts` — 7-year evidence retention -- `src/lib/orchestration/orchestrate-support-reply.ts` — AI chat orchestration -- `src/lib/policy/evaluate-policy.ts` — AI policy evaluation engine -- `prisma/schema.prisma` — Database schema (22 models, 9 enums) -- `next.config.js` — Security headers, redirects, image optimization -- `vercel.json` — Vercel deployment configuration - -## Environment Variables -Required env vars are documented in `.env.example`. For development/testing, use these defaults: -- DATABASE_URL=postgresql://test:test@localhost:5432/gem_test -- JWT_SECRET=test-secret-that-is-at-least-32-characters-long-for-dev -- NEXT_PUBLIC_APP_URL=http://localhost:3000 -- NEXT_PUBLIC_APP_NAME=GEM Enterprise -- AUDIT_ENABLED=true - -## Verification Commands — RUN AFTER EVERY CHANGE + +- **Framework:** Next.js 16 App Router +- **Language:** TypeScript +- **Database:** PostgreSQL through Prisma 5 +- **Authentication:** existing JWT/session implementation using `jose` and `bcryptjs` +- **Session:** HTTP-only cookie named `gem_session` +- **UI:** Tailwind CSS and existing shared components +- **Email:** Nodemailer SMTP when production credentials are configured +- **Commerce:** request-only catalogue until payments, fulfilment, refunds, taxes, licensing, and inventory are verified +- **Testing:** Vitest; Playwright is available for end-to-end tests +- **Package manager:** pnpm 10.28.0 only + +## Non-Negotiable Safety and Trust Rules + +1. **Fail closed.** Do not enable KYC uploads, biometrics, automatic approvals, automatic payments, live intelligence, or marketplace transactions without the complete supporting infrastructure and explicit owner approval. +2. **No false operational claims.** Do not describe static, sample, mock, planned, or manually reviewed data as live, continuous, verified, encrypted, certified, guaranteed, monitored, or available 24/7. +3. **No secrets in code, prompts, commits, logs, issues, screenshots, or pull requests.** Use environment-variable names and secret managers only. +4. **No paid service activation.** An agent may build an adapter or sandbox integration, but may not accept pricing, enable billing, purchase a plan, or create financial obligations. +5. **No direct production database mutation from CI.** Schema changes require a migration, compatibility assessment, rollback plan, and owner-approved production execution. +6. **No direct commits to `main`.** Use a focused branch and pull request except for an explicitly documented emergency process. +7. **One canonical deployment.** Vercel Git integration owns production deployment. Do not create duplicate production deploy workflows or attach the domain to another project without a migration plan. +8. **Human review for high-impact decisions.** Identity, eligibility, legal, financial, security-incident, and access decisions must remain reviewable and auditable. + +## Architecture Rules + +1. Extend the authentication implementation in `src/lib/auth.ts`; do not replace it with another auth platform without an approved migration plan. +2. Put Prisma models in `prisma/schema.prisma` and access the database using `db` from `src/lib/db.ts`. +3. Validate API inputs with Zod. +4. Call `emitAuditLog()` from `src/lib/audit.ts` for administrator, reviewer, authorization, verification, and sensitive state changes. +5. Do not trust client-supplied roles, storage paths, scan results, payment states, provider decisions, or redirect URLs. +6. Pages belong in `src/app/`, API routes in `src/app/api/`, shared logic in `src/lib/`, and reusable UI in `src/components/`. +7. Match the existing design system and avoid introducing another styling framework. +8. External providers must be accessed through small adapter interfaces so they can be disabled or replaced. +9. Sensitive files must never be stored in public paths or accepted before private storage, validation, scanning, access control, audit logging, retention, and deletion are working. +10. APIs handling credentials, identity, contact, payments, administration, or recovery must use `no-store` responses and production-appropriate abuse controls. + +## Agent Delivery Flow + +Every implementation task follows this sequence: + +1. **Create or reference one GitHub issue** containing the objective, acceptance criteria, exclusions, risks, and manual dependencies. +2. **Create a focused branch** using `feat/`, `fix/`, `chore/`, `docs/`, `security/`, or `test/`. +3. **Inspect before editing.** Read the affected routes, schema, tests, configuration, and recent related pull requests. +4. **Write a brief implementation plan** in the issue or pull request before broad changes. +5. **Implement the smallest complete vertical slice.** Avoid unrelated refactors. +6. **Add or update tests** for success, authorization failure, validation failure, provider failure, and fail-closed behavior. +7. **Run the repository gate:** + ```bash +corepack enable pnpm install --frozen-lockfile -pnpm run db:generate -pnpm build -pnpm test +pnpm run verify ``` -If any of these fail, fix the errors before committing. - -## Commit Convention -- Use conventional commits: feat:, fix:, chore:, test:, docs: -- Include the prompt number in commits: `feat(prompt-7): wire community hub to database` -- One logical change per commit when possible - -## Testing Standards -- Unit tests go in `src/__tests__/` -- E2E tests go in `e2e/` -- Test files follow pattern: `*.test.ts` or `*.spec.ts` -- Mock external services (Anthropic, Resend, Stripe) — never call real APIs in tests -- Target 70%+ statement coverage - -## PR Description Format -When creating a pull request, include: -1. **Prompt Reference**: Which prompt number this addresses -2. **Changes Summary**: What was added/modified/deleted -3. **Files Changed**: List of key files -4. **Testing**: What tests were added or updated -5. **Verification**: Confirm `pnpm build` and `pnpm test` pass +8. **Open a pull request** with risks, manual dependencies, test evidence, and rollback notes. +9. **Verify the Vercel preview** for affected public routes and inspect runtime/build logs. +10. **Merge only after required checks pass.** Vercel Git integration deploys `main` to production. +11. **Run production smoke checks** without submitting sensitive data or causing billable external actions. + +## Build Gate + +`pnpm run verify` must complete successfully. It runs: + +- Prisma client generation +- ESLint +- TypeScript checking +- Unit tests +- Next.js production build + +If the full command cannot run because a required external dependency is unavailable, the agent must document the exact blocker and must not claim the feature is complete. + +## Free-Tier Development Policy + +Development should preserve useful free operation: + +- Prefer existing infrastructure and open-source libraries. +- Do not add a paid provider merely to complete a demo. +- Build provider-independent interfaces and use local fakes in tests. +- Keep optional integrations disabled by default. +- Add usage limits, queue boundaries, retention limits, and clear error states before enabling a metered service. +- Treat billing approval, identity-provider contracts, production email credentials, regulated data sources, and external seller verification as owner-only actions. + +## Current Sensitive Feature Gates + +These remain disabled or request-only until their activation requirements pass: + +- Identity and financial document upload +- Biometric and liveness verification +- Automatic KYC/KYB approval +- Automatic payments and subscriptions +- Live threat-intelligence assertions +- Marketplace transactions and verified-member claims +- Guaranteed response times and continuous monitoring + +## Key Files + +- `src/lib/auth.ts` — authentication and session management +- `src/lib/db.ts` — Prisma client +- `src/lib/audit.ts` — audit events +- `src/app/api/contact/route.ts` — durable public enquiry intake +- `src/app/api/kyc/documents/route.ts` — intentionally fail-closed document endpoint +- `src/lib/storefrontPresentation.ts` — truthful request-only commerce presentation +- `prisma/schema.prisma` — database schema +- `next.config.js` — browser security headers and routing +- `.github/workflows/ci.yml` — canonical build verification gate +- `docs/AGENT_BUILD_FLOW.md` — task and release operating procedure + +## Commit and Pull Request Standards + +Use conventional commits such as `feat:`, `fix:`, `security:`, `test:`, `docs:`, and `chore:`. A pull request must include: + +1. Objective and linked issue +2. User-visible and architectural changes +3. Files and data models affected +4. Security, privacy, billing, and operational risks +5. Tests and verification performed +6. Manual actions that remain +7. Rollback method + +An AI agent is an executor, not the approval authority for billing, legal representations, identity decisions, production secrets, or regulated-service activation. From 7e546ce77d1aa51e955b792aa3e450418441e84c Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 18:57:49 +0000 Subject: [PATCH 05/24] docs(build): add agent-first free-tier delivery flow --- docs/AGENT_BUILD_FLOW.md | 267 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 docs/AGENT_BUILD_FLOW.md diff --git a/docs/AGENT_BUILD_FLOW.md b/docs/AGENT_BUILD_FLOW.md new file mode 100644 index 00000000..cd3b8f01 --- /dev/null +++ b/docs/AGENT_BUILD_FLOW.md @@ -0,0 +1,267 @@ +# GEM Enterprise Agent-First Build Flow + +## Purpose + +This flow allows GEM Enterprise to keep building with limited personnel time and minimal billing exposure while preserving a trustworthy production system. + +The operating principle is: + +> Humans define intent and approve high-impact decisions. Agents implement, test, document, and prepare pull requests. Automated gates verify the work. Production-sensitive capabilities remain disabled until their infrastructure and owner approvals exist. + +## Roles + +### Business owner + +Responsible for: + +- Business priorities and public claims +- Billing, contracts, and paid plans +- Legal entity and policy approval +- Provider accounts and production credentials +- Final approval for identity, payment, storage, monitoring, and regulated-service activation + +### Lead development agent + +Responsible for: + +- Repository inspection and task planning +- Focused implementation +- Tests and documentation +- Pull-request creation +- Build and preview verification +- Reporting exact blockers and manual actions + +### Review agent + +Responsible for an independent pass over: + +- Security and authorization boundaries +- Privacy and sensitive-data handling +- False or unsupported public claims +- Database and migration safety +- Test coverage and rollback readiness + +The lead agent and review agent may use different products, but every change still passes the same repository gate. + +## Canonical workflow + +```text +Owner objective + ↓ +GitHub issue with acceptance criteria + ↓ +Agent branch + ↓ +Inspect current code and related PRs + ↓ +Small vertical implementation + ↓ +Unit/security/fail-closed tests + ↓ +pnpm run verify + ↓ +Pull request + ↓ +Independent review + CodeQL + Vercel preview + ↓ +Owner-only approval when billing/legal/provider action exists + ↓ +Merge to main + ↓ +Vercel Git production deployment + ↓ +Production smoke check and rollback watch +``` + +## Work queue + +Use four priority lanes. + +### P0 — Production safety + +Examples: + +- Authentication bypass +- Data exposure +- Contact submissions being lost +- Broken production deployment +- Unsupported claims that can materially mislead users + +Rules: + +- Stop unrelated feature work. +- Fix in the smallest possible branch. +- Require tests and production verification. + +### P1 — Revenue and customer flow + +Examples: + +- Enquiry intake +- Application status +- Service-request workflow +- Email delivery +- Reviewer queue + +Rules: + +- Build request-and-review flows before automated or paid flows. +- Persist data before showing success. + +### P2 — Trust infrastructure + +Examples: + +- Audit records +- Access controls +- Backups and restore testing +- Rate limiting +- Monitoring +- Privacy and retention controls + +### P3 — Optional expansion + +Examples: + +- Provider adapters +- Live feeds +- Automated payments +- Biometrics +- Marketplace transactions + +Rules: + +- Keep disabled until P0–P2 requirements and owner approvals are complete. + +## Definition of ready + +An issue is ready for an agent only when it contains: + +- User or business outcome +- In-scope routes and roles +- Acceptance criteria +- Explicit exclusions +- Sensitive-data classification +- Billing impact +- Manual/provider dependencies +- Rollback expectation + +## Definition of done + +A task is complete only when: + +- The implementation matches the issue scope. +- Validation and authorization failures are tested. +- Provider failure or missing configuration fails closed. +- `pnpm run verify` passes. +- Vercel preview routes work. +- No secret or real sensitive document was used in testing. +- The PR states what remains manual. +- Production smoke checks pass after merge. + +## Standard agent prompt + +Use this prompt when delegating a repository task: + +```text +Repository: support371/gem-enterprise + +Read AGENTS.md and docs/AGENT_BUILD_FLOW.md before making changes. + +Objective: + + +Acceptance criteria: +- +- +- + +Explicit exclusions: +- No paid service activation +- No production secrets +- No direct commit to main +- No enabling sensitive uploads or payments unless this issue explicitly includes every required control and owner approval + +Required process: +1. Inspect affected code, schema, tests, and recent related PRs. +2. Post a short plan. +3. Implement the smallest complete vertical slice. +4. Add tests for success, validation failure, authorization failure, and fail-closed behavior. +5. Run pnpm run verify. +6. Open a PR with risks, manual dependencies, and rollback steps. +7. Do not claim completion if any gate fails. +``` + +## Recommended agent allocation + +### Primary implementation agent: OpenAI Codex + +Use for: + +- Multi-file repository tasks +- Bug diagnosis +- Refactors and migrations +- Test creation +- Pull-request preparation +- Parallel tasks that can be isolated by branch + +Codex should follow `AGENTS.md`, use one issue per task, and operate only through pull requests. + +### Independent review: GitHub Copilot coding agent or a second Codex task + +Use for: + +- Reviewing the PR without sharing the implementation conversation +- Looking for authorization, data-handling, and regression issues +- Suggesting missing tests + +### Replit Agent + +Use when a visual prototype or isolated experimental application is needed. Do not make it the canonical production repository or deployment path for GEM Enterprise. + +### Devin + +Use only for a clearly bounded backlog with sufficient paid capacity. It is not required for the current free-first flow. + +## First implementation program: GEM Verify Core + +Build in this order: + +1. Verification application and consent records +2. Manual case-status workflow +3. Reviewer queue and role checks +4. Information-request, approval, rejection, and escalation actions +5. Audit events and immutable decision history +6. Storage-provider interface with a fake test implementation +7. Retention and deletion scheduling model +8. Private upload adapter only after owner-selected storage and scanning are available +9. Optional Veriff or other provider adapter after sandbox approval + +Until step 8 is verified, `/api/kyc/documents` must remain fail closed. + +## Free-tier safeguards + +- Cancel superseded CI runs. +- Use one canonical verification job. +- Let Vercel Git integration perform the only production deployment. +- Use local fakes for external providers in tests. +- Do not run scheduled jobs more frequently than the business requires. +- Keep optional integrations disabled by default. +- Record usage and define a hard stop before enabling metered services. +- Never rely on a free plan whose terms prohibit the intended business use. + +## Manual gates + +The agent must stop and request owner action for: + +- Accepting pricing or terms +- Enabling billing +- Creating regulated-data provider accounts +- Entering production secrets +- Selecting retention periods +- Approving public certifications or SLAs +- Naming authorized identity reviewers +- Activating payment collection +- Moving the production domain or database + +These gates are not development failures. They are separation-of-duty controls. From 98969fb4882d7964b07f054e00f034407548366d Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 18:58:04 +0000 Subject: [PATCH 06/24] docs(github): add structured agent task template --- .github/ISSUE_TEMPLATE/agent-task.yml | 117 ++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/agent-task.yml diff --git a/.github/ISSUE_TEMPLATE/agent-task.yml b/.github/ISSUE_TEMPLATE/agent-task.yml new file mode 100644 index 00000000..59004201 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/agent-task.yml @@ -0,0 +1,117 @@ +name: Agent implementation task +description: Define a bounded development task for an AI coding agent +title: "[Agent Task]: " +labels: [] +body: + - type: markdown + attributes: + value: | + Read `AGENTS.md` and `docs/AGENT_BUILD_FLOW.md` before implementation. Do not include secrets or real identity documents. + + - type: textarea + id: objective + attributes: + label: Objective + description: State one measurable user or business outcome. + placeholder: A public contact enquiry is stored before the visitor sees a success message. + validations: + required: true + + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: List observable conditions that prove the task is complete. + placeholder: | + - Valid submissions are persisted. + - Invalid input returns 400. + - Storage failure returns 503. + - Tests cover success and failure paths. + validations: + required: true + + - type: textarea + id: scope + attributes: + label: In-scope routes, roles, and files + description: Identify affected user roles, routes, models, or integrations. + validations: + required: true + + - type: textarea + id: exclusions + attributes: + label: Explicit exclusions + description: State what the agent must not change or activate. + placeholder: | + - No paid service activation. + - No production credentials. + - No direct commits to main. + - No sensitive document upload. + validations: + required: true + + - type: dropdown + id: data + attributes: + label: Sensitive-data level + options: + - None or public content + - Account or contact information + - Authentication or authorization + - Identity, financial, legal, or regulated information + validations: + required: true + + - type: dropdown + id: billing + attributes: + label: Billing impact + options: + - None + - Uses an existing free or already-approved service + - May create metered usage + - Requires owner approval before implementation can finish + validations: + required: true + + - type: textarea + id: dependencies + attributes: + label: Manual and provider dependencies + description: List accounts, approvals, provider decisions, or credentials the owner must supply. + placeholder: None, or describe the exact owner-only action. + validations: + required: true + + - type: textarea + id: tests + attributes: + label: Required verification + description: Include unit, authorization, fail-closed, preview, and production checks as applicable. + placeholder: | + - pnpm run verify + - Vercel preview route check + - No external billable calls in tests + validations: + required: true + + - type: textarea + id: rollback + attributes: + label: Rollback expectation + description: Explain how the change can be disabled or reverted safely. + validations: + required: true + + - type: checkboxes + id: guardrails + attributes: + label: Guardrails + options: + - label: I have not placed secrets, passwords, API keys, or real sensitive documents in this issue. + required: true + - label: The task does not authorize billing, legal claims, certifications, or regulated-service activation. + required: true + - label: The agent must use a branch and pull request. + required: true From 56d81c78b06c01ca75b967a38f8078a2b26abb98 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 18:58:13 +0000 Subject: [PATCH 07/24] docs(github): add agent-ready pull request template --- .github/pull_request_template.md | 50 ++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..5237f411 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,50 @@ +## Objective + +Closes # + +Describe the single measurable outcome delivered by this pull request. + +## Changes + +- + +## Files and data models affected + +- + +## Trust, security, privacy, and billing review + +- [ ] No secrets or real sensitive documents are included. +- [ ] Public wording does not overstate live, verified, encrypted, certified, guaranteed, or continuous capability. +- [ ] Authorization and validation boundaries were reviewed. +- [ ] Missing provider configuration fails closed. +- [ ] No paid plan, billing, or metered feature was activated. +- [ ] Database changes include compatibility and rollback notes, or no schema change was made. + +## Verification + +- [ ] `pnpm run verify` +- [ ] Relevant authorization and validation failures tested +- [ ] Vercel preview checked +- [ ] Build/runtime logs checked +- [ ] No billable external calls made during testing + +Evidence: + +```text +Paste concise command results or route/status checks here. +``` + +## Manual actions remaining + +State exactly what requires the business owner, provider account, legal approval, or production credential. Write `None` when no manual action remains. + +## Rollback + +Describe how to revert, disable, or fail closed safely. + +## Agent declaration + +- [ ] I read `AGENTS.md` and `docs/AGENT_BUILD_FLOW.md`. +- [ ] This pull request stays within the linked issue scope. +- [ ] I am not claiming completion while a required gate is failing. From 3990df491cace634febafaa9715435de8d57e5d6 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:01:17 +0000 Subject: [PATCH 08/24] ci: use current Node-compatible GitHub Actions --- .github/workflows/ci.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0f338dc0..867248ab 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,15 +37,13 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Install pnpm - uses: pnpm/action-setup@v4 - with: - version: 10.28.0 + uses: pnpm/action-setup@v6 - name: Setup Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: 20 cache: pnpm From 31573c86ebaaba4d7da5d8fa25b391df3d73de05 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:01:27 +0000 Subject: [PATCH 09/24] ci(security): update CodeQL workflow action runtimes --- .github/workflows/codeql.yml | 109 +++++++++++------------------------ 1 file changed, 34 insertions(+), 75 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index d6cf71be..5f339aaf 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,89 +1,48 @@ -# CodeQL Analysis - Runs only on pull requests to avoid deployment interference -name: "CodeQL Advanced" +name: CodeQL Advanced on: pull_request: - branches: [ "main" ] + branches: [main] schedule: - - cron: '15 6 * * 4' + - cron: "15 6 * * 4" + workflow_dispatch: + +permissions: + contents: read + actions: read + packages: read + security-events: write + +concurrency: + group: codeql-${{ github.ref }} + cancel-in-progress: true jobs: analyze: name: Analyze (${{ matrix.language }}) - # Runner size impacts CodeQL analysis time. To learn more, please see: - # - https://gh.io/recommended-hardware-resources-for-running-codeql - # - https://gh.io/supported-runners-and-hardware-resources - # - https://gh.io/using-larger-runners (GitHub.com only) - # Consider using larger runners or machines with greater resources for possible analysis time improvements. - runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} - permissions: - # required for all workflows - security-events: write - - # required to fetch internal or private CodeQL packs - packages: read - - # only required for workflows in private repositories - actions: read - contents: read + runs-on: ubuntu-latest + timeout-minutes: 30 strategy: fail-fast: false matrix: include: - - language: actions - build-mode: none - - language: javascript-typescript - build-mode: none - # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift' - # Use `c-cpp` to analyze code written in C, C++ or both - # Use 'java-kotlin' to analyze code written in Java, Kotlin or both - # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both - # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis, - # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning. - # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how - # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages - steps: - - name: Checkout repository - uses: actions/checkout@v4 + - language: actions + build-mode: none + - language: javascript-typescript + build-mode: none - # Add any setup steps before running the `github/codeql-action/init` action. - # This includes steps like installing compilers or runtimes (`actions/setup-node` - # or others). This is typically only required for manual builds. - # - name: Setup runtime (example) - # uses: actions/setup-example@v1 - - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: github/codeql-action/init@v4 - with: - languages: ${{ matrix.language }} - build-mode: ${{ matrix.build-mode }} - # If you wish to specify custom queries, you can do so here or in a config file. - # By default, queries listed here will override any specified in a config file. - # Prefix the list here with "+" to use these queries and those in the config file. - - # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs - # queries: security-extended,security-and-quality - - # If the analyze step fails for one of the languages you are analyzing with - # "We were unable to automatically build your code", modify the matrix above - # to set the build mode to "manual" for that language. Then modify this step - # to build your code. - # ℹ️ Command-line programs to run using the OS shell. - # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun - - name: Run manual build steps - if: matrix.build-mode == 'manual' - shell: bash - run: | - echo 'If you are using a "manual" build mode for one or more of the' \ - 'languages you are analyzing, replace this with the commands to build' \ - 'your code, for example:' - echo ' make bootstrap' - echo ' make release' - exit 1 - - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4 - with: - category: "/language:${{matrix.language}}" + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + + - name: Perform CodeQL analysis + uses: github/codeql-action/analyze@v4 + with: + category: /language:${{ matrix.language }} From df31627ea72dcedf3b6b2ec5bcfa90a8c191c0d2 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:02:46 +0000 Subject: [PATCH 10/24] chore(build): add preview verification command --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index b17680b1..a3fc9a08 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,8 @@ "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage", - "verify": "pnpm run db:generate && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build", + "verify:preview": "pnpm run lint && pnpm run typecheck && pnpm run test", + "verify": "pnpm run db:generate && pnpm run verify:preview && pnpm run build", "db:generate": "prisma generate", "db:push": "prisma db push", "db:migrate": "prisma migrate dev", From 42735bef17aaf5c4240d6070bb64f8d654416793 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:02:59 +0000 Subject: [PATCH 11/24] ci: make Vercel previews the automatic verification gate --- scripts/vercel-build.mjs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/scripts/vercel-build.mjs b/scripts/vercel-build.mjs index 21e6d07d..67ba5619 100644 --- a/scripts/vercel-build.mjs +++ b/scripts/vercel-build.mjs @@ -39,6 +39,27 @@ if (directUrl) env.POSTGRES_URL_NON_POOLING = directUrl; console.log("Generating Prisma client..."); run("pnpm", ["exec", "prisma", "generate"], env); +const shouldVerifyPreview = + env.VERCEL_ENV === "preview" || env.RUN_PREVIEW_VERIFICATION === "true"; + +if (shouldVerifyPreview) { + console.log("Running preview verification: lint, typecheck, and unit tests..."); + const verificationEnv = { + ...env, + NODE_ENV: "test", + JWT_SECRET: "preview-verification-secret-min-32-characters", + POSTGRES_PRISMA_URL: "postgresql://ci:ci@localhost:5432/gem_ci", + POSTGRES_URL_NON_POOLING: "postgresql://ci:ci@localhost:5432/gem_ci", + SMTP_HOST: "", + SMTP_PORT: "587", + SMTP_USER: "", + SMTP_PASS: "", + CRON_SECRET: "preview-verification-cron-secret", + AUDIT_ENABLED: "true", + }; + run("pnpm", ["run", "verify:preview"], verificationEnv); +} + if (env.AUTO_DB_PUSH === "true") { if (!pooledUrl) { throw new Error( From 6604bd930fafb7cd77786b6092cc44f5431f0cb8 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:03:09 +0000 Subject: [PATCH 12/24] ci: keep GitHub verification available without blocking free-tier PRs --- .github/workflows/ci.yml | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 867248ab..1bde4dff 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,17 +1,13 @@ -name: Build Verification +name: Manual Build Verification on: - pull_request: - branches: [main] - push: - branches: [main] workflow_dispatch: permissions: contents: read concurrency: - group: build-verification-${{ github.ref }} + group: manual-build-verification-${{ github.ref }} cancel-in-progress: true jobs: @@ -51,17 +47,5 @@ jobs: - name: Install dependencies run: pnpm install --frozen-lockfile - - name: Generate Prisma client - run: pnpm run db:generate - - - name: Lint - run: pnpm run lint - - - name: Typecheck - run: pnpm run typecheck - - - name: Unit tests - run: pnpm run test - - - name: Production build - run: pnpm run build + - name: Verify repository + run: pnpm run verify From 5f1ef146b63cf98edc3120aca6432edb8db73c40 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:03:19 +0000 Subject: [PATCH 13/24] ci(security): make CodeQL manual while Actions access is constrained --- .github/workflows/codeql.yml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 5f339aaf..d5b6ae4e 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,10 +1,6 @@ -name: CodeQL Advanced +name: Manual CodeQL Analysis on: - pull_request: - branches: [main] - schedule: - - cron: "15 6 * * 4" workflow_dispatch: permissions: @@ -14,7 +10,7 @@ permissions: security-events: write concurrency: - group: codeql-${{ github.ref }} + group: manual-codeql-${{ github.ref }} cancel-in-progress: true jobs: From 67e57c67de38b914b7968075e610eb963a84654c Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:03:52 +0000 Subject: [PATCH 14/24] docs(agent): document preview verification fallback --- AGENTS.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0139b0a6..42c8344c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,8 @@ GEM Enterprise is a controlled-access platform for cybersecurity, compliance, fi - **Default branch:** `main` - **Canonical host:** Vercel project `support371-gem-enterprise` - **Deployment method:** Vercel Git integration deploys `main`; agents must not run a second `vercel --prod` deployment from CI. +- **Automatic pull-request gate:** canonical Vercel preview builds run lint, type checking, unit tests, and the Next.js production build. +- **GitHub Actions status:** workflows remain available for manual execution; while hosted-runner access is constrained, their absence is not a passing result and Vercel preview verification is required. - **Current operating mode:** controlled production launch. Sensitive or provider-dependent features fail closed until verified. ## Tech Stack @@ -56,9 +58,9 @@ Every implementation task follows this sequence: 2. **Create a focused branch** using `feat/`, `fix/`, `chore/`, `docs/`, `security/`, or `test/`. 3. **Inspect before editing.** Read the affected routes, schema, tests, configuration, and recent related pull requests. 4. **Write a brief implementation plan** in the issue or pull request before broad changes. -5. **Implement the smallest complete vertical slice.** Avoid unrelated refactors. +5. **Implement the smallest complete vertical slice.** Avoid unrelated refactors and batch related edits before pushing to reduce unnecessary preview builds. 6. **Add or update tests** for success, authorization failure, validation failure, provider failure, and fail-closed behavior. -7. **Run the repository gate:** +7. **Run the repository gate locally or in the development agent environment:** ```bash corepack enable @@ -67,13 +69,14 @@ pnpm run verify ``` 8. **Open a pull request** with risks, manual dependencies, test evidence, and rollback notes. -9. **Verify the Vercel preview** for affected public routes and inspect runtime/build logs. -10. **Merge only after required checks pass.** Vercel Git integration deploys `main` to production. -11. **Run production smoke checks** without submitting sensitive data or causing billable external actions. +9. **Require the canonical Vercel preview to pass.** Preview builds automatically run lint, type checking, unit tests, Prisma generation, and the Next.js production build. Inspect its build logs and affected routes. +10. **Use the manual GitHub verification and CodeQL workflows when hosted-runner access is available.** Do not describe a workflow that never started as passing. +11. **Merge only after the available required gates pass.** Vercel Git integration deploys `main` to production. +12. **Run production smoke checks** without submitting sensitive data or causing billable external actions. ## Build Gate -`pnpm run verify` must complete successfully. It runs: +`pnpm run verify` must complete successfully in the agent environment before the pull request is presented as ready. It runs: - Prisma client generation - ESLint @@ -81,7 +84,9 @@ pnpm run verify - Unit tests - Next.js production build -If the full command cannot run because a required external dependency is unavailable, the agent must document the exact blocker and must not claim the feature is complete. +The canonical Vercel preview independently runs `pnpm run verify:preview` before building the application. This is the automatic hosted gate while GitHub Actions runner access is constrained. + +If verification cannot run because a required dependency or account service is unavailable, the agent must document the exact blocker and must not claim the feature is complete. ## Free-Tier Development Policy @@ -91,6 +96,7 @@ Development should preserve useful free operation: - Do not add a paid provider merely to complete a demo. - Build provider-independent interfaces and use local fakes in tests. - Keep optional integrations disabled by default. +- Batch related commits before pushing so one preview validates one coherent change set. - Add usage limits, queue boundaries, retention limits, and clear error states before enabling a metered service. - Treat billing approval, identity-provider contracts, production email credentials, regulated data sources, and external seller verification as owner-only actions. @@ -116,7 +122,9 @@ These remain disabled or request-only until their activation requirements pass: - `src/lib/storefrontPresentation.ts` — truthful request-only commerce presentation - `prisma/schema.prisma` — database schema - `next.config.js` — browser security headers and routing -- `.github/workflows/ci.yml` — canonical build verification gate +- `scripts/vercel-build.mjs` — Prisma, preview verification, and application build orchestration +- `.github/workflows/ci.yml` — manual full verification fallback +- `.github/workflows/codeql.yml` — manual CodeQL fallback - `docs/AGENT_BUILD_FLOW.md` — task and release operating procedure ## Commit and Pull Request Standards From 984b9c31fe0c0f57bdbb4fd2f8671e9a1562d446 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:04:20 +0000 Subject: [PATCH 15/24] docs(build): align workflow with preview verification fallback --- docs/AGENT_BUILD_FLOW.md | 76 ++++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 35 deletions(-) diff --git a/docs/AGENT_BUILD_FLOW.md b/docs/AGENT_BUILD_FLOW.md index cd3b8f01..377fbce4 100644 --- a/docs/AGENT_BUILD_FLOW.md +++ b/docs/AGENT_BUILD_FLOW.md @@ -2,11 +2,17 @@ ## Purpose -This flow allows GEM Enterprise to keep building with limited personnel time and minimal billing exposure while preserving a trustworthy production system. +This flow lets GEM Enterprise keep building with limited personnel time and minimal billing exposure while preserving a trustworthy production system. -The operating principle is: +> Humans define intent and approve high-impact decisions. Agents implement, test, document, and prepare pull requests. Hosted gates verify the work. Sensitive capabilities remain disabled until their infrastructure and owner approvals exist. -> Humans define intent and approve high-impact decisions. Agents implement, test, document, and prepare pull requests. Automated gates verify the work. Production-sensitive capabilities remain disabled until their infrastructure and owner approvals exist. +## Current hosted-gate arrangement + +- **Canonical automatic gate:** Vercel preview deployment for the canonical `support371-gem-enterprise` project. +- **What the preview runs:** Prisma generation, ESLint, TypeScript checking, Vitest, and the Next.js production build. +- **GitHub Actions:** build verification and CodeQL workflows remain available through manual dispatch. They are not automatic while hosted-runner access is constrained. +- **Production deployment:** Vercel Git integration deploys `main`. No second production deployment workflow is permitted. +- **Important:** a GitHub workflow that never starts is not a passing check. The Vercel preview and the agent's own `pnpm run verify` evidence are required. ## Roles @@ -28,7 +34,8 @@ Responsible for: - Focused implementation - Tests and documentation - Pull-request creation -- Build and preview verification +- Local or agent-environment verification +- Vercel preview verification - Reporting exact blockers and manual actions ### Review agent @@ -41,8 +48,6 @@ Responsible for an independent pass over: - Database and migration safety - Test coverage and rollback readiness -The lead agent and review agent may use different products, but every change still passes the same repository gate. - ## Canonical workflow ```text @@ -56,15 +61,17 @@ Inspect current code and related PRs ↓ Small vertical implementation ↓ -Unit/security/fail-closed tests +Unit, authorization, validation, and fail-closed tests ↓ -pnpm run verify +pnpm run verify in the agent environment ↓ Pull request ↓ -Independent review + CodeQL + Vercel preview +Canonical Vercel preview runs lint + typecheck + tests + build ↓ -Owner-only approval when billing/legal/provider action exists +Independent review; manual CodeQL when runner access is available + ↓ +Owner-only approval when billing, legal, or provider action exists ↓ Merge to main ↓ @@ -75,8 +82,6 @@ Production smoke check and rollback watch ## Work queue -Use four priority lanes. - ### P0 — Production safety Examples: @@ -129,9 +134,7 @@ Examples: - Biometrics - Marketplace transactions -Rules: - -- Keep disabled until P0–P2 requirements and owner approvals are complete. +Rule: keep these disabled until P0–P2 requirements and owner approvals are complete. ## Definition of ready @@ -153,16 +156,15 @@ A task is complete only when: - The implementation matches the issue scope. - Validation and authorization failures are tested. - Provider failure or missing configuration fails closed. -- `pnpm run verify` passes. -- Vercel preview routes work. +- `pnpm run verify` passes in the development-agent environment. +- The canonical Vercel preview passes its full preview verification and build. +- Affected preview routes work. - No secret or real sensitive document was used in testing. - The PR states what remains manual. - Production smoke checks pass after merge. ## Standard agent prompt -Use this prompt when delegating a repository task: - ```text Repository: support371/gem-enterprise @@ -180,16 +182,18 @@ Explicit exclusions: - No paid service activation - No production secrets - No direct commit to main -- No enabling sensitive uploads or payments unless this issue explicitly includes every required control and owner approval +- No enabling sensitive uploads or payments unless every required control and owner approval is included Required process: -1. Inspect affected code, schema, tests, and recent related PRs. +1. Inspect affected code, schema, tests, configuration, and recent related PRs. 2. Post a short plan. 3. Implement the smallest complete vertical slice. 4. Add tests for success, validation failure, authorization failure, and fail-closed behavior. -5. Run pnpm run verify. -6. Open a PR with risks, manual dependencies, and rollback steps. -7. Do not claim completion if any gate fails. +5. Run pnpm run verify in your environment. +6. Batch related changes before pushing to reduce preview builds. +7. Open a PR with risks, manual dependencies, and rollback steps. +8. Require the canonical Vercel preview to pass. +9. Do not claim completion if any available gate fails. ``` ## Recommended agent allocation @@ -203,25 +207,25 @@ Use for: - Refactors and migrations - Test creation - Pull-request preparation -- Parallel tasks that can be isolated by branch +- Parallel tasks isolated by branch -Codex should follow `AGENTS.md`, use one issue per task, and operate only through pull requests. +Codex must follow `AGENTS.md`, use one issue per task, run repository verification in its environment, and operate through pull requests. ### Independent review: GitHub Copilot coding agent or a second Codex task Use for: - Reviewing the PR without sharing the implementation conversation -- Looking for authorization, data-handling, and regression issues -- Suggesting missing tests +- Checking authorization, data handling, and regressions +- Finding missing tests ### Replit Agent -Use when a visual prototype or isolated experimental application is needed. Do not make it the canonical production repository or deployment path for GEM Enterprise. +Use for a visual prototype or isolated experiment. Do not make it the canonical production repository or deployment path. ### Devin -Use only for a clearly bounded backlog with sufficient paid capacity. It is not required for the current free-first flow. +Use only for a clearly bounded backlog when paid capacity is approved. It is not required for the current free-first flow. ## First implementation program: GEM Verify Core @@ -235,17 +239,18 @@ Build in this order: 6. Storage-provider interface with a fake test implementation 7. Retention and deletion scheduling model 8. Private upload adapter only after owner-selected storage and scanning are available -9. Optional Veriff or other provider adapter after sandbox approval +9. Optional Veriff or another provider adapter after sandbox approval Until step 8 is verified, `/api/kyc/documents` must remain fail closed. ## Free-tier safeguards -- Cancel superseded CI runs. -- Use one canonical verification job. +- Batch related edits before pushing so one preview validates one coherent change set. +- Cancel superseded preview and CI runs where supported. +- Use the canonical Vercel project only. - Let Vercel Git integration perform the only production deployment. - Use local fakes for external providers in tests. -- Do not run scheduled jobs more frequently than the business requires. +- Do not run scheduled jobs more frequently than required. - Keep optional integrations disabled by default. - Record usage and define a hard stop before enabling metered services. - Never rely on a free plan whose terms prohibit the intended business use. @@ -263,5 +268,6 @@ The agent must stop and request owner action for: - Naming authorized identity reviewers - Activating payment collection - Moving the production domain or database +- Disconnecting duplicate Vercel projects or changing organization-level GitHub billing and Actions settings -These gates are not development failures. They are separation-of-duty controls. +These gates are separation-of-duty controls, not development failures. From 1d32123eefc8eca6f398560fcc85b8b7fb3ce96d Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:12:21 +0000 Subject: [PATCH 16/24] fix(vercel): fail closed for duplicate project deployments --- scripts/vercel-ignore.mjs | 66 ++++++++++++++++++++++++++++++++++----- 1 file changed, 58 insertions(+), 8 deletions(-) diff --git a/scripts/vercel-ignore.mjs b/scripts/vercel-ignore.mjs index c42ca396..650e7660 100644 --- a/scripts/vercel-ignore.mjs +++ b/scripts/vercel-ignore.mjs @@ -1,15 +1,65 @@ const canonicalProjectId = "prj_VDGqnA7wZt2E65LLvT94ZOpnYc2Z"; -const currentProjectId = process.env.VERCEL_PROJECT_ID?.trim(); +const canonicalMarkers = [ + "support371-gem-enterprise", + "www.gemcybersecurityassist.com", + "gemcybersecurityassist.com", +]; +const knownDuplicateMarkers = [ + "project-dtrl6", + "gem-enterprise-admin-25521151s-projects", + "gem-enterprise-git-", +]; -if (!currentProjectId) { - console.log("VERCEL_PROJECT_ID is unavailable; continue the build safely."); +const projectId = process.env.VERCEL_PROJECT_ID?.trim() || ""; +const deploymentSignals = [ + process.env.VERCEL_PROJECT_PRODUCTION_URL, + process.env.VERCEL_URL, + process.env.VERCEL_BRANCH_URL, + process.env.VERCEL_TARGET_ENV, +] + .filter((value) => typeof value === "string" && value.trim().length > 0) + .map((value) => value.trim().toLowerCase()); + +function continueBuild(reason) { + console.log(`[vercel-ignore] Continue build: ${reason}`); process.exit(1); } -if (currentProjectId === canonicalProjectId) { - console.log(`Canonical Vercel project ${canonicalProjectId}; continue the build.`); - process.exit(1); +function ignoreBuild(reason) { + console.log(`[vercel-ignore] Ignore build: ${reason}`); + process.exit(0); +} + +if (projectId) { + if (projectId === canonicalProjectId) { + continueBuild(`canonical project ID ${canonicalProjectId}`); + } + + ignoreBuild( + `non-canonical project ID ${projectId}; canonical project is ${canonicalProjectId}`, + ); +} + +if ( + deploymentSignals.some((signal) => + canonicalMarkers.some((marker) => signal.includes(marker)), + ) +) { + continueBuild(`canonical project marker detected in ${deploymentSignals.join(", ")}`); +} + +if ( + deploymentSignals.some((signal) => + knownDuplicateMarkers.some((marker) => signal.includes(marker)), + ) +) { + ignoreBuild(`known duplicate marker detected in ${deploymentSignals.join(", ")}`); +} + +if (process.env.VERCEL === "1" || process.env.CI === "1") { + ignoreBuild( + "Vercel project identity could not be verified. Failing closed to prevent an unknown or duplicate project from consuming build capacity.", + ); } -console.log(`Ignoring duplicate Vercel project ${currentProjectId}; canonical project is ${canonicalProjectId}.`); -process.exit(0); +continueBuild("local non-Vercel environment"); From 8f31d12d56400f92281ef4e0a0a37028fece4a90 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 19:13:28 +0000 Subject: [PATCH 17/24] docs(vercel): document canonical project build guard --- docs/AGENT_BUILD_FLOW.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/AGENT_BUILD_FLOW.md b/docs/AGENT_BUILD_FLOW.md index 377fbce4..2f0e0306 100644 --- a/docs/AGENT_BUILD_FLOW.md +++ b/docs/AGENT_BUILD_FLOW.md @@ -8,11 +8,13 @@ This flow lets GEM Enterprise keep building with limited personnel time and mini ## Current hosted-gate arrangement -- **Canonical automatic gate:** Vercel preview deployment for the canonical `support371-gem-enterprise` project. -- **What the preview runs:** Prisma generation, ESLint, TypeScript checking, Vitest, and the Next.js production build. +- **Canonical automatic gate:** Vercel preview deployment for project `support371-gem-enterprise` (`prj_VDGqnA7wZt2E65LLvT94ZOpnYc2Z`). +- **Duplicate protection:** `scripts/vercel-ignore.mjs` allows only the canonical project to build. Any non-canonical project ID or recognized duplicate URL is ignored before the build begins. Unknown Vercel projects fail closed. +- **Confirmed duplicates awaiting dashboard disconnection:** `gem-enterprise` (`prj_iT8bNqbTiePiM2SZiWTkOUJXy3o0`) and `project-dtrl6` (`prj_TUZk9mqccnIGSsSpsti7jwg9D3W2`). +- **What the canonical preview runs:** Prisma generation, ESLint, TypeScript checking, Vitest, and the Next.js production build. - **GitHub Actions:** build verification and CodeQL workflows remain available through manual dispatch. They are not automatic while hosted-runner access is constrained. - **Production deployment:** Vercel Git integration deploys `main`. No second production deployment workflow is permitted. -- **Important:** a GitHub workflow that never starts is not a passing check. The Vercel preview and the agent's own `pnpm run verify` evidence are required. +- **Important:** a GitHub workflow that never starts is not a passing check. The canonical Vercel preview and the agent's own `pnpm run verify` evidence are required. ## Roles @@ -67,6 +69,8 @@ pnpm run verify in the agent environment ↓ Pull request ↓ +Duplicate Vercel projects are ignored + ↓ Canonical Vercel preview runs lint + typecheck + tests + build ↓ Independent review; manual CodeQL when runner access is available @@ -249,6 +253,7 @@ Until step 8 is verified, `/api/kyc/documents` must remain fail closed. - Cancel superseded preview and CI runs where supported. - Use the canonical Vercel project only. - Let Vercel Git integration perform the only production deployment. +- Keep `scripts/vercel-ignore.mjs` fail closed for any unknown or non-canonical Vercel project. - Use local fakes for external providers in tests. - Do not run scheduled jobs more frequently than required. - Keep optional integrations disabled by default. From 36efa39c4d1c1f18cd2aaf73833e6c0aa3fc81c1 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 20:41:41 +0100 Subject: [PATCH 18/24] docs(vercel): record completed duplicate-project disconnect --- docs/VERCEL_CANONICAL_PROJECT.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/VERCEL_CANONICAL_PROJECT.md diff --git a/docs/VERCEL_CANONICAL_PROJECT.md b/docs/VERCEL_CANONICAL_PROJECT.md new file mode 100644 index 00000000..c002335a --- /dev/null +++ b/docs/VERCEL_CANONICAL_PROJECT.md @@ -0,0 +1,29 @@ +# Canonical Vercel Project + +Verified on 2026-07-09 after the dashboard cleanup. + +## Canonical project + +- Name: `support371-gem-enterprise` +- Project ID: `prj_VDGqnA7wZt2E65LLvT94ZOpnYc2Z` +- Production domains: + - `https://www.gemcybersecurityassist.com` + - `https://gemcybersecurityassist.com` + +This is the only Vercel project authorized to build and deploy `support371/gem-enterprise`. + +## Disconnected duplicate projects + +- `gem-enterprise` — `prj_iT8bNqbTiePiM2SZiWTkOUJXy3o0` +- `project-dtrl6` — `prj_TUZk9mqccnIGSsSpsti7jwg9D3W2` + +After their Git connections were removed, neither duplicate created a deployment from subsequent repository activity. The repository-level `scripts/vercel-ignore.mjs` guard remains enabled as defense in depth and fails closed for non-canonical or unknown Vercel projects. + +## Verification rule + +Before merging a pull request: + +1. Confirm the pull-request head creates a deployment only in the canonical project. +2. Confirm the canonical preview reaches `READY`. +3. Inspect the canonical build logs for lint, TypeScript, unit-test, Prisma, and Next.js build results. +4. Do not treat historical checks from disconnected projects as current deployment evidence. From 2b757bd6926626a2f02935f37da06b2d3abe086d Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 20:44:03 +0100 Subject: [PATCH 19/24] chore(vercel): trigger canonical connection verification --- scripts/vercel-ignore.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/vercel-ignore.mjs b/scripts/vercel-ignore.mjs index 650e7660..4a9012c1 100644 --- a/scripts/vercel-ignore.mjs +++ b/scripts/vercel-ignore.mjs @@ -1,3 +1,4 @@ +// Defense-in-depth: only the canonical GEM Vercel project may consume a build. const canonicalProjectId = "prj_VDGqnA7wZt2E65LLvT94ZOpnYc2Z"; const canonicalMarkers = [ "support371-gem-enterprise", From 41050e0c08449c6bc282c4ead34c4348ca3330a1 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 20:45:43 +0100 Subject: [PATCH 20/24] fix(vercel): retain lint and test files for preview verification --- .vercelignore | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/.vercelignore b/.vercelignore index 50645e37..31d14123 100644 --- a/.vercelignore +++ b/.vercelignore @@ -1,23 +1,14 @@ -# Development and testing artifacts -src/test/ -*.test.ts -*.test.tsx -*.spec.ts -*.spec.tsx - -# Supabase local tooling is not needed at runtime +# Supabase local tooling is not needed during application builds supabase/ -# Documentation +# Documentation is excluded from deployment bundles *.md DEPLOYMENT.md -# Config files not needed at runtime +# Local environment templates are not deployed .env.example -eslint.config.mjs -vitest.config.ts -# Misc +# Editor and workstation artifacts .idea/ .vscode/ .DS_Store From 9e1295d07c4f13b7fd0b78bac6ddfd98907439c8 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 20:49:41 +0100 Subject: [PATCH 21/24] docs(vercel): mark duplicate projects disconnected --- docs/AGENT_BUILD_FLOW.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/AGENT_BUILD_FLOW.md b/docs/AGENT_BUILD_FLOW.md index 2f0e0306..61e450ee 100644 --- a/docs/AGENT_BUILD_FLOW.md +++ b/docs/AGENT_BUILD_FLOW.md @@ -10,7 +10,7 @@ This flow lets GEM Enterprise keep building with limited personnel time and mini - **Canonical automatic gate:** Vercel preview deployment for project `support371-gem-enterprise` (`prj_VDGqnA7wZt2E65LLvT94ZOpnYc2Z`). - **Duplicate protection:** `scripts/vercel-ignore.mjs` allows only the canonical project to build. Any non-canonical project ID or recognized duplicate URL is ignored before the build begins. Unknown Vercel projects fail closed. -- **Confirmed duplicates awaiting dashboard disconnection:** `gem-enterprise` (`prj_iT8bNqbTiePiM2SZiWTkOUJXy3o0`) and `project-dtrl6` (`prj_TUZk9mqccnIGSsSpsti7jwg9D3W2`). +- **Disconnected duplicates:** `gem-enterprise` (`prj_iT8bNqbTiePiM2SZiWTkOUJXy3o0`) and `project-dtrl6` (`prj_TUZk9mqccnIGSsSpsti7jwg9D3W2`) were disconnected from the repository on 2026-07-09. A fresh commit created no deployments in either project. - **What the canonical preview runs:** Prisma generation, ESLint, TypeScript checking, Vitest, and the Next.js production build. - **GitHub Actions:** build verification and CodeQL workflows remain available through manual dispatch. They are not automatic while hosted-runner access is constrained. - **Production deployment:** Vercel Git integration deploys `main`. No second production deployment workflow is permitted. From 30008d41b23ede1e2d5a056b7fe51c07151b4c91 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 20:50:55 +0100 Subject: [PATCH 22/24] docs(vercel): record successful canonical preview gate --- docs/VERCEL_CANONICAL_PROJECT.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/VERCEL_CANONICAL_PROJECT.md b/docs/VERCEL_CANONICAL_PROJECT.md index c002335a..20d0898c 100644 --- a/docs/VERCEL_CANONICAL_PROJECT.md +++ b/docs/VERCEL_CANONICAL_PROJECT.md @@ -19,11 +19,23 @@ This is the only Vercel project authorized to build and deploy `support371/gem-e After their Git connections were removed, neither duplicate created a deployment from subsequent repository activity. The repository-level `scripts/vercel-ignore.mjs` guard remains enabled as defense in depth and fails closed for non-canonical or unknown Vercel projects. +## Verified preview gate + +Canonical preview deployment `dpl_7zyuXQAuMaVE1ywj6eo4HRoyS2C6` reached `READY` for code commit `41050e0c08449c6bc282c4ead34c4348ca3330a1` after completing: + +- Prisma client generation +- ESLint +- TypeScript checking +- 14 Vitest files and 164 passing tests +- Next.js 16 production compilation and deployment + +Subsequent changes to this document are documentation-only and are excluded from the deployment bundle by `.vercelignore`. + ## Verification rule Before merging a pull request: -1. Confirm the pull-request head creates a deployment only in the canonical project. +1. Confirm the pull-request code head creates a deployment only in the canonical project. 2. Confirm the canonical preview reaches `READY`. 3. Inspect the canonical build logs for lint, TypeScript, unit-test, Prisma, and Next.js build results. 4. Do not treat historical checks from disconnected projects as current deployment evidence. From a0d19c4ad07b8bd75079a080874cf5024747cdb2 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 20:51:15 +0100 Subject: [PATCH 23/24] docs(vercel): finalize canonical preview record --- docs/VERCEL_CANONICAL_PROJECT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/VERCEL_CANONICAL_PROJECT.md b/docs/VERCEL_CANONICAL_PROJECT.md index 20d0898c..8ad4b241 100644 --- a/docs/VERCEL_CANONICAL_PROJECT.md +++ b/docs/VERCEL_CANONICAL_PROJECT.md @@ -29,7 +29,7 @@ Canonical preview deployment `dpl_7zyuXQAuMaVE1ywj6eo4HRoyS2C6` reached `READY` - 14 Vitest files and 164 passing tests - Next.js 16 production compilation and deployment -Subsequent changes to this document are documentation-only and are excluded from the deployment bundle by `.vercelignore`. +This file is documentation-only and excluded from the deployment bundle by `.vercelignore`, so later documentation commits do not change the verified application build. ## Verification rule From 964adf0c8c4b3212411ea97e1c53e42b0d21f1c4 Mon Sep 17 00:00:00 2001 From: GEM CYBERSECURITY-MONITORING ASSIST Date: Thu, 9 Jul 2026 20:51:31 +0100 Subject: [PATCH 24/24] docs(vercel): lock verified canonical record