pluribus-context 0.2.0

package/docs/openclaw-integration.md

@@ -0,0 +1,145 @@
+# OpenClaw Integration
+
+OpenClaw is an AI agent runner that uses **`AGENTS.md`** as its primary context file. Pluribus can generate and keep `AGENTS.md` in sync from a single `pluribus.md` source.
+
+---
+
+## How It Works
+
+OpenClaw reads `AGENTS.md` on startup to understand:
+
+- The agent's **identity** — name, role, persona
+- **Sub-agent system** — what agents exist and when to spawn them
+- **Tools and integrations** — external services the agent can use
+- **Operating rules** — constraints, protocols, and guardrails
+- **Soul/tone** — how the agent communicates
+
+Pluribus maps your `pluribus.md` sections to a well-structured `AGENTS.md`:
+
+| `pluribus.md` section | `AGENTS.md` output |
+|---|---|
+| `# Identity` | Identity block (name, role, emoji) |
+| `# Agents` | Sub-agent system table |
+| `# Stack` | Tools and integrations |
+| `# Conventions` | Operating protocols |
+| `# Constraints` | Hard rules and guardrails |
+| `# Soul` | Tone and behavior guidance |
+
+---
+
+## Workflow
+
+### 1. Initialize
+
+```bash
+cd your-openclaw-workspace/
+pluribus init --tools openclaw
+```
+
+This scaffolds `pluribus.md` with OpenClaw-specific sections pre-filled.
+
+### 2. Edit `pluribus.md`
+
+Write your agent context once:
+
+```markdown
+# Identity
+
+I am Friday, the primary AI agent for Lucio.
+
+# Agents
+
+| Agent | Role | When to spawn |
+|---|---|---|
+| FORGE | Engineering | All coding tasks |
+| ARGUS | Research | Feed collection, market signals |
+
+# Constraints
+
+- Never write code directly — delegate to FORGE
+- Never send external messages without confirmation
+```
+
+### 3. Sync
+
+```bash
+pluribus sync --tools openclaw
+```
+
+Output:
+
+```
+🔄 Syncing pluribus.md → openclaw
+
+   ✅ [openclaw] → AGENTS.md
+
+✅ Sync complete — 1 file(s) written.
+```
+
+### 4. OpenClaw picks it up
+
+On next gateway startup (or `openclaw gateway restart`), OpenClaw reads the updated `AGENTS.md` and your agent reflects the new context.
+
+---
+
+## File Placement
+
+By default, `AGENTS.md` is written to the current directory (your OpenClaw workspace root). This is typically:
+
+```
+workspace/
+├── pluribus.md         ← your source of truth
+├── AGENTS.md           ← generated by pluribus sync
+├── SOUL.md             ← tone file (optional, not generated)
+└── TOOLS.md            ← tool notes (optional, not generated)
+```
+
+---
+
+## Dry Run
+
+Preview what will be generated without writing:
+
+```bash
+pluribus sync --tools openclaw --dry-run
+```
+
+---
+
+## Example
+
+See [`examples/openclaw/`](../examples/openclaw/) for a full working example:
+
+- [`pluribus.md`](../examples/openclaw/pluribus.md) — source context file
+- [`AGENTS.md`](../examples/openclaw/AGENTS.md) — generated output
+
+---
+
+## OpenClaw-Specific Sections
+
+When targeting OpenClaw, two sections unlock additional output:
+
+### `# Agents` (sub-agent table)
+
+Generates the sub-agent routing table in `AGENTS.md`:
+
+```markdown
+# Agents
+
+| Agent | Role | When to spawn |
+|---|---|---|
+| FORGE ⚙️ | Engineering | All coding and system-building |
+| ARGUS 🔍 | Research    | Market signals, feed collection |
+```
+
+### `# Soul`
+
+Maps to a behavioral guidance block in `AGENTS.md`. This is the tone section — how the agent communicates, what it avoids, how it handles uncertainty.
+
+---
+
+## Notes
+
+- `AGENTS.md` is generated — do not edit it manually. Edit `pluribus.md` and re-sync.
+- If you also use Claude Code, run `pluribus sync --tools openclaw,claude` to update both `AGENTS.md` and `CLAUDE.md` from the same source.
+- The OpenClaw skill is built-in — no configuration needed.

package/docs/release-checklist.md

@@ -0,0 +1,91 @@
+# Release checklist
+
+This checklist keeps Pluribus releases reproducible and avoids accidentally publishing stale context, missing docs, or a package name that collides with an unrelated project.
+
+## 0. Preconditions
+
+- Work from a clean `main` branch tracking `origin/main`.
+- Confirm the package name is available or intentionally chosen:
+  - `npm view pluribus-context name version description`
+  - `npm view pluribus name version description` — expected to return an unrelated package, so do not publish as `pluribus`.
+- Confirm npm auth only through the npm CLI/session, never by writing tokens into the repo:
+  - `npm whoami`
+
+## 1. Version and release notes
+
+- Update `package.json` version.
+- Update `CHANGELOG.md` with user-facing changes, migration notes, and verification commands.
+- Confirm README install commands use the package name `pluribus-context` and that the binary remains `pluribus`.
+
+## 2. Local checks
+
+Run from the repo root:
+
+```bash
+npm test
+git diff --check
+npm pack --dry-run
+npm publish --dry-run
+```
+
+The dry-run package should include at least:
+
+- `README.md`
+- `LICENSE`
+- `CHANGELOG.md`
+- `bin/pluribus.js`
+- `src/`
+- `docs/`
+- `spec/`
+- `examples/`
+
+## 3. Tarball install smoke
+
+Before publishing, install the exact tarball that `npm pack` creates into a temporary project and run the CLI as a user would. This catches version drift or missing packaged files that unit tests and dry-runs can miss.
+
+```bash
+npm run release:smoke
+```
+
+The script packs the current checkout, installs that tarball into a temporary project, runs `pluribus --version`, `--help`, `init`, `validate`, `sync --dry-run`, and a real `sync`, then checks that generated output includes the package version from `package.json`. It also removes the temporary project and generated tarball on exit.
+
+Expected results:
+
+- `pluribus --version` matches `package.json`.
+- `pluribus --help` shows the same version.
+- generated files mention the same Pluribus version.
+- `validate` and `sync --dry-run` work from the installed package, not the repo checkout.
+
+## 4. Publish
+
+Only publish after npm auth is active and the dry run is clean:
+
+```bash
+npm publish --access public
+```
+
+Then verify:
+
+```bash
+npm view pluribus-context version dist.tarball
+npx pluribus-context --help
+```
+
+## 5. GitHub release
+
+After npm publish succeeds:
+
+- Tag the exact published commit: `vX.Y.Z`.
+- Create a GitHub release using the matching `CHANGELOG.md` section.
+- Link the npm package and the GitHub release from any launch post or reply.
+
+## 6. Post-release monitoring
+
+Within the next work block, check:
+
+- GitHub Actions for the release commit/tag.
+- GitHub issues/notifications.
+- npm package page metadata.
+- Any X/Reddit/Discord replies mentioning install problems.
+
+If install fails or package contents are wrong, do not keep posting. Patch, test, publish a fix version, and document what changed.

package/docs/remote-composable-context-imports.md

@@ -0,0 +1,233 @@
+# Remote Composable Context Imports
+
+Status: remote MVP implemented for explicit `github:`/`https://` fetches, lock/cache offline reuse, and optional GitHub auth for private imports. Remaining design work: CI/cache policy ergonomics and deeper structured error context.
+
+## Goals
+
+Remote imports should let teams inherit shared context from GitHub or HTTPS without making Pluribus non-deterministic, credential-leaky, or unsafe in CI.
+
+The design principle is the same as local imports: explicit context inheritance, expanded before project-local context, with local sections still winning.
+
+## Syntax
+
+Keep the existing directive form:
+
+```markdown
+# @import <spec>
+```
+
+Add remote specs:
+
+```markdown
+# @import github:owner/repo/path/to/context.md
+# @import github:owner/repo/path/to/context.md@ref
+# @import https://example.com/context.md
+```
+
+For GitHub imports, `@ref` should support a branch, tag, or commit SHA. Pinned refs are recommended; floating default-branch imports should warn in local/dev use and fail in CI unless explicitly refreshed.
+
+If a GitHub path includes `@`, parse the ref from the rightmost `@`.
+
+## Resolution semantics
+
+- Preserve the current expansion order: imported content expands before the importing file's local content.
+- Preserve current duplicate-section behavior: later local sections override earlier imported sections.
+- Remote files may contain nested imports, but they must obey the same max depth and safety rules.
+- Relative imports inside a GitHub file resolve relative to that file path in the same repo/ref.
+- Relative imports inside arbitrary HTTPS files are a non-goal for the first remote MVP.
+- Keep the existing max import depth of `5` unless there is strong evidence to change it.
+
+## Auth
+
+- Public GitHub and HTTPS imports work without auth.
+- Private GitHub imports may use existing credentials only during `pluribus sync --update-imports`.
+- Credential lookup order: `GH_TOKEN`, then `GITHUB_TOKEN`, then an existing GitHub CLI login via `gh auth token`.
+- Do not support inline tokens, token CLI flags, lockfile/cache auth metadata, or arbitrary custom headers in the MVP.
+- Do not store tokens in `pluribus.lock.json` or `.pluribus/cache/remote/`; the lockfile is safe to commit and the cache is local/regenerable.
+- Error messages must redact credentials, credential-bearing URLs, and known token values.
+
+## Lockfile and cache
+
+Add a project lockfile:
+
+```text
+pluribus.lock.json
+```
+
+Each locked remote import should include:
+
+- normalized import spec
+- resolved source URL or GitHub API target
+- resolved immutable commit SHA when available
+- SHA-256 content digest
+- byte size
+- fetched timestamp
+- content type
+
+Cache downloaded content by digest, for example:
+
+```text
+.pluribus/cache/remote/<sha256>.md
+```
+
+Default `pluribus sync` should prefer the lockfile/cache for deterministic runs. Network refresh should require an explicit flag such as:
+
+```bash
+pluribus sync --update-imports
+```
+
+## Deterministic CI
+
+CI/non-interactive runs should be deterministic by default:
+
+- fail if a remote import is unlocked
+- fail if required cached content is missing
+- fail if an import uses a floating GitHub ref without an explicit update mode
+- fail on digest mismatch
+- avoid network unless explicitly enabled
+
+Recommended workflow:
+
+1. Developer runs `pluribus sync --update-imports`.
+2. Pluribus writes or updates `pluribus.lock.json` and cache entries.
+3. Developer commits the lockfile.
+4. CI runs `pluribus sync --dry-run` without fetching remote content.
+
+## Network and content limits
+
+Defaults for the MVP:
+
+- HTTPS only; continue rejecting `http://`
+- 5s per-request timeout
+- 15s total remote resolution budget
+- 256 KiB max per remote file
+- 1 MiB max merged remote content
+- max 3 redirects
+- redirects must stay on `https://`
+- UTF-8 Markdown text only
+- reject binary or non-UTF-8 content
+- strip UTF-8 BOM before parsing, matching local import behavior
+
+## Supply-chain safety
+
+- Never execute imported content.
+- Never shell out based on imported content or import specs; the only subprocess is the fixed optional `gh auth token` credential lookup when env tokens are absent.
+- Never support post-processing hooks.
+- Require digest pinning for deterministic use.
+- Fail hard on lockfile digest mismatch.
+- Do not allow remote imports to resolve into local filesystem paths.
+- Treat remote imports as data, not configuration authority.
+
+## Error model
+
+Keep the current clear failure style from `resolveImports`, but add structured internal error codes for tests and callers:
+
+- `REMOTE_IMPORT_TIMEOUT`
+- `REMOTE_IMPORT_TOO_LARGE`
+- `REMOTE_IMPORT_AUTH_REQUIRED`
+- `REMOTE_IMPORT_LOCK_MISSING`
+- `REMOTE_IMPORT_DIGEST_MISMATCH`
+- `REMOTE_IMPORT_UNSAFE_REDIRECT`
+- `REMOTE_IMPORT_UNSUPPORTED_CONTENT`
+
+User-facing errors should include:
+
+- import spec
+- importing file
+- import chain
+- concise cause
+
+They should never include auth headers, tokens, credential-bearing URLs, or remote body content.
+
+## MVP scope
+
+Shipped in the first remote MVP:
+
+- `github:owner/repo/path.md[@ref]`
+- direct `https://...` Markdown/text files
+- unauthenticated public imports
+- optional private GitHub imports via `GH_TOKEN`/`GITHUB_TOKEN` or logged-in `gh`
+- explicit `pluribus sync --update-imports` network access
+- lockfile generation/update and cache by SHA-256 digest
+- deterministic offline lock/cache reuse with digest verification
+- timeout, redirect, content-type, UTF-8, per-file size, and merged-size guards
+- credential-bearing URL rejection/redaction
+- nested GitHub imports within the same repo/ref
+
+Still pending for the hardening phase:
+
+- CI/cache policy ergonomics
+- immutable GitHub commit resolution metadata
+- richer import-chain context in structured errors
+
+Non-goals:
+
+- `http://`
+- GitLab/Bitbucket shorthand
+- arbitrary request headers
+- remote directory imports or globs
+- executable imports or hooks
+- automatic dependency updates
+- relative imports from arbitrary HTTPS documents
+- silent network access in deterministic CI mode
+
+## Implementation shape
+
+Current implementation keeps `resolveImports(sourcePath, options)` as the synchronous local-only entry point and adds `resolveImportsAsync(sourcePath, { allowRemote })` for explicit remote resolution:
+
+- local resolver: existing filesystem behavior
+- GitHub resolver: normalize `github:` specs and fetch raw content, optionally with existing GitHub auth
+- HTTPS resolver: fetch Markdown/text with timeout and size guards
+- lock/cache module: read/write `pluribus.lock.json`, verify digest, read/write cached blobs
+
+Potential options:
+
+```js
+resolveImports(sourcePath, {
+  allowRemote: false,
+  updateImports: false,
+  offline: false,
+  lockfilePath: 'pluribus.lock.json',
+  cacheDir: '.pluribus/cache/remote',
+  timeoutMs: 5000,
+  maxRemoteBytes: 256 * 1024,
+  maxMergedRemoteBytes: 1024 * 1024,
+})
+```
+
+CLI flag shipped: `pluribus sync --update-imports` enables remote network fetches. Without that flag, remote directives fail clearly instead of doing silent network access.
+
+## Test checklist
+
+- [x] parses `github:` imports with `@ref`
+- [x] rejects `http://`
+- [x] redacts auth in errors
+- [x] enforces timeout
+- [x] enforces per-file and merged-size limits
+- [x] rejects unsafe redirects
+- [x] writes deterministic lockfile entries
+- [x] reads from lock/cache without network in CI/offline mode
+- [x] fails on missing lock entry in CI/offline mode
+- [x] fails on digest mismatch
+- [x] supports nested GitHub imports within the same repo/ref
+- [x] rejects unsupported HTTPS-relative nested imports
+- [x] preserves local override behavior after remote expansion
+
+## Suggested issue #9 checklist
+
+```markdown
+Next phase for #9: harden remote composable context imports.
+
+- [x] Specify remote syntax: `github:owner/repo/path.md[@ref]` and `https://...`.
+- [x] Preserve local MVP merge behavior: imports expand before local content; local duplicate sections win.
+- [x] Add `pluribus.lock.json` design with SHA-256 digest, size, fetched timestamp, and content type. Resolved commit metadata remains pending.
+- [x] Add cache design around the explicit `--update-imports` refresh flow.
+- [x] Define CI/offline behavior: fail on unlocked/cache-missing imports unless explicitly updating. Floating ref policy remains pending.
+- [x] Define auth: public unauthenticated fetches plus optional existing `GH_TOKEN`/`GITHUB_TOKEN` or logged-in `gh`; never persist or log secrets.
+- [x] Enforce safety limits: HTTPS only, request timeout, max bytes, redirect limit, UTF-8 Markdown only.
+- [x] Define supply-chain protections: digest verification, hard fail on mismatch, no execution/hooks.
+- [ ] Add structured remote import errors with import-chain context and broader secret redaction.
+- [x] MVP: GitHub + direct HTTPS files only.
+- [x] Non-goals: `http://`, arbitrary headers, GitLab/Bitbucket shorthand, directory/glob imports, HTTPS-relative nested imports.
+- [ ] Add tests for lockfile determinism, digest mismatch, and CI/offline mode.
+```

package/examples/claude-cowork/.cursorrules

@@ -0,0 +1,82 @@
+# Generated by Pluribus 0.1.0 on 2026-03-08 — do not edit manually
+# Source: pluribus.md | Skill: cursor
+# Project: Orbital — Multi-tenant logistics SaaS
+
+## Project Overview
+
+You are assisting the **Orbital** engineering team — 5 backend engineers building a multi-tenant SaaS for logistics operations. TypeScript monorepo using NestJS, PostgreSQL (drizzle-orm), and BullMQ. All engineers use shared conventions.
+
+## Tech Stack
+
+- TypeScript 5.4 (strict mode) + Node.js 22 LTS
+- NestJS 10 with Fastify adapter
+- PostgreSQL 16 via drizzle-orm (NO raw SQL in application code)
+- BullMQ + Redis 7 for job queues
+- Jest 29 + Supertest for testing
+- pnpm workspaces monorepo
+- ESLint flat config + Prettier (2-space, single quotes, trailing commas)
+
+## Code Conventions
+
+- `async/await` only — never `.then()/.catch()`
+- No `any` — use `unknown` with explicit narrowing
+- Named exports only — no default exports, no barrel files
+- File naming: `kebab-case.ts`
+- NestJS pattern: `<feature>.module.ts`, `<feature>.service.ts`, `<feature>.controller.ts`
+- Error handling: always use `AppError` from `packages/core/errors` — never throw plain strings or generic `Error`
+- No circular dependencies (enforced by ESLint)
+- No `@ts-ignore` or `@ts-expect-error`
+
+## Testing
+
+- Unit tests for all service methods with side effects
+- Integration tests for all controller endpoints via Supertest
+- Use test factories from `test/factories/` — never construct objects manually in tests
+- Inject mocks via DI — no module-level `jest.mock()`
+- Test naming: `describe('<Unit>', () => { it('should <behavior> when <condition>', ...) })`
+
+## Pull Requests
+
+- PRs must be < 400 lines (excluding generated files and migrations)
+- Every PR needs at least one test covering the new behavior
+- Migrations must be reviewed by Ana (`@ana/tech-lead`) before merge
+- No self-merging — minimum 1 approval required
+- Fill the PR description template: What, Why, How, Risk, Test plan
+
+## AI Review Rules
+
+When reviewing code:
+- Check for correctness, type safety, and convention violations (not style — Prettier handles that)
+- Flag missing error handling in async paths
+- Flag raw SQL outside drizzle-orm
+- Flag new endpoints without integration tests
+- Flag new endpoints without declared RBAC role
+- Never suggest approving a PR with failing CI
+
+## Constraints (Non-negotiable)
+
+- NO raw SQL — all queries through drizzle-orm schema types
+- NO `any` type — use `unknown` and narrow
+- NO secrets in the repository — ever
+- NO new direct dependencies without an ADR in `docs/adr/`
+- NO bypassing RBAC — every endpoint declares its required role
+- NO modifying migration files after they've been applied to staging or production
+- NO `console.log` in production code — use `packages/core/logger`
+- NO singleton mutable state outside of NestJS module providers
+
+## Goals
+
+- Correctness over speed — a broken feature costs more than a slow one
+- Consistent codebase across all 5 engineers
+- PR cycle time under 24 hours
+- Zero production incidents from merged code
+- Junior team members learn through Claude's explanations, not just receive generated code
+
+## Anti-patterns to Avoid
+
+- Fat controllers: business logic belongs in services
+- Barrel files that re-export everything
+- Data transforms inside schema migration files
+- Returning HTTP 200 for business errors — use proper status codes + `AppError.httpStatus`
+- `console.log` in production paths
+- Optimistic locking without retry loop

package/examples/claude-cowork/pluribus.md

@@ -0,0 +1,137 @@
+# Identity
+
+We are the **Orbital** engineering team — 5 backend engineers building a multi-tenant SaaS platform for logistics operations.
+
+We use Claude Code heavily for code review, pair programming, and greenfield feature work. Claude is treated as a senior team member, not a code autocomplete tool. It attends PR reviews, writes tests, and proposes architectural changes.
+
+**Team:**
+- **Ana (tech lead):** owns architecture decisions, API design, and final approval on schema changes
+- **Bruno:** payment integrations, billing engine
+- **Clara:** logistics domain, route optimization
+- **Diego:** infrastructure, observability, CI/CD
+- **Elena:** frontend (React + TypeScript), design system
+
+All engineers use Claude Code. Shared conventions apply to all AI-assisted work.
+
+# Stack
+
+- **Language:** TypeScript 5.4 (strict mode)
+- **Runtime:** Node.js 22 LTS
+- **Framework:** NestJS 10 (REST API) + Fastify adapter
+- **Database:** PostgreSQL 16 via `drizzle-orm`
+- **Message queue:** BullMQ + Redis 7
+- **Testing:** Jest 29 + Supertest; coverage threshold: 80% on all PRs
+- **Linting:** ESLint flat config (team-shared config in `packages/eslint-config`)
+- **Formatting:** Prettier (2-space indent, single quotes, trailing commas)
+- **Package manager:** pnpm + workspaces monorepo
+- **CI/CD:** GitHub Actions — lint, test, type-check on every PR; deploy to staging on merge to `main`
+- **Auth:** JWT (access) + refresh tokens; role-based access control (RBAC)
+- **Monitoring:** OpenTelemetry → Grafana Cloud
+- **No raw SQL in application code** — all queries through drizzle-orm schema types
+
+# Conventions
+
+## Code
+
+- `async/await` only — no `.then()/.catch()`
+- No class decorators for business logic — NestJS decorators only for DI wiring
+- No `any` — `unknown` with explicit narrowing
+- Error handling: use the shared `AppError` class from `packages/core/errors`; never throw plain strings or generic `Error`
+- Named exports — no default exports, no barrel files unless explicitly discussed
+- File naming: `kebab-case.ts`; NestJS modules follow `<feature>.module.ts`, `<feature>.service.ts` etc.
+- No circular dependencies — enforce with `eslint-plugin-import`
+
+## Testing
+
+- Unit tests for all service methods with side effects
+- Integration tests for all controller endpoints using Supertest
+- Test factories in `test/factories/` — never construct objects manually in tests
+- No `jest.mock()` at module level — use dependency injection and pass mocks through constructor
+- Test descriptions: `describe('<Unit>', () => { it('<should do X when Y>', ...) })`
+
+## Pull Requests
+
+- PRs must be < 400 lines changed (excluding generated files and migrations)
+- Every PR needs at least one test covering the new behavior
+- PR description: fill the template (What, Why, How, Risk, Test plan)
+- Migrations must be reviewed by Ana before merge — tag `@ana/tech-lead` in the PR
+- No self-merging — at least one approval required
+- Draft PRs are welcome for early feedback; mark ready when CI passes
+
+## AI-Assisted Code Review
+
+When Claude is used for PR review:
+- Focus on correctness, type safety, and convention violations — not style (Prettier handles that)
+- Always check for missing error handling in async paths
+- Flag any SQL written outside drizzle-orm types
+- Check that new endpoints have corresponding integration tests
+- Do not approve PRs with failing tests, regardless of context
+
+## Branching
+
+- `main` → production
+- `staging` → staging environment (auto-deploy)
+- Feature branches: `feat/<ticket-id>-<short-description>`
+- Hotfix branches: `hotfix/<ticket-id>-<short-description>`
+- Never commit directly to `main` or `staging`
+
+# Goals
+
+1. Ship reliable features — correctness over speed; a broken feature costs more than a slow one
+2. Maintain a consistent codebase across 5 engineers — conventions enforce shared quality, not personal preference
+3. PR cycle time < 24h — fast reviews unblock the team; slow reviews kill momentum
+4. Zero production incidents from merged code — staging catches what tests miss
+5. Knowledge sharing — Claude should help junior team members learn through its explanations, not just generate code
+
+# Constraints
+
+- Never approve or suggest merging a PR with failing CI
+- Never write raw SQL — always use drizzle-orm schema types and query builder
+- Never commit secrets or environment variables to the repository
+- Do not add direct dependencies without an ADR (Architecture Decision Record) in `docs/adr/`
+- Never bypass RBAC — new endpoints must declare their required role
+- Never modify migration files after they've been applied to staging or production
+- Do not suggest patterns that require `@ts-ignore` or `@ts-expect-error`
+- No singleton state outside of NestJS module providers — no module-level mutable variables
+
+# Workflow
+
+## Feature Development
+
+1. Pick ticket from the sprint board
+2. Create feature branch: `feat/<ticket-id>-<description>`
+3. Write tests first for complex domain logic (TDD preferred in logistics domain)
+4. Open PR as Draft early — tag relevant reviewers
+5. When CI passes → mark PR as Ready for Review
+6. One approval + all checks green → merge to `main`
+7. Monitor staging deploy; check observability dashboard
+
+## Code Review Checklist
+
+When reviewing (human or AI-assisted):
+
+- [ ] Does it have tests covering the new behavior?
+- [ ] Are errors handled correctly (using `AppError`)?
+- [ ] Is the TypeScript type coverage complete (no `any`)?
+- [ ] Are there any raw SQL queries?
+- [ ] Does it respect RBAC for new endpoints?
+- [ ] Is the PR < 400 lines?
+- [ ] Is the PR description filled out?
+- [ ] Are new dependencies justified?
+
+## ADR Process
+
+Any new library, architectural pattern, or significant deviation from convention requires an ADR:
+- File: `docs/adr/YYYY-MM-DD-<slug>.md`
+- Sections: Context, Decision, Alternatives considered, Consequences
+- Reviewed asynchronously; Ana signs off on architectural ADRs
+
+# Anti-patterns
+
+- **Fat controllers:** Business logic belongs in services, not in NestJS controllers
+- **Barrel files that re-export everything:** They make refactoring hard and break tree-shaking
+- **Test isolation via `jest.clearAllMocks()` in `afterEach`:** Use proper DI and scoped mocks instead
+- **Migrations with data transforms:** Schema changes and data migrations are separate PRs
+- **Optimistic locking without retries:** If you use `version` columns for optimistic concurrency, you must handle the retry loop
+- **`console.log` in production code:** Use the shared `logger` from `packages/core/logger`
+- **Returning 200 for business errors:** Use proper HTTP status codes + `AppError` with `httpStatus` field