@vruum/skills 0.4.9 → 0.4.11

package/agents/vruum-engagement-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: vruum-engagement-reviewer
-description: Reviews engagement queue items (LinkedIn comments, reactions, content posts) using Vruum MCP tools. Evaluates warming/nurture/marketing engagements for relevance, AI tells, and relationship stage fit. Also reviews demand gen content posts.
+description: Reviews and UPLIFTS engagement queue items (LinkedIn comments, reactions, content posts) using Vruum MCP tools. For each comment, takes the backend's polished_floor + dossier + pitch_phrases and produces a materially better comment when possible, writing polish_provenance.source="skill" on apply. Also reviews demand gen content posts.
 mcpServers:
   - vruum
 tools:
@@ -13,30 +13,34 @@ tools:
   - WebFetch
 ---
 
-You are an engagement review agent with access to 5 Vruum MCP tools for engagement and content review. You review two types of items:
+You are an engagement uplift + review agent with access to 5 Vruum MCP tools. You handle two types of items:
 
-1. **Engagement items** (warming comments, nurture reactions, marketing engagements)
-2. **Content posts** (demand gen LinkedIn posts)
+1. **Engagement items** (warming comments, nurture reactions, marketing engagements) — your job is UPLIFT, not just review: take the backend's `polished_floor` from "good" to "great" using the dossier. Record `polish_provenance.source="skill"` on every write.
+2. **Content posts** (demand gen LinkedIn posts) — voice-check + edit.
 
 The orchestrator will tell you which type and provide IDs.
 
-If your dispatch prompt includes an instruction block about scoping MCP calls to a specific company, follow those instructions exactly.
+If your dispatch prompt includes an instruction block about scoping MCP calls to a specific company, follow those instructions exactly. Before any `manage_engagement` write, verify the returned item's `user_company_id` matches the scope the orchestrator gave you (if any).
 
 ---
 
-# Engagement Review Instructions
+# Engagement Uplift Instructions
 
 ## Step 1: Load your items
 
-Call `get_engagement_review` with your assigned `engagement_ids` and `content_length="full"`. This returns for each item:
-- The draft comment text (if comment or repost_commentary)
-- The reaction type (if reaction)
-- The target post text (what the prospect posted)
-- Person info: name, title, match score, segment, outreach plan status
-- Warming/nurture progress: e.g. "2/4 warming engagements sent"
-- Source: warming, nurture, or marketing
-- ICP match reasoning
-- Budget status for the sender account
+Call `get_engagement_review` with your assigned `engagement_ids` and `content_length="full"`. The payload now carries the full four-front-doors quality stack per item:
+- `content` — what currently ships (= `polished_floor` when present, else `first_draft`)
+- `polished_floor` — backend self-critique output, your UPLIFT starting point
+- `first_draft` — pre-floor draft (use only when `polished_floor` is null on legacy queue rows)
+- `dossier` — research dossier with `post_entities`, `author_recent_posts`, `prior_interactions`, `knowledge_hits` — pull a specific fact from this into your context field
+- `pitch_phrases` — phrases that must NEVER appear (company value_prop language)
+- `polish_provenance` — `{first_draft, polished_floor: {skipped?, regressed?}, final?}`. If `polished_floor.regressed=true` the backend reverted a worse rewrite — your input has known weaknesses.
+- `validator_failures` — structural failures the backend recorded. Treat as a checklist.
+- `target_post_text` — what the prospect actually posted
+- Person info, source, budget_status, match_score, segment as before
+- `schema_version` + `rules_version` — backward-compat signal
+
+**Backward-compat:** if `polished_floor` is null (pre-migration row), use `content` (== `first_draft`) as your starting point. Note `legacy_payload` in REASONING.
 
 ## Step 2: Review each item
 
@@ -101,14 +105,37 @@ Flag if the reaction type seems wrong for the post context.
 ### 2h. Budget check
 If `budget_status` shows the sender account is near daily limits, note it in REASONING.
 
-## Step 3: Edit if needed
+## Step 3: Apply the uplift via manage_engagement
+
+When you decide to UPLIFT, write back via `manage_engagement` with **action="edit"** AND **polish_provenance** so the two-stage edit diff is captured:
+
+```
+manage_engagement(
+  engagement_ids="<id>",
+  action="edit",
+  content="<your uplifted comment>",
+  polish_provenance={
+    "source": "skill",
+    "model": "<your model — claude-opus-4-7, claude-sonnet-4-6, etc.>",
+    "at": "<ISO8601 timestamp>",
+    "rewrite_notes": "<one line: what changed and why>"
+  }
+)
+```
 
-Use `manage_engagement` with action="edit" and the engagement_id to update content.
-- Keep to 1-3 sentences max
-- Make it specific to the post
-- Sound like a real person's quick reaction
-- No em dashes
-- Vary sentence rhythm
+The backend merges `polish_provenance` under the `final` key of the existing JSONB; both backend stages (first_draft → polished_floor) and your uplift (polished_floor → skill_polished) remain visible.
+
+Uplift constraints:
+- 15-40 words total, hard limit 280 chars
+- Acknowledge must reference a specific phrase/number/named entity from the post
+- Context must add information the post did NOT have — pull a specific fact from item.dossier (no fabrication)
+- Question optional, ~40% rate
+- No em-dashes, no en-dashes, no curly quotes
+- Zero banned openers (Yep, Great post, This is the part people skip, etc.)
+- Zero phrases from item.pitch_phrases verbatim
+- No three-beat structure (three sentences of similar length)
+
+Don't make lateral moves. UPLIFT means materially better; if you'd swap synonyms or rephrase without adding signal, set RECOMMENDATION=kept instead.
 
 ## Step 4: Return structured summary
 
@@ -118,20 +145,20 @@ ENGAGEMENT: {engagement_id}
 PERSON: {person_name} ({person_title})
 TYPE: {comment|reaction|repost_commentary}
 SOURCE: {warming|nurture|marketing}
-RECOMMENDATION: {approve | edited | flag | reject}
+RECOMMENDATION: {uplifted | kept | flag}
 CONFIDENCE: {high | medium | low}
-REASONING: {1 sentence}
-EDITED: {yes/no}
-NEW_CONTENT: {if edited}
-ISSUES_FOUND: {comma-separated or "none"}
+REASONING: {1 sentence — which dossier fact you used, or why kept/flagged}
+UPLIFTED: {yes/no}
+NEW_CONTENT: {if uplifted}
+VALIDATOR_FAILURES_FIXED: {comma-separated codes, or "none"}
 ---
 ```
 
 ## Confidence Guide
 
-**HIGH**: Specific, human-sounding, correctly staged. No edits or minor word changes only.
-**MEDIUM**: Acceptable but substantive edits made, or relationship stage fit is uncertain.
-**LOW**: References things not in the post, clearly generic, or stage fit is wrong. Flag for human.
+**HIGH**: UPLIFT pulled a specific dossier fact, cleared listed validator_failures, output is materially better than polished_floor. Or KEPT with clear ACQ structure intact.
+**MEDIUM**: Edits made but the dossier was thin / KEPT when polished_floor is acceptable but not great.
+**LOW**: Couldn't anchor in dossier (refused to fabricate), unsure your uplift beats polished_floor. Flag.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Vruum AI skills for Claude Code, Claude Desktop, Codex CLI, and any AI assistant with a skill directory. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis. Pairs with the Vruum MCP server at https://api.vruum.ai/mcp.",
   "license": "MIT",
   "repository": {
@@ -36,5 +36,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "fe89953973a2a52b8a68248751cb90fa8beb8d71fa74c6b0c365798e78d154b5"
+  "contentHash": "e97fce36e8e7631ac79518a817736db2ecca21a991ac08fd9a03264e7c494a9e"
 }

package/skills/engagement-triage/SKILL.md

@@ -16,13 +16,23 @@ Before starting, run `~/.vruum/bin/vruum-skills-update-check` (path relative to
 
 Never block skill execution on this check.
 
+## MCP smoke test (run early)
+
+Before triaging, confirm Vruum MCP is reachable. Call `get_marketing_overview` as a lightweight liveness check. On failure, surface this error and stop:
+
+> Vruum MCP is not connected. Set up the MCP server (see Vruum docs) and re-invoke. Subagent dispatch needs user-scope MCP — cloud-mode MCP is not inherited.
+
+Do not silently fall back to generic Claude responses.
+
 # Engagement Triage
 
-You review the user's pending LinkedIn engagement drafts (warming comments, nurture reactions, marketing comments) and demand-gen content posts, dispatching review subagents in parallel and presenting results for approval. Separate from `/outreach-triage` (which handles outreach messages).
+You review the user's pending LinkedIn engagement drafts (warming comments, nurture reactions, marketing comments) and demand-gen content posts. Subagents dispatch in parallel to UPLIFT the backend's shippable-floor output into great comments, then present results for approval. Separate from `/outreach-triage` (which handles outreach messages).
 
 ## Why this is a skill and not just "call the tool"
 
-Each engagement item carries context — the post being engaged with, the target persona, the sender's own voice and positioning, the draft comment. Reviewing inline burns tokens fast. Subagents with their own context windows do the review work and return compact verdicts.
+The backend produces a research dossier + shippable-floor comment for every engagement (the `polished_floor` field — quality SLA for all four front doors per `project_four_front_doors_architecture`). The skill's job is to UPLIFT that floor into a great comment using the operator's Claude subscription, then write the polished result back via `manage_engagement` with `polish_provenance.source="skill"` so the two-stage edit diff is captured.
+
+Reviewing inline burns tokens fast. Subagents with their own context windows do the uplift in parallel and return compact verdicts.
 
 ## Subagent: `vruum-engagement-reviewer`
 
@@ -77,10 +87,25 @@ For each queue type the user selected, call the appropriate list endpoint, get I
 
 Spawn up to 4 subagents concurrently. For larger queues (15+), dispatch in waves.
 
+#### What the subagent receives from `get_engagement_review`
+
+The MCP payload now carries the full four-front-doors quality stack per item:
+
+- `content` — what currently ships (= `polished_floor` when present, else `first_draft`)
+- `polished_floor` — backend's shippable-floor output (this is what your uplift starts from)
+- `first_draft` — pre-floor draft (use only for backward-compat fallback)
+- `dossier` — research dossier (`post_entities`, `author_recent_posts`, `prior_interactions`, `knowledge_hits`). USE the named entities and numbers in your uplift — that's the grounding the backend already gathered.
+- `pitch_phrases` — phrases that must NEVER appear in marketing comments (per-tenant value_prop language)
+- `polish_provenance` — `{first_draft: {...}, polished_floor: {...skipped?, regressed?}, final?: {...}}`. Note whether the floor pass was `skipped` (model said the input was already good) or `regressed` (floor was worse and we reverted) — those signal that the input has known weaknesses.
+- `validator_failures` — structural failures the backend recorded (e.g. `["banned_opener:Yep", "no_specific_marker:0/1"]`). Treat as a checklist to fix during uplift.
+- `rules_version` + `schema_version` — backward-compat signal
+
+**Backward-compat:** if `polished_floor` is null (old queue rows pre-migration), use `content` as your input and skip the dossier-anchored grounding.
+
 Subagent prompt template:
 
 ```
-You are an engagement review agent for {company_name}.
+You are an engagement uplift agent for {company_name}.
 
 SENDER PROFILE:
 {sender_profile_block}
@@ -89,22 +114,51 @@ Engagement IDs: {comma_separated_ids}
 
 Call get_engagement_review with engagement_ids="{comma_separated_ids}" and content_length="full" to load your assigned items.
 
-For each engagement:
-1. Check voice fit against sender profile (would this person actually say this?)
-2. Check relevance to the prospect's post
-3. Check for AI tells (generic phrasing, hollow flattery, buzzwords)
-4. Check for over-pitching (warming comments should NOT sell)
-5. Rate quality: genuine value-add vs generic engagement
+Each item gives you the dossier, polished_floor, first_draft, pitch_phrases, and
+validator_failures. Your job is UPLIFT, not just review: take polished_floor and
+make it materially better when you can.
 
-If a comment needs fixes, edit it via manage_engagement. Only edit when there's genuine improvement — don't rewrite solid comments.
+Quality bar (ACQ framework):
+- Acknowledge: reference a specific phrase/number/named entity from the post.
+- Context: add information the post did NOT have — pull a specific fact from
+  the dossier (named entity, number, prior post, KB hit). No fabrication.
+- Question: optional. Skip ~60% of the time.
+- Length: 15-40 words total. Hard limit 280 chars.
+
+Hard constraints:
+- No em-dashes (—) or en-dashes (–). No curly quotes.
+- No banned openers (Yep, Great post, This is the part people skip, etc.).
+- Three-beat structure (three equal-length sentences) is the #1 AI tell — avoid.
+- No phrase from item.pitch_phrases verbatim (marketing voice must stay separate from outreach pitch).
+- No company/product names, URLs, or CTAs.
+
+For each engagement:
+1. Read polished_floor + dossier + pitch_phrases + validator_failures.
+2. Decide UPLIFT, KEEP, or FLAG:
+   - UPLIFT: rewrite to fix listed validator_failures AND/OR pull a sharper
+     specific fact from the dossier. Materially better, not lateral.
+   - KEEP: polished_floor is already strong. Don't edit.
+   - FLAG: structurally broken (off-topic, wrong stage, prospect bad fit).
+     Recommend skip + plan-stop cascade.
+3. If UPLIFT, call manage_engagement with:
+     action="edit"
+     engagement_ids="<id>"
+     content="<your uplifted comment>"
+     polish_provenance={
+       "source": "skill",
+       "model": "<your model — claude-opus-4-7, claude-sonnet-4-6, etc.>",
+       "at": "<ISO8601>",
+       "rewrite_notes": "<one line — what you changed and why>"
+     }
 
 IMPORTANT: Do NOT approve or skip engagements. Return recommendations only.
+The operator approves in Step 5.
 
 Return a structured summary for each item:
-ENGAGEMENT: {id} | TYPE: {reaction|comment} | PERSON: {name} | SOURCE: {warming|nurture|marketing} | RECOMMENDATION: {approve|edited|flag|skip} | CONFIDENCE: {high|medium|low} | REASONING: {1-2 sentences} | EDITED: {yes/no} | COMMENT_TEXT: {the comment text, or "reaction" for likes}
+ENGAGEMENT: {id} | TYPE: {reaction|comment} | PERSON: {name} | SOURCE: {warming|nurture|marketing} | RECOMMENDATION: {uplifted|kept|flag} | CONFIDENCE: {high|medium|low} | REASONING: {1-2 sentences} | UPLIFTED: {yes/no} | COMMENT_TEXT: {the comment text, or "reaction" for likes} | VALIDATOR_FAILURES_FIXED: {comma-separated, or "none"}
 ```
 
-For high-value comments (match score 80+, nurture, cold marketing), use research mode: 1 comment per subagent. The subagent reads the prospect's actual post via `get_person_360`, understands what they're saying, and edits only if there's a real opportunity to improve.
+For high-value comments (match score 80+, nurture, cold marketing), use research mode: 1 comment per subagent. The subagent reads the prospect's actual post via `get_person_360`, cross-checks against the dossier, and uplifts only when there's a real opportunity to improve.
 
 ### Step 5: Present results — always show content
 

package/skills/engagement-triage/references/engagement-subagent-instructions.md

@@ -1,79 +1,121 @@
-# Subagent Instructions: Engagement Review Agent
+# Subagent Instructions: Engagement Uplift Agent
 
-You are reviewing AI-generated LinkedIn engagement items (comments, reactions, reposts) before they go to a human operator for approval.
+You are uplifting AI-generated LinkedIn engagement items (comments, reactions, reposts) before a human operator approves them. Your job is **uplift, not just review** — the Vruum backend already produced a shippable-floor comment for each item. You take it from "good" to "great" using the dossier, then record provenance so the system learns from the two-stage edit diff.
+
+This is front door 1 (managed ops) in the four-front-doors architecture (see project memory `project_four_front_doors_architecture`). Front doors 2/3/4 ship `polished_floor` from the backend directly; we're the layer that makes managed-ops comments stand out.
 
 ## Step 1: Load your items
 
-Call `get_engagement_review` with your assigned `engagement_ids`, `content_length="full"`. This returns for each item:
-- The draft comment text (if comment or repost_commentary)
-- The reaction type (if reaction)
-- The target post text (what the prospect posted)
-- Person info: name, title, match score, segment, outreach plan status
-- Warming/nurture progress: e.g. "2/4 warming engagements sent"
-- Source: warming, nurture, or marketing
-- ICP match reasoning
-- Budget status for the sender account
-
-## Step 2: Review each item
-
-### 2a. Relevance check
-Does the comment address something specific in the post? A comment that could apply to any post fails.
-- Bad: "Great insights here. Definitely something to think about."
-- Good: "The stat on ramp time resonating, we've seen similar patterns when hiring reps with zero SDR background"
-
-### 2b. AI tell detection
-Comments are short (under 300 chars). They fail fast if robotic.
-Check for:
-- Generic opener ("Great post!", "Loved this!", "So true!")
-- Transition words: moreover, furthermore, additionally
-- Emoji overuse (one is fine, three or more is a tell)
-- Round numbers that feel fabricated ("100% agree")
-- Commenting on something not in the post text (hallucination)
-- Em dashes (banned)
-
-### 2c. Relationship stage fit
-- **Warming**: purely value-add, never reference the outreach company's services. Read like a thoughtful peer.
-- **Nurture**: slightly warmer but still not salesy. Reference shared context only if genuinely relevant.
-- **Marketing**: professional and non-salesy. Represents the sender's professional brand.
+Call `get_engagement_review` with your assigned `engagement_ids`, `content_length="full"`. The payload now carries the full quality stack per item:
+
+- `content` — what currently ships (defaults to `polished_floor` when present, else `first_draft`)
+- `polished_floor` — backend self-critique output, your uplift starting point
+- `first_draft` — pre-floor draft; useful when polished_floor is null (legacy queue rows)
+- `dossier` — research dossier:
+  - `post_entities.capitalized` / `acronyms` / `numbers` — named entities & numbers in the post
+  - `author_recent_posts` — author's last 5 posts (snippets)
+  - `prior_interactions` — Vruum's prior engagement with this person
+  - `knowledge_hits` — relevant entries from the company knowledge base
+- `pitch_phrases` — phrases that must NEVER appear (company value_prop language)
+- `polish_provenance.polished_floor.skipped` — true means the backend's floor model kept the input (so first_draft has known weaknesses)
+- `polish_provenance.polished_floor.regressed` — true means the backend's floor rewrite was worse than first_draft and was reverted (signal that the rules are hard for this draft)
+- `validator_failures` — structural failures recorded by the backend (e.g. `["banned_opener:Yep","no_specific_marker:0/1"]`). Treat as a checklist.
+- `target_post_text` — what the prospect actually posted
+- `person_id`, `person_name`, `person_title`, `match_score`, `segment_name` — person context
+- `source` — `warming` / `nurture` / `marketing`
+- `budget_status` — sender daily quota
+- `schema_version` + `rules_version` — backward-compat signals
+
+**Backward-compat:** if `polished_floor` is null (pre-migration queue row), use `content` (== `first_draft`) as your starting point and proceed without dossier grounding. Note `legacy_payload` in REASONING.
+
+## Step 2: Decide UPLIFT / KEEP / FLAG per item
+
+### 2a. KEEP
+The polished_floor already passes ACQ, references a specific dossier fact, has no validator_failures, and you cannot materially improve it. Don't edit. Don't make lateral moves (swapping synonyms isn't uplift).
+
+### 2b. UPLIFT
+Either there are listed `validator_failures` you can fix, OR a sharper dossier fact would land harder than what polished_floor uses. Rewrite to:
+- **Acknowledge**: reference a specific phrase/number/named entity from the post text (item.target_post_text).
+- **Context**: add information the post did NOT have. Pull a specific fact from item.dossier — a number, named entity, prior post, KB hit. No fabrication.
+- **Question**: optional (~40% rate). Skip 60% of the time so question-ending doesn't become its own AI tell.
+- **Length**: 15-40 words total. Hard limit 280 chars.
+
+Hard constraints (must NOT violate):
+- No em-dashes (—) or en-dashes (–). No curly quotes.
+- No banned openers (Yep, Great post, This is the part people skip, etc. — see `quality-standards.md`).
+- No three-beat structure (three sentences of similar length). The #1 AI tell.
+- Zero phrases from `item.pitch_phrases` verbatim (marketing voice must stay separate from outreach pitch).
+- No company/product/URL/CTA.
+
+### 2c. FLAG
+Structural problems uplift can't fix:
+- Off-topic (post topic isn't in sender's lane despite backend gates)
+- Wrong stage fit (warming comment that needs nurture treatment, etc.)
+- Prospect is a clear bad fit (match_score < 35 and no signal in dossier)
+- The dossier is empty AND the post is too short/generic for ACQ grounding
+
+Set RECOMMENDATION=flag with a one-line reason. The skill will offer skip + plan-stop cascade.
 
 ### 2d. Reactions
-If engagement_type = reaction, confirm the reaction_type fits:
-- like/thumbs_up: most posts
-- celebrate: milestones/announcements
-- support: challenges/difficulties
-Flag if the reaction type seems wrong for the post context.
+If `engagement_type=reaction`, confirm the `reaction_type` fits the post tone:
+- like / thumbs_up: most posts
+- celebrate: milestones / announcements
+- support: challenges / difficulties
+- insightful: technical / data-rich posts
+Reactions are usually KEEP. Only edit if reaction_type is wrong for the post context.
 
 ### 2e. Budget check
-If `budget_status` shows the sender account is near daily limits, note it in REASONING.
+If `budget_status` shows the sender account near daily limits, note it in REASONING (the operator may want to defer some approvals).
 
-## Step 3: Edit if needed
+## Step 3: Apply the uplift via manage_engagement
 
-Use `manage_engagement` with action="edit" and the engagement_id to update content.
-- Keep to 1-3 sentences max
-- Make it specific to the post
-- Sound like a real person's quick reaction
-- No em dashes
-- Vary sentence rhythm
+When RECOMMENDATION=uplifted, write back via `manage_engagement`:
 
-## Step 4: Return structured summary
+```
+manage_engagement(
+  engagement_ids="<id>",
+  action="edit",
+  content="<your uplifted comment>",
+  polish_provenance={
+    "source": "skill",
+    "model": "<your model — claude-opus-4-7 / claude-sonnet-4-6 / etc.>",
+    "at": "<ISO8601 timestamp>",
+    "rewrite_notes": "<one line: what changed and why>"
+  }
+)
+```
+
+The `polish_provenance` payload is what captures the two-stage edit diff signal (polished_floor → skill_polished → operator_final). The backend merges it under the `final` key of the existing JSONB; both stages remain visible in the row's polish_provenance after the operator's eventual approve.
+
+**Multi-tenant defense:** if the orchestrator gave you a company scope in your dispatch prompt, verify `item.user_company_id` matches that scope before issuing the write. If not, abort with REASONING="cross-tenant mismatch detected, write blocked".
+
+Do NOT approve or skip — operator handles those in Step 5 of the parent skill.
+
+## Step 4: Return a structured summary
 
-For each item:
 ```
 ENGAGEMENT: {engagement_id}
 PERSON: {person_name} ({person_title})
 TYPE: {comment|reaction|repost_commentary}
 SOURCE: {warming|nurture|marketing}
-RECOMMENDATION: {approve | edited | flag | reject}
+RECOMMENDATION: {uplifted | kept | flag}
 CONFIDENCE: {high | medium | low}
-REASONING: {1 sentence}
-EDITED: {yes/no}
-NEW_CONTENT: {if edited}
-ISSUES_FOUND: {comma-separated or "none"}
+REASONING: {1-2 sentences — what was in the dossier you used, or why kept/flagged}
+UPLIFTED: {yes/no}
+COMMENT_TEXT: {final comment text, or "reaction" for likes}
+VALIDATOR_FAILURES_FIXED: {comma-separated codes you cleared, or "none"}
 ---
 ```
 
-## Confidence Guide
+## Confidence guide
+
+- **HIGH** — UPLIFT pulled a specific dossier fact, cleared all listed validator_failures, output is materially better than polished_floor. Or KEEP with clear ACQ structure intact.
+- **MEDIUM** — Edits made but the dossier was thin / forced a stretch. Or KEEP when polished_floor is acceptable but not great.
+- **LOW** — Couldn't anchor in dossier (refused to fabricate), or wrote uplift that you're unsure beats polished_floor. Flag for human eyes.
+
+## Error handling
 
-**HIGH**: Specific, human-sounding, correctly staged. No edits or minor word changes only.
-**MEDIUM**: Acceptable but substantive edits made, or relationship stage fit is uncertain.
-**LOW**: References things not in the post, clearly generic, or stage fit is wrong. Flag for human.
+- **MCP call failure**: retry once. If it still fails, set RECOMMENDATION=flag with REASONING="MCP error: <message>" and continue with the next item. Don't abort the whole batch.
+- **manage_engagement write fails (idempotency)**: report failure in REASONING; the operator can re-run. The skill keeps partial state in `/tmp/engagement-triage-$$/pending.jsonl` (parent skill responsibility).
+- **No polished_floor AND no first_draft AND no content**: the queue row is malformed; flag with REASONING="malformed_queue_row, no draft to uplift".
+- **Empty dossier + empty post text**: flag with REASONING="no grounding available".

package/skills/engagement-triage/references/quality-standards.md

@@ -2,18 +2,28 @@
 
 These apply to LinkedIn comments and reposts in the engagement queue.
 
-## Universal rules
+> **Single source of truth:** the authoritative rules ship in
+> `backend/app/domains/marketing/data/engagement_rules.json`. Backend Python
+> validators (`engagement_validators.py`) load it directly; this reference file
+> is the human-readable mirror for subagent prompt design. If the JSON changes,
+> update this file and bump `rules_version`.
+
+## Universal rules (rules_version 2026.05.10)
 
 - Never generic: a comment that could apply to any post fails immediately
-- Under 300 characters, hard limit
-- No em dashes, ever
+- 15-40 words total, hard limit 280 chars
+- No em dashes (—), no en dashes (–), no curly quotes
 - No "Great post!", "Love this!", or any pure agreement opener without substance
+- No banned openers (see engagement_rules.json `banned_openers`): "Yep", "This is the part people skip", "This is where it gets real", "That's the real story", "Big milestone", "That part actually works", "The real signal", etc.
 - One emoji maximum. Zero is fine.
-- Reference something specific from the post: a number, an example, a named decision
+- Acknowledge MUST reference a specific phrase/number/named entity from the post text
+- Context MUST add information the post did NOT have — digit, named entity, contrasting case, or KB hit pulled from `dossier`
 - No transition words: moreover, furthermore, additionally
-- No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, pivotal
+- No banned AI vocabulary (see engagement_rules.json `banned_words`): delve, leverage, robust, navigate, foster, comprehensive, nuanced, etc.
+- Three-beat structure (three sentences of similar length) is the #1 AI tell — never produce it
 - Vary sentence rhythm even in short comments
 - Sound like typing fast, not crafting a message
+- No phrase from `item.pitch_phrases` verbatim (marketing voice ≠ outreach pitch)
 
 ## Warming-specific
 

package/skills/enrich-prospect/SKILL.md

@@ -77,9 +77,9 @@ No embedding search finds these gaps. No keyword filter finds them. You have to
 
 ## Step 4: Offer to save
 
-"Update AI notes with this diarization? This will be visible to the outreach agent when writing messages."
+"Append this diarization as a note? It will appear on the person card timeline and be visible to the outreach agent when writing messages."
 
-If approved: call `update_person_ai_notes` with a condensed version of the diarization (the SAYS/ACTUALLY gap, key signals, and recommended approach).
+If approved: call `add_person_note` with a condensed version of the diarization (the SAYS/ACTUALLY gap, key signals, and recommended approach). Each call appends a new row to the person's notes timeline — no overwrite of prior notes.
 
 ## Notes
 

package/skills/pipeline-fill/RESEARCH-ENGINE.md

@@ -188,7 +188,27 @@ If the prospect's company isn't already cached and Phase A produced fresh resear
    - Last-space heuristic: split on the last space. `Jane Smith` → first=`Jane`, last=`Smith`. `Jane van der Merwe` → first=`Jane`, last=`van der Merwe`.
    - **Override with Phase B canonical names** if `fetch_linkedin_data` returned them. LinkedIn's `first_name`/`last_name` fields are authoritative; the heuristic is a fallback for candidates without `linkedin_url`.
 
-2. **Call `save_person_research(first_name=..., last_name=..., company=..., linkedin_url=..., email=..., topics_of_interest=..., recent_posts=..., opening_hooks=..., role_start_date=...)`.**
+2. **Call `save_person_research(...)`.** The backend now requires you to identify the company unambiguously — pick ONE of these two paths:
+
+   **Path A (preferred): pass `company_id`.** Run `save_company_research(...)` first, capture the returned `company_id`, then pass it here.
+
+   **Path B (when Path A isn't done yet): pass `company_name` + at least one anchor.** Required anchors are any of `company_domain`, `company_website`, or `company_linkedin_url`. The data is in the LinkedIn payload you already fetched. The prospect's CURRENT employer is the entry in `work_experience[]` with `end_date: null` — that entry has `company_linkedin_url` (e.g. `https://linkedin.com/company/microsoft`). If you ran `fetch_linkedin_data(include_company=true)`, the separate company response carries `website` and `industry`. Domain can be derived from website (e.g. `microsoft.com` from `https://microsoft.com`) or from the prospect's verified work email.
+
+   **Anchor-less name-only saves are rejected with HTTP 422.** This was hardened to stop orphan stub creation in the companies table — name-only saves were silently producing duplicate rows for common names like Microsoft.
+
+   Example call:
+   ```
+   save_person_research(
+     first_name=..., last_name=...,
+     email=..., linkedin_url=...,
+     # ONE of:
+     company_id=<from save_company_research>
+     # OR:
+     company_name=..., company_linkedin_url=...,  # at least one anchor
+     # ...rest of research fields
+   )
+   ```
+
    - If the prospect already had `person_id` set on the candidate (e.g. operator pasted a Vruum person UUID), pass it explicitly: `save_person_research(person_id=..., ...)` — backend updates rather than creating a new record.
    - The response includes the `person_id`. Capture it for step c.