omnesis-review · git:20261104.8d35018 · 2026-11-04 · sha256 0e7bb6682bb0f4d3
omnesis-review git:20261104.8d35018A
Immutable. This exact content never changes and is served at /api/v1/blob/0e7bb6682bb0f4d3.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_k67zuvnltfrhjl2k/0e7bb6682bb0f4d3dcb43ef9a2ef6ac7d2548a1a9e3c40f9b4578939d5673147.json
Then /plugin install omnesis-review@markdownregistry-k67zuvnltfrhjl2k in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: omnesis-review description: Audit Omnesis changes for architecture, correctness, security, privacy, tests, and documentation. Use for a repository review or the required implementation self-review. --- Audit all code changed in this session — committed, staged, unstaged, and new files — unless the user's accompanying instructions narrow the scope. Only apply checks relevant to those changes. Determine the review base from the requested scope; for a feature branch use `git diff main...HEAD`, then inspect `git diff`, `git diff --cached`, and `git ls-files --others --exclude-standard` to include uncommitted work. Do not infer scope from the number of commits made today. When delegation is available and permitted, use the host agent's sub-agent tools to split relevant checks in parallel. Pass each reviewer the exact file list, review base, and role. Otherwise, work through the full checklist yourself; record any checks you cannot perform. --- ## Checks ### Design and architecture - **Elegance.** Are the abstractions well-considered, or does the code feel like duct tape? Would a staff engineer approve this design? - **Source encapsulation.** No source-specific logic (branching on a source name, unit nouns, icons, URL handling, display strings) outside that source's provider package. The `defineSource()` descriptor is the contract — extend it rather than hardcoding downstream. Generic abstractions (registry iteration, `:sourceType` routing) are fine. - **Routes only call services.** HTTP route handlers are thin adapters: parse, call a domain service, map the result. No direct imports of repositories, the writer queue, or the scheduler in route files. - **assertNever exhaustiveness.** Every switch on an internal discriminated union ends with `default: assertNever(x)`. External-data switches use typed defaults instead. - **Facade pattern.** If a module grew past ~600 LOC or gained unrelated responsibilities, was it split into focused collaborators behind a thin facade? Check against `docs/conventions.md` for the canonical examples. ### Correctness - **Edge cases.** Does the code handle all realistic edge cases? If covering an edge case would add disproportionate complexity, flag it for discussion rather than silently fixing. - **Concurrency.** Check for race conditions, ABA problems, TOCTOU bugs, and stale-read hazards — not just in background jobs but anywhere concurrent access is possible (writer queue, sync engine, scheduler). - **Background jobs.** If new or modified: (a) is the algorithm correct under concurrent execution? (b) could it starve lower-latency work like agent or user requests? Watch for writer-queue contention. - **What does this cost the writer?** Ask it of every change that touches a writer path. Does it do a lookup inside a writer transaction — resolution, a membership test, anything that reads — where the read could happen on the io handle and be passed in? Does it iterate without committing in sub-batches and checking the preempt token between them, so one oversized input holds the write lock for as long as that input is large? See `docs/conventions.md` § "The writer is one thread". - **Does this change what a consumer assumed?** A producer — a new source, a normalizer emitting more links or people per item, a route ingesting a new shape — can be correct in itself and still break a consumer whose cost model assumed the old volume. If the change alters how much of anything is produced per item, name the consumers of that data and say what the new volume costs them. The defects this question exists to catch were all of this form: each piece locally reasonable, nobody owning the interaction. ### Security and privacy - **Security.** No command injection, XSS, SQL injection, path traversal, or other OWASP top 10 vulnerabilities. Validate at system boundaries (user input, external APIs, HTTP bodies). - **Privacy (corpus data).** No real _indexed_ user data — names, emails, phone numbers, addresses, vendors, personal context from the user's corpus — in fixtures, test inputs, examples, comments, commit messages, or anywhere else in the codebase. Invent all example data from scratch per the rules in CLAUDE.md. (Operator/machine setup leakage is covered under _Open-source hygiene_ below.) ### Open-source hygiene This is a public repository. Beyond "is this good code," every change must be safe to be public. - **Operator & infra leakage.** No operator- or machine-specific detail in committed (non-gitignored) files: machine names, tailnet/LAN IPs, hostnames, live-service control (tmux panes, ports as infrastructure), local model endpoints, or internal tooling names. These belong only in `CLAUDE.local.md` (gitignored) — never in `AGENTS.md`, source, or public docs. The `scripts/pii-scan.mjs` guard enforces the specific identifiers; confirm it passes. - **Non-public references.** No links or references to issue trackers, repos, dashboards, or resources a public contributor cannot access — inline the rationale instead. Never use a bare `#NNN` to reference a non-public issue; it collides with this repository's own public issue numbers. - **CI supply-chain & fork safety.** Every `.github/workflows/` job runs on a GitHub-hosted runner; a self-hosted label is a finding (a fork PR could run arbitrary code on a physical machine). Pin new third-party actions to a full commit SHA. Never expose secrets to `pull_request` / `pull_request_target` from forks. - **License & third-party attribution.** New source files carry the SPDX header. Vendored or third-party code must NOT be stamped with the project's AGPL/copyright header, must keep its upstream license notice, and must be listed in `THIRD_PARTY_NOTICES.md`. New bundled brand assets (icons, fonts, logos) need a `TRADEMARKS.md` entry and correct attribution. ### Code hygiene - **Dead code.** Did the changes leave behind unused imports, functions, types, variables, or files? Delete them. - **TypeScript strictness.** No `any` except in test mocks. No `console.log/warn/error` — use the structured logger (`createLogger`). Imports use `.js` extensions. No cross-package relative imports (use `@omnesis/core`, `@omnesis/types`, etc.). - **Logger conventions.** Logger components follow the hierarchy (`gateway`, `gateway:http`, `provider:google`, etc.). Messages are concise one-liner template literals, not structured-data objects. - **Zod at boundaries.** HTTP route bodies are validated via per-route zod schemas. Branded ID constructors (`SourceId()`, `ProviderId()`, etc.) validate input — no `as SourceId` casts on untrusted data. - **Configurable tunables.** Did the changes introduce magic numbers or hardcoded thresholds that should live in `omnesisConfigSchema` (`packages/config/src/config-schema.ts`)? If a value is likely to be tuned by future agents or the user, expose it through the config schema. Flag uncertain cases for discussion. - **Comment quality.** Comments describe the code as it exists now, for a reader with no prior context. No references to prior versions, refactors, recent changes, or session-specific context. No "we changed X from A to B" — just explain B. Test: would a stranger opening the file a year from now understand this comment without access to the conversation or git history? ### Testing - **Coverage.** Every new feature and bug fix includes tests. New sources need sync (bootstrap + incremental), normalization, and error-handling tests. Tests use vitest, placed next to source files as `*.test.ts`. - **Test quality.** Tests exercise meaningful behavior, not implementation details. No tests that assert junk or merely prove the mock works. Edge cases and error paths are covered, not just the happy path. ### Documentation - **Public docs.** If user-visible behavior changed (defaults, types, HTTP endpoints, CLI commands, source semantics, error states, new or removed features), check `website/docs/` for affected pages and update them. Use the anchoring table in CLAUDE.md to find the right page. Don't add docs for every internal detail — maintain a consistent level of detail. - **CLAUDE.md / README accuracy.** Did the changes make any rules or descriptions in CLAUDE.md or README.md stale? If so, update them. - **GitHub issues in code.** If GitHub issues were created this session, are they referenced at the relevant call sites with a short comment (`// See #NNN — ...`)? This helps future agents discover tracked work without searching GitHub. Skip this for large-feature tracking issues. ### Agent protocol (only if changed) - **Synthetic conversations.** If tool specs, transcript storage, or tool inventory changed: are the synthetic conversations in the active universe updated to reflect the new protocol? New tools need a scenario exercising them; removed or modified tools need existing scenarios updated. Synthetic conversations must be grounded in real documents from the synthetic corpus. ### iOS (only if views changed) - **SwiftUI previews.** Are there enough previews for added or modified views? Do the previews cover all meaningful state combinations (empty, loading, error, populated, edge cases)? This is the agent feedback loop — without it, layout verification requires human testing. --- ## Execution rules - If delegating, determine the split based on the scope of changes. Each sub-agent gets a clear role and the list of files to review. - After collecting findings, fix all issues directly — don't just list them. Pause and ask for the user's opinion only when a fix involves a judgment call (e.g. disproportionate complexity for an edge case, whether a tunable belongs in config). - Fix forward on the current branch unless otherwise specified. - Ensure tests pass after all fixes. Add tests for the fixes themselves when applicable. - Run `npm run typecheck` after all changes to catch any type errors introduced by the fixes.