Ref Ingest

ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. ref-ingest v1.0 — recent: initial version. Then proceed.

The one operation every input funnels through for a reference scope: incoming info → resolve → reconcile → upsert. It grows the manual single-upsert manage-reference-data with the two load-bearing hard parts — entity resolution (is this new "Reply" the existing Reply.io?) and reconciliation (new fact contradicts old → overwrite / supersede-with-history / flag) — plus the automation split by scope.

Read first (authoritative — this skill enforces, does not restate):

• resources/layered-brains/COMPANY-BRAIN-SCHEMA.md → "The update model", "The two axes" (sub-scope routing + type:/relationship: enums), "Automation boundary — split by scope".
• resources/layered-brains/REFERENCE-SCOPE-SCHEMA.md → the reference-kind frontmatter contract.
• .claude/skills/manage-reference-data/SKILL.md → the seed upsert (Step 0 scope check + the frontmatter template). This skill is its richer successor; it does not duplicate the contract.

Composes

• /ref-supersede — when reconciliation finds a validity transition that needs a prior snapshot (contract renewal, role/price change), hand off instead of overwriting. Never invoked on the market/autonomous branch (see the invariant).

State Dependencies

The automation split (load-bearing)

Invariant (what makes any autonomous caller safe): the market/ branch is overwrite-only — it never opens an approval gate and never calls /ref-supersede. A validity transition in market/ that would need a snapshot is flagged for a human ref-supersede, not auto-run. So a scheduled caller (e.g. ref-refresh, or domain-watch in 9e) that routes market items here always takes a gate-free path.

Process

Step 1 — Resolve the scope + confirm reference-kind

cd resources/local-brain-search
SCOPE="${scope:-Company}"
./venv/bin/python - "$SCOPE" <<'PY'
import sys, memory_config as mc
f = sys.argv[1]
print("kind:", mc.scope_kind(f), "| is_reference:", mc.is_reference_scope(f))
PY

If is_reference is False → stop (this skill only writes reference scopes). See the schema doc's "Adding a new reference scope".

Step 2 — Extract candidate entity facts

From the incoming info (the user in conversation · a document/contract/deck/call · a domain-watch market signal · another agent's report), pull the atomic facts about one real-world entity: display name + aliases, type:, the relation to us (relationship:), body facts, and any term-bearing fact (a contract window, a role start, a price effective date).

Step 3 — Route to the sub-scope (watch vs transact)

Apply the partition rule from COMPANY-BRAIN-SCHEMA "The two axes":

• an entity you watch (competitor, competitor product, ecosystem player) → market/
• an entity you own or transact with (self, client, prospect, partner, vendor, your offering, internal agent, a deal) → people/ orgs/ products/ engagements/ by type:. The internal agent workforce (type: agent) lives in products/ alongside own products — there is no separate agents/ sub-scope.
• type:/relationship: values MUST come from the schema doc's enum (person·organization·product·agent·engagement·interaction × the relationship axis). Never invent a value.

Step 4 — ENTITY RESOLUTION (never duplicate)

Find the one canonical note this fact belongs to before writing:

# semantic: does an entity like this already exist in the family?
BRAIN_READ_SCOPE=core,Company resources/local-brain-search/run_search.sh "<entity name + a distinctive fact>" --limit 8 --json
# exact/alias: title + body match
grep -rilE "<name>|<alias1>|<alias2>" Brain/Company/

• Match found → this is an update to that note. Use its exact path.
• Ambiguous (2+ plausible matches, e.g. "Reply" vs "Reply.io") → present the candidates and ask which entity this is (AskUserQuestion); do NOT guess a new note into existence.
• No match → genuinely new entity → add.

Step 5 — RECONCILIATION (new fact vs old)

Compare the incoming fact to the note's current body:

Step 6 — Automation gate + upsert

• market/ → proceed (no gate). CRM sub-scopes → show the before/after diff and get explicit approval (AskUserQuestion) before writing.
• Write the note with the reference frontmatter contract (copy the template from manage-reference-data Step 2 — do not restate it here). On update: overwrite the body (current truth), preserve created/created_by, re-stamp as_of + updated to today, bump updated_by to your model. Append a ## Change Log line:

  ## Change Log
  - 2026-07-08 — <what changed> (source: <where it came from>)

• Going forward only: for a term-bearing fact, add valid_from:/valid_until:. Do NOT backfill these onto notes that lack them — incremental adoption.

Step 7 — Reindex (unless deferred)

cd resources/local-brain-search && ./run_index.sh && ./run_daemon.sh restart   # daemon on :7437, RESTART not reload

Content-hash detection → a changed note triggers a full FAISS rebuild (minutes). Reference notes are BDG-excluded, so no run_brain_graph.sh bootstrap is needed. If invoked with --no-reindex (batch mode, e.g. by ref-refresh over many market items), skip this step and let the batch caller reindex once at the end.

Verification

• Round-trip: after an add/overwrite + reindex, the entity surfaces under a mount and is absent unmounted:

  BRAIN_READ_SCOPE=core,Company resources/local-brain-search/run_search.sh "<entity>" --limit 5 --json   # present
  resources/local-brain-search/run_search.sh "<entity>" --limit 5 --json                                  # absent (core default)

• Learn-gate held: md5 resources/local-brain-search/data/q_values.json is byte-identical before and after (a mounted read trains nothing).
• Audit trail: the note has a new ## Change Log line; the body is the current truth (no append-only drift); as_of = today.
• No duplicate: exactly one note exists for the entity (grep -ril "<name>" Brain/Company/ returns one canonical file).

This skill must refuse to

• Write into a non-reference / core / cognitive folder, or set any provenance but reference.
• Create a duplicate entity note when resolution finds (or is unsure of) an existing one.
• Auto-supersede or gate-skip on a CRM sub-scope, or run /ref-supersede on the market/ branch.
• Crystallize, lifecycle-classify, synthesis-pulse, or promote a record into an endorsed cognitive insight — that crossing stays the human encountered → endorsed act.