feat: add CONVENTIONS.md, reviewer references it instead of hardcoding rules

- CONVENTIONS.md covers: language paradigm, naming, error handling,
  workflow/sense structure, role patterns, meta convention, git rules
- Reviewer prompt now: cat CONVENTIONS.md + check diff against it
- Single source of truth for all roles

CONVENTIONS.md

@@ -0,0 +1,152 @@
+# Nerve Workspace Conventions
+
+This document defines coding and workflow conventions for the nerve-workspace (`~/.uncaged-nerve`).
+All roles (planner, coder, reviewer, tester) should reference this file.
+
+## Language & Paradigm
+
+### Functional-first
+
+Use `function` + `type`, not `class` + `interface`.
+
+```typescript
+// ✅ Good
+type Signal = { senseId: string; value: unknown; ts: number };
+function createSignal(senseId: string, value: unknown): Signal { ... }
+
+// ❌ Bad
+class Signal implements ISignal { ... }
+```
+
+### Rules
+
+| Rule | Description |
+|------|-------------|
+| `type` over `interface` | All type definitions use `type` |
+| `function` over `class` | Pure functions + closures, no class |
+| No `this` | Functions must not depend on `this` context |
+| No inheritance | No `extends`, `implements`, `abstract` |
+| Composition over inheritance | Use function composition |
+| No optional properties | Use `T \| null` instead of `?:` |
+| No dynamic `import()` | Always static top-level `import` |
+| `async/await` only | Never `.then()` chains |
+
+### Exceptions
+
+Classes allowed when required by a library (e.g. Drizzle `sqliteTable`) or Error subclasses.
+
+## Naming
+
+| Type | Style | Example |
+|------|-------|---------|
+| Files | kebab-case | `signal-bus.ts` |
+| Types | PascalCase | `SignalBus` |
+| Functions/variables | camelCase | `createSignalBus` |
+| Constants | UPPER_SNAKE | `MAX_RETRY_COUNT` |
+
+## Error Handling
+
+- Use `Result<T, E>` for expected failures
+- `throw` only for unrecoverable bugs
+- No try-catch for flow control
+
+```typescript
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+```
+
+## Workflow Structure
+
+Each workflow follows the multi-file pattern:
+
+```
+workflows/<name>/
+  index.ts          — WorkflowDefinition default export (thin entry point)
+  build.ts          — factory function with dependency injection
+  moderator.ts      — moderator function + WorkflowMeta type
+  roles/
+    <role>/
+      index.ts      — build function + meta schema
+      prompt.ts     — prompt pure function (string template)
+  package.json      — with esbuild build script
+  tsconfig.json
+```
+
+### Role Implementation Patterns
+
+| Pattern | When to use | Example |
+|---------|-------------|---------|
+| `createCursorRole` | Needs file system access (code generation, planning) | planner, coder |
+| `createHermesRole` | Needs shell + tools (testing, reviewing) | tester, reviewer |
+| `createLlmRole` | Pure LLM reasoning, no tools | analysis roles |
+| Direct `Role<Meta>` | No LLM needed, scripted logic | committer |
+
+### Meta Convention
+
+Meta is a **routing signal only** — one boolean per role:
+- `{ ready: boolean }` — planner
+- `{ done: boolean }` — coder
+- `{ approved: boolean }` — reviewer
+- `{ passed: boolean }` — tester
+- `{ success: boolean }` — committer
+
+### Standard Flow
+
+```
+planner → coder → reviewer → tester → committer → END
+```
+
+- Reviewer rejection → back to coder (within MAX_CODER_ITERATIONS)
+- Tester failure → back to coder (within MAX_CODER_ITERATIONS)
+- Committer failure → back to coder (within MAX_CODER_ITERATIONS)
+
+## Sense Structure
+
+```
+senses/<name>/
+  src/
+    index.ts        — compute() function + schema
+    schema.ts       — Drizzle table definition
+  migrations/       — SQLite migrations
+  package.json      — with esbuild build script
+```
+
+## Toolchain
+
+| Tool | Purpose |
+|------|---------|
+| **pnpm** | Package manager (workspace mode) |
+| **TypeScript** | Type checking |
+| **esbuild** | Bundling (each workflow/sense bundles independently) |
+
+### Commands
+
+```bash
+pnpm build          # build all packages
+pnpm -r build       # same, explicit recursive
+cd workflows/<name> && pnpm build   # build one workflow
+```
+
+## Git & Commit Convention
+
+```
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: workflow | sense | core | ...
+```
+
+### What NOT to commit
+
+- `node_modules/`
+- `dist/` (build outputs, generated by esbuild)
+- `.DS_Store`
+- pnpm cache artifacts (e.g. `false/` directories from `--no-cache` misuse)
+- Secrets, API keys, tokens
+- Unrelated file changes outside the task scope
+
+## Dependencies
+
+Shared packages from the nerve monorepo:
+- `@uncaged/nerve-core` — types, END constant, WorkflowDefinition
+- `@uncaged/nerve-workflow-utils` — role factories, spawnSafe, llmExtract, cursorAgent
+- `zod` — schema definitions for meta extraction

workflows/gitea-issue-solver/roles/reviewer/prompt.ts

@@ -4,6 +4,7 @@ export function reviewerPrompt({ threadId, nerveRoot }: { threadId: string; nerv
 **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. Always \`cd ${nerveRoot}\` first.**
 
 Read the workflow thread for context: \`nerve thread ${threadId}\`
+Read project conventions: \`cat ${nerveRoot}/CONVENTIONS.md\`
 
 ## Your job — static analysis of the git diff
 
@@ -15,20 +16,16 @@ Run these commands and analyze the output:
 
 ## Checklist
 
+Review the diff against CONVENTIONS.md. Key things to catch:
+
 ### 🔴 Reject (approved: false) — tell coder exactly what to fix
-- **Garbage files**: node_modules/, .DS_Store, pnpm cache artifacts (e.g. \`false/\` directory), build outputs (dist/) that shouldn't be committed
+- **Garbage files**: anything listed under "What NOT to commit" in CONVENTIONS.md
 - **Secrets/credentials**: API keys, tokens, passwords hardcoded in the diff
 - **Unrelated changes**: files modified outside the scope of the task
-- **Debug code**: console.log, debugger statements, TODO/FIXME without context
+- **Convention violations**: patterns that contradict CONVENTIONS.md (e.g. \`interface\` instead of \`type\`, \`class\`, dynamic \`import()\`, optional properties with \`?:\`)
-- **Hardcoded paths** that should be configurable
-- **Wrong patterns**: dynamic import(), interfaces instead of types, broken routing
 
 ### ✅ Approve (approved: true) — no comment needed
-If everything looks clean, just approve. Do not add suggestions or warnings — they won't be seen.
+- Diff is clean, focused, follows conventions
-
-## Output
-
-Summarize what you found. If garbage files or secrets are present, list them explicitly so the coder knows what to clean up.
 
 End with:
 \`\`\`json

workflows/sense-generator/roles/reviewer/prompt.ts

@@ -4,6 +4,7 @@ export function reviewerPrompt({ threadId, nerveRoot }: { threadId: string; nerv
 **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. Always \`cd ${nerveRoot}\` first.**
 
 Read the workflow thread for context: \`nerve thread ${threadId}\`
+Read project conventions: \`cat ${nerveRoot}/CONVENTIONS.md\`
 
 ## Your job — static analysis of the git diff
 
@@ -15,20 +16,16 @@ Run these commands and analyze the output:
 
 ## Checklist
 
+Review the diff against CONVENTIONS.md. Key things to catch:
+
 ### 🔴 Reject (approved: false) — tell coder exactly what to fix
-- **Garbage files**: node_modules/, .DS_Store, pnpm cache artifacts (e.g. \`false/\` directory), build outputs (dist/) that shouldn't be committed
+- **Garbage files**: anything listed under "What NOT to commit" in CONVENTIONS.md
 - **Secrets/credentials**: API keys, tokens, passwords hardcoded in the diff
 - **Unrelated changes**: files modified outside the scope of the task
-- **Debug code**: console.log, debugger statements, TODO/FIXME without context
+- **Convention violations**: patterns that contradict CONVENTIONS.md (e.g. \`interface\` instead of \`type\`, \`class\`, dynamic \`import()\`, optional properties with \`?:\`)
-- **Hardcoded paths** that should be configurable
-- **Wrong patterns**: dynamic import(), interfaces instead of types, broken routing
 
 ### ✅ Approve (approved: true) — no comment needed
-If everything looks clean, just approve. Do not add suggestions or warnings — they won't be seen.
+- Diff is clean, focused, follows conventions
-
-## Output
-
-Summarize what you found. If garbage files or secrets are present, list them explicitly so the coder knows what to clean up.
 
 End with:
 \`\`\`json

workflows/workflow-generator/roles/reviewer/prompt.ts

@@ -4,6 +4,7 @@ export function reviewerPrompt({ threadId, nerveRoot }: { threadId: string; nerv
 **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. Always \`cd ${nerveRoot}\` first.**
 
 Read the workflow thread for context: \`nerve thread ${threadId}\`
+Read project conventions: \`cat ${nerveRoot}/CONVENTIONS.md\`
 
 ## Your job — static analysis of the git diff
 
@@ -15,20 +16,16 @@ Run these commands and analyze the output:
 
 ## Checklist
 
+Review the diff against CONVENTIONS.md. Key things to catch:
+
 ### 🔴 Reject (approved: false) — tell coder exactly what to fix
-- **Garbage files**: node_modules/, .DS_Store, pnpm cache artifacts (e.g. \`false/\` directory), build outputs (dist/) that shouldn't be committed
+- **Garbage files**: anything listed under "What NOT to commit" in CONVENTIONS.md
 - **Secrets/credentials**: API keys, tokens, passwords hardcoded in the diff
 - **Unrelated changes**: files modified outside the scope of the task
-- **Debug code**: console.log, debugger statements, TODO/FIXME without context
+- **Convention violations**: patterns that contradict CONVENTIONS.md (e.g. \`interface\` instead of \`type\`, \`class\`, dynamic \`import()\`, optional properties with \`?:\`)
-- **Hardcoded paths** that should be configurable
-- **Wrong patterns**: dynamic import(), interfaces instead of types, broken routing
 
 ### ✅ Approve (approved: true) — no comment needed
-If everything looks clean, just approve. Do not add suggestions or warnings — they won't be seen.
+- Diff is clean, focused, follows conventions
-
-## Output
-
-Summarize what you found. If garbage files or secrets are present, list them explicitly so the coder knows what to clean up.
 
 End with:
 \`\`\`json