Entity Review

entity-review

A diff-scoped, vision-aware reviewer for EntityStore corpora. It answers one question well: "Do the entities this branch/PR pushes stay valid against the latest schema AND on-track with the brain's design philosophy?"

It is the codified, repeatable version of the manual review done on company-brain PR #8 (the vessel/captain/navigation backfill).

Prerequisites

• Python 3.10+ with jsonschema (pip install jsonschema).
• git (and gh only if you pass --pr).
• The entitystore engine skill (sibling dir) for cb_engine.load_corpus / wiki_audit. Auto-detected; the reviewer degrades to a glob if absent.

When to use

• Reviewing a company-brain PR or branch that adds/changes entity JSON.
• Gating a scribe / backfill output before merge (HubSpot, Notion, Gmail…).
• A pre-merge / CI check on entity changes.

Do NOT use for code review, schema authoring, or non-entity JSON.

Design stance (why it exists)

cb_engine.wiki_audit already audits the whole corpus (contradictions, dead links, freshness, orphans, schema-invalid). This skill is different on two axes:

1. Diff-scoped — it reviews only the entities a change pushes, so a 2-file PR gets a 2-file review, not a 2,593-entity dump.
2. Vision-aware — it enforces the design philosophy that a JSON-schema cannot express on its own. Crucially, the guardrails are sourced from the schema's own PROHIBITED FIELDS: annotations wherever possible, so the reviewer stays schema-agnostic and never drifts from the schema of record.

How to run

python scripts/review_entities.py \
  --repo   /path/to/company-brain \
  --corpus corpora/syroco-commercial \
  --base   feat/hubspot-vessel-backfill \   # what to diff against (default: origin/main)
  --head   HEAD                              # the pushed state (default: HEAD)
# or review a GitHub PR directly:
python scripts/review_entities.py --repo /path/to/company-brain --pr 8
# or an explicit file list:
python scripts/review_entities.py --repo /path/to/company-brain --files a.json b.json

• --schema defaults to <corpus>/../../schemas/entity.schema.json (the latest / canonical schema). The reviewer always validates against that file — i.e. the latest schema version by definition.
• Reuses the entitystore engine in place (cb_engine.load_corpus, wiki_audit); point --engine at its scripts/ dir if not auto-found.
• Exit code 1 if any ERROR-severity finding, else 0 — CI-ready.

The checks (what "on track with the vision" means)

Severity: ERROR blocks merge · WARN needs a human call · INFO is a nudge.

Output

A markdown review: a verdict line, a one-line summary (files by status), then findings grouped by severity as file → check → message. Mirrors the PR #8 review format so it reads the same whether a human or this skill produced it. Example (company-brain PR #8):

# entity-review — 🟡 APPROVE WITH COMMENTS

Schema: **v5** · reviewed **2347** entities (+2345 new, ~2 modified, -0 deleted)
Findings: **0 ERROR · 1 WARN · 1 INFO**

## 🟡 WARN (1)
- `(push)` — **C7 lazy-materialization**: 1854 added navigation anchors are ALL
  orphan (no inbound ref) — anchors should materialize lazily, not one node per voyage

## ⚪ INFO (1)
- `(push)` — **C7 role-boundary**: 1854 navigation anchors from ONE extractor —
  confirm this is a system-of-record scribe, not an enricher mirroring another source

Extending

New vision rules go in scripts/review_entities.py as a check_* function returning Findings. Prefer sourcing the rule from the schema (a new PROHIBITED: / annotation convention) over hardcoding, to keep the engine schema-agnostic. Record any cross-cutting decision in company-brain/docs/proposals/ and reference it in the check's message so a flagged author can find the rationale.

Source: VictorGjn/agent-skills — distributed by TomeVault.