VERA

Appearance

Vendors & Liabilities ​

Vendors are external contractors or agencies tracked in VERA. Liabilities are fixed payment commitments to those vendors.

Vendor users ​

A vendor is a user with employment_type = "vendor".

add_user name="Dev House X" employment_type="vendor"

Vendor users are like regular users in the system — they appear in list_users, can be allocated to projects, and have time logged against them. The difference is:

  1. PMs log hours on their behalf — vendor users don't message the bot themselves
  2. Cost is typically governed by a liability rather than an hourly rate
  3. Revenue is the same as direct labor — hours × billing_rate

Liabilities ​

A liability is a fixed payment commitment to a vendor on a specific project.

Example: "We agreed to pay Dev House X $5,000 to build the authentication module on Project Rambo."

This is recorded as a liability with:

  • vendor_user_id — Dev House X's user ID
  • project_id — Project Rambo
  • agreed_amount — $5,000
  • agreed_hours — 80 (the contracted scope in hours)
  • description — "Authentication module development"

Why liabilities exist ​

Without a liability, VERA calculates vendor cost as hours × hourly_cost. But for fixed-fee vendor engagements, that's wrong — you've agreed to pay $5,000 regardless of how many hours are logged.

A liability overrides the hourly calculation entirely. When a liability is active for vendor X on project Y, the cost for that vendor on that project is agreed_amount, not hours × rate. The two methods are never mixed.

Vendor hours and the project budget ​

agreed_hours captures the contracted scope in hours. Because vendors don't log time themselves, VERA cannot know their actual pace — so it assumes even delivery from the liability creation date to the project deadline:

implied_hours_today = agreed_hours × (days_elapsed / total_days)

This implied figure is added to the team's logged hours when computing budget burn, health status, and proactive alerts. The project deadline is the 100% mark; at the deadline, all agreed_hours count in full. A cancelled liability contributes zero implied hours.

Both the agreed_hours value and the accrued implied_hours_to_date appear in the list_liabilities response. The project's deadline must be set before a liability can be created.

Revenue still comes from hours ​

Liabilities only affect cost. Revenue is still recognised from time entries in the normal way (hours × billing_rate for T&M, or percentage-of-completion for Fixed Price).

Liability lifecycle ​

create_liability → active
       ↓
  cancel_liability → cancelled (not deleted)

Cancelled liabilities are kept for audit trail. When listing liabilities, filter by status = "active" to see open commitments only.

Permissions ​

ActionOwnerManagerUser
Create liability✅❌❌
View liabilities✅ (all)✅ (own projects)❌
Cancel liability✅❌❌

P&L cost rule (vendor summary) ​

For vendor X on project Y:

  If active liability exists:
    cost = liability.agreed_amount

  Else:
    cost = hours_logged × hourly_cost (from Rate History, effective on entry date)

This rule is applied when calculating project cost and margin in generate_monthly_report and the reporting sheet's financial tabs.

Common vendor workflow ​

  1. Add the vendor: add_user with employment_type="vendor"
  2. Create a liability: create_liability with the agreed amount, contracted hours, and description — the project must have a deadline set
  3. PM logs hours: log_time with the vendor's user ID — this tracks delivery against the engagement (optional but recommended)
  4. View cost: The liability's agreed_amount appears as cost in financial reports, regardless of hours logged
  5. Budget burn: The vendor's agreed_hours accrue linearly against the project budget — no manual entries needed for the hours story to stay accurate

If the engagement grows beyond the original liability, cancel the old one and create a new one with the updated amount.

VERA by talktalkmake