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.
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user