@vruum/skills 0.6.59 → 0.6.60

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.59",
+  "version": "0.6.60",
   "description": "Vruum AI skills + remote MCP server for B2B GTM teams. Slash commands for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis, paired with the full Vruum MCP tool surface over OAuth 2.1.",
   "author": {
     "name": "Vruum AI",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "vruum",
-  "version": "0.6.59",
+  "version": "0.6.60",
   "description": "Vruum AI skills + remote MCP server for B2B GTM teams. Skills for outreach triage, engagement triage, pipeline filling, prospect enrichment, and reply diagnosis, paired with the full Vruum MCP tool surface over OAuth 2.1.",
   "author": {
     "name": "Vruum AI",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.6.59",
+  "version": "0.6.60",
   "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": {
@@ -41,5 +41,5 @@
     "outreach",
     "gtm"
   ],
-  "contentHash": "e01e694eb0dd3fdf8067590b38ddd7b09c2288853c1ced48c335a4ae52eb4408"
+  "contentHash": "559d42027f1ec16aa3dec684dc62bb66f5c4d240568c719fec789cb12fe2999a"
 }

package/skills/deal-triage/SKILL.md

@@ -102,11 +102,11 @@ After presenting results, the user can request actions. Execute them using MCP t
 - **Close deal** → `manage_deal` action=won or action=lost (payload carries win_factors / loss_reason)
 - **Reopen deal** → `manage_deal` action=reopen with payload={stage}
 - **Mark stalled** → `manage_deal` action=stalled (records the stalled outcome; payload optional)
-- **Update account state** → `manage_account` action=state with id=<company_id> and payload={account_stage?, health_score?, arr_current?, arr_potential?, renewal_at?, notes?}. Do this whenever the review surfaced account-level facts: a stage that no longer matches reality (the backfilled stages have never been updated), a health read from the conversation, or ARR/renewal numbers the seller confirmed. The account row is what the impact scoreboard and deal_360 read — a stale stage there misleads every later review.
+- **Update account state** → `manage_account` action=state with id=<company_id> and payload={renewal_at?, notes?, service_model?, scoped_labor_minutes_per_month?}. The account's lifecycle stage is NOT in this payload: it is derived from the facts (deal outcomes, impact events, recorded churn/renewal) and the response carries `account_stage_basis` — the fact that set it. To move a stage, record the fact: `manage_deal` action=won/lost/reopen, `manage_account` action=record_impact (practice + event_type from the practice's list; `winback`/`churn` ends the contract, `expansion`/`renewal_signed` restores it). There is no health score and no typed ARR: the account's value is `won_annual_value_minor` from its won deals' money records.
 
 For batch actions ("advance all deals in proposal"), confirm with the user before executing.
 
-**Account hygiene (every run):** for each reviewed deal's account, compare `account_state.account_stage` against what the deal review just showed (an `engaged`-stage account with a closed-won deal, or a `prospect` account with an active opportunity, is stale). Propose the corrected stage in the Step 3 summary and write it via `manage_account` action=state on approval. This is the write half of the accounts loop — the read half (scoreboard, deal_360) only works if reviews maintain it.
+**Account hygiene (every run):** for each reviewed deal's account, read `account_state.account_stage` with its `account_stage_basis` and the `lifecycle.reasons`. The stage already follows the deals, so a mismatch means a FACT is missing, not a label: a customer that is still `committed` has no post-commit impact event on record (ask what the customer got and record it), an account the seller calls lost is `adopting` until a `churn` is recorded, a renewal the seller mentioned is not on file until `renewal_signed` is. Propose the missing facts in the Step 3 summary and record them on approval. This is the write half of the accounts loop — the read half (scoreboard, deal_360) only works if reviews record what happened.
 
 ## Error handling
 

package/skills/expansion-fill/COHORT-QUERIES.md

@@ -48,7 +48,7 @@ candidate in the skill's Step 3 enrichment and:
 - Up-rank rows where `account_stage` is `adopting` or `expansion_ready`.
 - Down-rank or skip rows where `account_stage` is `dormant` or `churned` —
   those belong in `/winback-fill`, not expansion.
-- Use `accounts.health_score` (returned in the same payload) as a gate;
+- Use the derived `account_stage` with its `account_stage_basis` (returned in the same payload) as the gate: `adopting` / `expansion_ready` means impact recurs;
   `> 70` is the floor for a productive expansion conversation.
 
 The skill does not change account stages itself — stages are set in the
@@ -61,7 +61,7 @@ Per-account features the skill computes from `get_person_360` +
 
 - `accounts.renewal_at` (from `fetch` type=account_state) — proximity weight
   (60-180d sweet spot)
-- `accounts.health_score` — gate (>70 only)
+- `accounts.account_stage` — gate (`adopting` or `expansion_ready` only; there is no typed health score)
 - `accounts.account_stage` — boost (`adopting`, `expansion_ready`) or skip
   (`dormant`, `churned`)
 - Most recent `practice='adoption'` activity in last 60d — engagement signal

package/skills/expansion-fill/SKILL.md

@@ -44,7 +44,7 @@ Step 3 — Per-account enrichment. For each surfaced (person, company):
 
 Step 4 — Score and rank. Within the cohort, rank by:
 - (a) **Renewal pressure** — `accounts.renewal_at` within 60-180 days → up-rank
-- (b) **Health signal** — `accounts.health_score` > 70 (only push expansion if account is healthy)
+- (b) **Health signal** — the derived stage with its basis: `adopting` / `expansion_ready` means impact recurs (value events in ≥3 of the last 4 weeks); there is no typed health score
 - (c) **Recent engagement** — if there's `practice='adoption'` activity in the last 60d (account engaged), up-rank
 - (d) **Account stage** — `accounts.account_stage IN ('adopting', 'expansion_ready')` → up-rank; `dormant` → down-rank or skip
 - (e) **Champion present** — if any `company_people` row has been engaged in the last 30d (touch sent or reply received), surface the champion's name
@@ -66,7 +66,7 @@ Step 6 — Hand off to outreach. Two options:
 - **Option A (recommended)**: Approve the ranked list, then for each account: run `/pipeline-fill` with that prospect_list — same Sales Nav harness flow, just sourced from the expansion cohort instead of cold. Tag the resulting `outreach_plans.tag` with `bowtie_pilot:expansion` so success-tracking finds them.
 - **Option B**: Direct `manage_outreach` action=start with an expansion objective: create it with `target.lever = {"component": "expansion"}` (`objective_create`) and the right tone — formal, ROI-focused, no opener-hooks since the customer already knows you. The lever does the sourcing work: the plan's pool is the installed base (`accounts.account_stage = 'expansion_ready'`, no open deal), no discovery provider runs, the conversion evidence is scoped to expansion (an acquisition rate never sizes it), and `objective_source` qualifies the buyer titles at those accounts for free.
 
-Step 7 — Success tracking (auto). When a calendar webhook fires a `meeting_booked` event on an outreach plan tagged `bowtie_pilot:expansion`, the webhook handler in `backend/app/domains/calendar/` auto-records the impact event, equivalent to:
+Step 7 — Success tracking (auto). When a calendar `meeting_booked` outcome lands on an action whose objective's growth lever names expansion (`target.lever.component = "expansion"`), `deals/services/lifecycle_outcomes.record_lifecycle_meeting` records the impact event, equivalent to:
 ```
 manage_account(
   action="record_impact",
@@ -78,9 +78,9 @@ manage_account(
   }
 )
 ```
-You do NOT manually record the impact event for tagged plans. If a meeting is booked outside Vruum (manual scheduling, calendar tool not connected), record it manually via `manage_account` action=record_impact from the person 360 Activity tab.
+You do NOT manually record the impact event for meetings booked under an expansion objective. If a meeting is booked outside Vruum (manual scheduling, calendar tool not connected), record it manually via `manage_account` action=record_impact from the person 360 Activity tab — `event_type` must be one of the expansion practice's types.
 
-After 30 days, run `fetch` type=scoreboard subtype=impact to measure cohort uplift: expansion `event_count` should be > 0 with `impact_sum` matching the booked deals' annual values (minor units, one currency).
+After 30 days, run `fetch` type=scoreboard subtype=impact with `id=<company_id>` per account to measure cohort uplift: expansion `event_count` should be > 0 with `impact_sum` matching the booked deals' annual values (minor units, one currency).
 
 ## When NOT to use this skill
 

package/skills/winback-fill/SKILL.md

@@ -19,7 +19,7 @@ A closed-lost deal is not a closed door. Most "lost" deals had a real conversati
 - Their company has had a recent trigger (new exec, funding, news event)
 - A former champion has moved to a new company (the "champion follows you" play)
 
-The impact scoreboard and the `account_stage='churned'`/`'dormant'` tagging let this skill target the right accounts deterministically.
+The impact scoreboard and the derived `account_stage` (`churned` on a recorded churn or cancelled subscription, `dormant` after 60 days without impact — see `docs/ACCOUNT-LIFECYCLE-VOCABULARY.md`) let this skill target the right accounts deterministically.
 
 ## Where heavy logic lives
 
@@ -57,7 +57,7 @@ Limit 50. Order by `stage_changed_at DESC` (most-recent loss first — freshest
 Step 3 — Per-account enrichment.
 - `get_person_360` — what was the original conversation? `analysis` JSONB on the old deal often captures objection patterns.
 - `fetch` type=company_research — has anything changed at the company? New exec? Funding? Recent news?
-- `accounts.account_stage` — if `churned`, the account has been flagged as dead. Skip or down-rank unless variant 2/3 applies.
+- `accounts.account_stage` — if `churned`, a churn was recorded (or the subscription cancelled); `account_stage_basis` says which. Skip or down-rank unless variant 2/3 applies.
 
 Step 4 — Score and rank.
 - **Loss reason quality**: `competitor_chose_other`, `timing`, `budget_cycle`, `no_decision` are revivable. `no_fit`, `no_budget_permanent` are not (already filtered, but double-check).
@@ -86,7 +86,7 @@ Step 6 — Hand off. Two options:
 - **Option A (recommended)**: Approve the list; run `/pipeline-fill` with the prospect_list for harness deep research + outreach. Plans get `outreach_plans.tag = bowtie_pilot:winback`.
 - **Option B**: Direct `manage_outreach` action=start with a winback-flavored objective (pre-create a `winback_<your-tenant>` objective — tone: empathetic, no apology, lead with what changed since last conversation). Winback is the book's closed loop over the Bowtie, not a growth component: leave `target.lever` at its default (acquisition by volume) and select the dormant/churned accounts through the objective audience (`objective_account`), so their people are the cohort and the plan does not buy new prospects for them.
 
-Step 7 — Success tracking (auto). The calendar webhook records the impact event, equivalent to:
+Step 7 — Success tracking (auto). A calendar `meeting_booked` outcome with a `churned` or `dormant` account records the impact event (`deals/services/lifecycle_outcomes.record_lifecycle_meeting`), equivalent to:
 ```
 manage_account(
   action="record_impact",
@@ -98,7 +98,9 @@ manage_account(
   }
 )
 ```
-when a meeting is booked on a plan tagged `bowtie_pilot:winback`. You do NOT manually fire for tagged plans. After 30 days, `fetch` type=scoreboard subtype=impact should show winback `event_count` > 0.
+whatever plan or objective the meeting came from. You do NOT fire it by hand. After 30 days, `fetch` type=scoreboard subtype=impact with `id=<company_id>` should show winback `event_count` > 0.
+
+After a successful winback the stage follows the facts: a new open deal makes a `churned`/`dormant` account `engaged`, a win makes it `committed`, a `renewal_signed` impact event (practice expansion) cancels the recorded churn. Nobody types the stage (`manage_account` action=state carries no `account_stage`).
 
 ## When NOT to use this skill