Files

T

Moheeb Zara ea8d7a5f91 feat: governance kernel, deployment hardening, local-dev stack

Adds proposals + proposal_votes + policies + incidents + incident_updates
tables with full RLS, async voting flow, dismissal-appeal pathway,
versioned policies with provenance, and an anonymous-incident token mode.
Adds per-space configurable areas, financial visibility settings, member
self-profile + COI disclosure, and a mission statement that renders in
the app footer.

Reorganises lib/actions.ts into per-domain files (tasks, projects,
members, payments, contacts, knowledge-base, secrets, area-leads,
settings, imports, proposals, incidents, policies, areas) plus a barrel.
Adds lib/permissions.ts and lib/auth-helpers.ts so action bodies stop
duplicating the user-to-member-to-role check. Wires every action that has
a Zod schema; introduces a flexibleDateTime preprocessor so HTML date
pickers no longer hit "Invalid datetime".

Hardens RLS: drops NOT NULL on space_members.user_id for offline members,
adds a privilege-escalation trigger that blocks self-edits to role / tier
/ status / approved / has_card_access / space_id, closes four
cross-tenant holes in the governance kernel, and adds a partial unique
index so two admins cannot concurrently activate two drafts of the same
policy slug.

Ships every deployment artifact: Dockerfile, docker-compose,
.do/app.yaml, .env.example, /api/health, plus a managed-Supabase guide
(docs/DEPLOYMENT.md), an end-to-end self-hosted Droplet guide
(docs/DEPLOY_DO_SELFHOSTED.md), and a Supabase-CLI local-dev quickstart
(docs/LOCAL_DEV.md). Replaces middleware.ts with proxy.ts for Next.js 16.
Adds scripts/schema.sql as the canonical idempotent full deploy plus
fourteen numbered incremental migrations.

Adds scripts/seed.sql so a fresh local DB renders something instead of
empty pages: a demo space, five members across all roles, a v1 code of
conduct, three proposals in different states with seven votes already
cast, an open incident, a project, three tasks, a KB entry, and matching
activity-log rows.

Replaces v0-generated test scaffolding with 266 real tests across
__tests__/{actions,auth-helpers,components,governance,permissions,
security,utils,validations}.test.ts. Adds react-markdown + remark-gfm
for proposal / incident / policy body rendering. Deletes four dead v0
fix-* scripts, the unused components/app-shell.tsx, and the duplicate
app/auth/login/page.tsx.

Routes (31 total): /api/health, /api/paypal/sync, /auth/callback, /,
/login, /signup, /signup/confirm, /dashboard, /tasks, /projects,
/members, /payments, /financials, /contacts, /ops, /ops/[id], /ops/new,
/proposals, /proposals/[id], /proposals/new, /incidents, /incidents/[id],
/incidents/new, /policies, /policies/[slug], /policies/new, /profile,
/recruitment, /settings, /comms, /import.

Full pass-by-pass history is in docs/HANDOFF.md; the roadmap is in
docs/GOVERNANCE_FEATURES.md.

2026-05-14 04:52:11 -07:00

5.0 KiB

Raw Blame History

Working Agreement for Claude

This file is the standing brief for any Claude session in this repository. Read it before touching code, every session.

Identity rules

Never include Claude attribution in commits. No Co-Authored-By: Claude, no Generated with Claude Code, no emoji robot signatures. Commits must look like a human wrote them.
Never include Claude attribution in pull request descriptions, code comments, or generated documents unless the user explicitly asks for it.

Writing rules

No emojis anywhere: not in code, comments, commits, PR bodies, docs, or chat replies. The user reads them as AI tells.
No em dashes (—). Use a period, a colon, a semicolon, or parentheses depending on the sentence.
No "AI language" patterns: avoid "Let me", "I'll go ahead and", "Sure!", "Certainly!", "delve", "leverage", "robust", "seamless", "comprehensive", "best practices", filler hedges, and breathless intros. Be direct and specific.
No hype, no sales copy. Describe what something does, not how great it is.
Code comments only when the WHY is non-obvious. Never comments that say WHAT the code does.

Engineering rules

Be cautious. Be careful. Be smart.
Smart separation of concerns: server actions in lib/, UI in components/ and app/(app)/*-client.tsx, data access through lib/supabase/*. Do not cross these lines without a reason you can defend in a sentence.
Test-driven where practical: when changing a server action or a utility, write or update the test first. Tests live in __tests__/ (Vitest) and e2e/ (Playwright). New tests must run with pnpm test and pnpm test:e2e without extra config.
Match the existing patterns. If you find yourself inventing a new abstraction, stop and ask why the current one is wrong.
Do not refactor while fixing a bug. Land the fix. Refactor in a separate change.
Do not introduce backwards-compat shims for code you wrote in the same session.
Use parameterized queries through the Supabase client. Never build raw SQL with string concatenation.
Validate input at the server-action boundary with Zod schemas from lib/validations.ts. Reject before you touch the database.

Database rules

The canonical schema lives in scripts/schema.sql. It must remain idempotent and runnable top-to-bottom on a clean Supabase project.
When you add a column, table, enum, or policy, add it to scripts/schema.sql AND add a numbered incremental migration in scripts/ named NNN_short_description.sql so existing deployments can upgrade.
When you change a column on an existing deployment, the incremental migration runs first, then scripts/schema.sql is updated to match.
Never break RLS. Every new table starts with ENABLE ROW LEVEL SECURITY and explicit policies for SELECT, INSERT, UPDATE, DELETE before it is merged.
Enum changes require a migration, never a re-create. ALTER TYPE ... ADD VALUE is the only safe path.
After any schema change, refresh types/database.ts and update DB_SCHEMA_MAP.md.

Deployment rules

A fresh clone must produce a working app with no more than: clone, pnpm install, copy .env.example to .env.local with real values, run scripts/schema.sql in Supabase, pnpm dev.
A fresh production deploy (Vercel, DigitalOcean App Platform, Droplet) must be documented in docs/DEPLOYMENT.md step by step, no implicit knowledge required.
Any new environment variable must be added to .env.example in the same change that introduces it. Never let a deploy fail because an env var was only documented in a Slack thread.
The Dockerfile and docker-compose configuration in the repo are the source of truth for self-hosted deploys. Update them when the runtime requirements change.

Documentation rules

Always document. If you add a feature, a server action, or a table, update the relevant doc in the same change:
- docs/ARCHITECTURE.md for structural changes
- docs/API_REFERENCE.md for new server actions
- docs/DATABASE_SCHEMA.md and DB_SCHEMA_MAP.md for schema changes
- docs/DEPLOYMENT.md for new env vars or new deploy steps
Documentation describes the system as it is, not as it might be. Mark known gaps with a clear "Not implemented" or "Planned" so readers do not mistake intent for reality.

Handoff rules

For long sessions (anything over ~30 minutes of active work, or any session that touched more than three files), update docs/HANDOFF.md at the end of the session.
A handoff entry includes: date in YYYY-MM-DD, branch name, what changed, why, what is still open, and any pending decisions the user needs to make.
A handoff is a one-screen read. Bullets, not paragraphs.

Authorization rules

Do not run destructive git operations without explicit user confirmation: push --force, reset --hard, branch -D, clean -f.
Do not commit, push, or open a pull request unless the user asked for it. Authorization is per-request, not standing.
Do not skip pre-commit hooks (--no-verify). If a hook fails, fix the underlying problem.

When in doubt

Ask. The cost of a clarifying question is small. The cost of a wrong action is large.

5.0 KiB Raw Blame History