---
name: profile-gap-policy-sample
version: 1.0.0
description: >
  Example soul_engine/profile_gap hook. Suppresses profile-gap questions for fields
  already present in Chroma user_facts or in a custom operator notes file. Copy this
  into $FUROSHIKI_DATA/plugins/ and adapt the suppression logic to your source of truth.
author: user
active: false
hooks:
  - type: soul_engine
    target: profile_gap
    entry: scripts/hook.py
    timeout: 8
    priority: 40
    description: "Veto profile-gap fields already answered in user_facts or operator notes"
permissions:
  read_user_facts: true
  output_mind_queue: false
  llm: false
  network: false
  openrouter_web: false
---

# Profile-gap policy sample

Demonstrates the `soul_engine / profile_gap` hook introduced in V2.

## What it does

On every soul_engine tick where `user_profile_gaps.json` has candidate fields to enqueue,
this hook runs once with the full candidate list. It checks each field against two sources:

1. **Chroma `user_facts`** — semantic search; confidence ≥ 0.35 → suppress.
2. **`$FUROSHIKI_DATA/plugins/profile-gap-policy-sample/data/known_fields.json`** — a
   simple JSON object `{"name": true, "location": true, ...}` that operators can maintain
   manually (e.g. seeded from an external CRM or notes app).

Fields suppressed by either source are returned in `suppress_fields`; soul_engine skips
them and they will not become `ask_user` self_questions this tick.

## Setup

```bash
# Copy into your instance plugins folder
cp -r examples/plugins/profile-gap-policy-sample ~/.furoshiki/plugins/

# Edit the manifest to set active: true
nano ~/.furoshiki/plugins/profile-gap-policy-sample/PLUGIN.md

# Optionally seed the known_fields file
mkdir -p ~/.furoshiki/plugins/profile-gap-policy-sample/data
echo '{"name": true, "location": true}' > \
  ~/.furoshiki/plugins/profile-gap-policy-sample/data/known_fields.json

# Reload plugins so brain picks up the hook
furoshiki plugins reload
```

## Extending this

- Replace the `known_fields.json` check with a call to your CRM / notes API.
- Add `network: true` and `llm: true` to permissions if you need outbound calls.
- Return `reason` in the JSON output for better log observability.
