# Product requirements reference — enterprise tools emulated by Northstar

**Document type:** source-backed product requirements and mock-parity contract
**Snapshot date:** 2026-07-28
**Scope:** Salesforce CRM, Zendesk Support, Stripe Billing, GitHub, and
Atlassian Confluence/Rovo MCP

## 1. Purpose

This document defines the software products and operational behaviors that the
five Northstar MCP servers emulate. It is not a PRD for Blobfish, the benchmark,
or the downloadable demo. A recipient should be able to answer:

1. Which real product is each server based on?
2. Which product entities, operations, permissions, and state transitions matter?
3. How does every mock tool map to a vendor surface?
4. Where is the mock intentionally simpler or extended for evaluation?
5. What observable acceptance test establishes correct behavior?

Vendor documentation is the authority. The mock uses generic names and
deterministic SQLite state; it does not claim wire-level or feature-complete
compatibility with any vendor.

## Evidence scope and workflow claim boundary

The source ledger provides primary anchors for the *component operations* in
this world: searching or updating CRM records, managing support tickets,
reading invoices and creating refunds, coordinating issues and pull requests,
and searching or updating knowledge pages. Executable tests then prove that the
mock implements its declared deterministic contract.

The ledger does **not** prove that a real customer performs the ten exact
cross-product sequences in section 9. Those are vendor-grounded synthetic
composites created for evaluation. This release contains zero customer
interviews, zero customer SOPs, zero process-mining exports, and zero production
vendor traces. A customer-workflow claim requires one of those evidence classes
and must remain separate from vendor capability citations.

The auditable chain is:

1. `sources.jsonl` — source URL, publisher, publication date where stated,
   original summary, design use, and a shared bundle-assembly stamp (not a
   per-source fetch receipt).
2. `article_notes/` — one original note per source.
3. this PRD — exact mock-to-vendor mapping and intentional parity gaps.
4. `tools.json` plus server code — executable schemas and state transitions.
5. `tasks.jsonl`, oracle traces, and verifier audit — proof that the designed
   composite workflows execute and are graded correctly in this mock.

## 2. Reference-product map

| mock server | reference product | primary product surface | mock entities | source |
|---|---|---|---|---|
| `crm` | Salesforce | Hosted MCP SObject operations and custom tools | accounts, contacts, interactions | [Salesforce Hosted MCP](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/hosted-mcp-servers-overview.html), [SObject All](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/references/reference/sobject-all.html) |
| `support` | Zendesk Support | Tickets API | tickets, internal notes | [Zendesk Tickets API](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/) |
| `billing` | Stripe Billing | Stripe MCP plus Invoices/Refunds APIs | invoices, refunds | [Stripe MCP](https://docs.stripe.com/mcp), [Invoices API](https://docs.stripe.com/api/invoices/list) |
| `engineering` | GitHub | Official GitHub MCP Server | repositories, issues, pull requests | [GitHub MCP docs](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/use-the-github-mcp-server), [server source](https://github.com/github/github-mcp-server) |
| `knowledge` | Atlassian Confluence/Rovo MCP | Confluence read/write/search tools | documents, acknowledgements, findings, audit events | [Rovo MCP supported tools](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/supported-tools/) |

### Mapping labels

- **Aligned:** the product exposes the same user-visible operation.
- **Transformed:** the product capability is preserved behind a narrower,
  deterministic contract.
- **Lab extension:** the behavior supports cross-product evaluation but is not
  represented as a native vendor MCP tool.

## 3. Cross-product requirements

### 3.1 Enterprise identity and authorization

- Production reference systems operate as an authenticated user and enforce the
  user's permissions. Salesforce applies object, field, and sharing permissions;
  GitHub tools inherit repository/feature access; Stripe recommends OAuth or
  restricted keys; Atlassian partitions read, write, and search permissions.
- The offline mock has no credentials. Tenant isolation is represented by a
  single seeded company and explicit entity identifiers.
- A tool must never silently broaden its target. Every mutation acts only on the
  supplied identifier and rejects missing entities.

### 3.2 Auditability

- Every mutating result returns the primary entity identifier and new observable
  state.
- Support comments/notes and explicit knowledge audit events provide durable
  evidence for multi-system workflows.
- Verifiers bind exact requested values, not just broad completion states.

### 3.3 Error behavior

- Missing required fields return `validation_error`.
- Unknown identifiers return `not_found`.
- Invalid lifecycle transitions return `precondition_failed`.
- Duplicate or already-completed operations return `conflict` where applicable.
- Tool execution errors are observable results and are not reclassified as model
  failures without checking environment ownership.

## 4. Salesforce CRM product requirements

### 4.1 Product intent

Salesforce Hosted MCP gives agents governed access to Salesforce records and
automation. The SObject servers support schema discovery, query/search, record
reads, mutations, and relationship traversal under the authenticated user's
existing Salesforce permissions.

### 4.2 Core entities

| entity | required fields in the mock | reference analogue |
|---|---|---|
| account | id, name, segment, owner, health, renewal state, onboarding state | Salesforce Account plus organization-specific fields |
| contact | id, account, name, email, role | Salesforce Contact |
| interaction | id, account, kind, summary, timestamp | Activity/custom timeline object |

### 4.3 Tool contract

| mock tool | label | reference capability | required behavior |
|---|---|---|---|
| `search_crm_accounts` | transformed | SObject search/query | Match account id or name; return bounded results. |
| `search_crm_employees` | transformed | SObject search/query over the User object | Company directory: filter people by department, authority role and status so policy-named parties resolve to a person. |
| `get_crm_account` | transformed | record read | Return one account or `not_found`. |
| `update_crm_owner` | aligned | record update | Require an existing account and active employee; persist the exact owner id. |
| `create_crm_contact` | aligned | record create | Require an existing account; enforce unique email; return created id. |
| `update_crm_account_health` | lab extension | custom field update | Restrict health to green/amber/red and persist the exact classification. |
| `add_crm_interaction` | transformed | Activity/custom action | Append, never overwrite, an exact kind and summary. |

### 4.4 CRM invariants

- Account identifiers are immutable.
- A contact cannot reference a missing account.
- Contact email is unique within the world.
- Owner changes must preserve referential integrity.
- Timeline interactions are append-only.
- Health changes are observable final state, never inferred from prose.

### 4.5 CRM acceptance scenarios

1. Searching by `acct-001` returns only matching account records.
2. Updating an existing account owner changes only that account.
3. Updating a missing account fails and leaves all accounts unchanged.
4. Creating a contact twice with the same email produces one record plus a
   conflict.
5. A verifier that changes the wrong account id must receive reward 0.

### 4.6 Known Salesforce deltas

- Generic tools replace Salesforce's schema-first SObject tool vocabulary.
- The mock omits SOQL, delete, relationship traversal, field-level permissions,
  sharing rules, Flow, Apex, Data 360, and Tableau.
- `health` and `interaction` are company-specific concepts presented as custom
  fields/actions, not claimed standard Salesforce objects.
- `search_crm_employees` is a benchmark discovery surface over a company employee
  directory, not a claim about a standard Salesforce object. It exists because
  delegation, ownership and code-review clauses name a party by department and
  authority role, and without a directory search those ids are reachable only by
  trying employees until one is accepted.

## 5. Zendesk Support product requirements

### 5.1 Product intent

Zendesk tickets are the agent-facing record of a customer request. Vendor
documentation defines ticket priority, status, requester context, comments,
internal notes, create/update operations, and audit records. The Northstar
support server preserves the operational subset needed for escalation and
resolution workflows.

### 5.2 Core entities and lifecycle

| entity | required fields | lifecycle |
|---|---|---|
| ticket | id, account, subject, status, priority, owner, links, resolution | `open → resolved` |
| internal note | id, ticket, body, visibility | append-only |

Zendesk uses states such as new, open, pending, hold, solved, and closed. The
mock intentionally collapses these to open/resolved. `resolved` corresponds to
the benchmark's completed state and must not be presented as exact Zendesk
status parity.

### 5.3 Tool contract

| mock tool | label | reference capability | required behavior |
|---|---|---|---|
| `search_support_tickets` | transformed | ticket list/search | Search id, subject, or account and optionally filter open/resolved. |
| `get_support_ticket` | aligned | show ticket | Return all workflow fields or `not_found`. |
| `create_support_ticket` | aligned | create ticket | Require a valid account; persist exact subject and priority. |
| `update_support_priority` | aligned | update ticket | Persist low/normal/high/critical; `critical` maps to Zendesk urgent semantics. |
| `add_support_internal_note` | aligned | private ticket comment | Append exact body with internal visibility. |
| `update_support_resolution` | transformed | update status/comment | Atomically store exact resolution and move open → resolved. |

### 5.4 Support invariants

- Notes never replace earlier notes.
- Resolution text is part of the requested outcome and must match exactly.
- Cross-system issue/PR links are bidirectional when the linking tool promises
  both sides.
- Updating a missing ticket cannot create one implicitly.

### 5.5 Support acceptance scenarios

1. A new normal-priority concierge ticket is returned by open-ticket search.
2. An internal note is visible to state verification but distinct from public
   content.
3. A resolved ticket stores the exact requested resolution.
4. A wrong priority, wrong note body, or wrong ticket id receives reward 0.

### 5.6 Known Zendesk deltas

- This is a REST-derived support mock; no official Zendesk MCP parity is claimed.
- Requesters, submitters, groups, collaborators, macros, triggers, custom
  statuses, attachments, safe updates, and asynchronous bulk jobs are omitted.
- `critical` and `resolved` are normalized benchmark terms.

## 6. Stripe Billing product requirements

### 6.1 Product intent

Stripe MCP exposes invoice discovery and refund creation among a broader set of
customer, product, price, subscription, dispute, and knowledge tools. Stripe's
invoice API defines invoice retrieval and lifecycle states. Northstar narrows
this to finance-remediation workflows and adds explicit hold/release policy
steps.

### 6.2 Core entities and lifecycle

| entity | required fields | lifecycle |
|---|---|---|
| invoice | id, account, amount, status, hold reason, payment reference, refund total | `open ↔ on_hold`; `open → paid` |
| refund | id, invoice, amount, reason, approval status | append approved refund |

`on_hold` is a Northstar finance-policy state, not a claim that Stripe invoices
use the same native status. Stripe's documented invoice states include draft,
open, paid, uncollectible, and void.

### 6.3 Tool contract

| mock tool | label | reference capability | required behavior |
|---|---|---|---|
| `list_billing_invoices` | aligned | `list_invoices` | Filter by account and return bounded invoice records. |
| `get_billing_invoice` | transformed | resource fetch/invoice retrieve | Return one invoice or `not_found`. |
| `update_billing_hold` | lab extension | internal collection policy | Reject paid invoices; store exact hold reason. |
| `update_billing_release` | lab extension | internal collection policy | Require on_hold; clear hold reason and return open state. |
| `update_billing_payment` | transformed | invoice payment outcome | Require open state; store exact payment reference; transition to paid. |
| `create_billing_refund` | aligned | `create_refund` | Reject amounts above remaining refundable balance; preserve exact reason. |

### 6.4 Billing invariants

- A held invoice cannot be paid until explicitly released.
- A paid invoice cannot be held.
- Total approved refunds cannot exceed invoice amount.
- Hold reason, refund reason, amount, and payment reference are exact verifier
  inputs.
- Failed transitions leave state unchanged.

### 6.5 Billing acceptance scenarios

1. Paying a held invoice without release returns `precondition_failed`.
2. Release followed by payment yields `paid:<payment_ref>`.
3. A refund with the wrong amount or reason receives reward 0.
4. Omitting hold, release, payment, or refund from a task that requests it must
   kill the verifier mutant.

### 6.6 Known Stripe deltas

- The mock does not implement PaymentIntents, customers, subscriptions, products,
  prices, disputes, idempotency keys, webhooks, currency, tax, or asynchronous
  settlement.
- `update_billing_hold`, `update_billing_release`, and
  `update_billing_payment` are deterministic workflow wrappers, not names from
  Stripe's documented MCP catalog.

## 7. GitHub engineering product requirements

### 7.1 Product intent

GitHub's maintained MCP server exposes repository, issue, pull-request, action,
security, and related toolsets. Tool access inherits the corresponding GitHub
feature and repository permissions. Northstar preserves the repository →
issue/PR coordination subset.

### 7.2 Core entities and lifecycle

| entity | required fields | lifecycle |
|---|---|---|
| repository | id, name, owner, default branch | immutable seed record |
| issue | id, repository, title, status, priority, linked ticket | `open → closed` (close is not exposed in v1) |
| pull request | id, repository, status, reviewer, linked ticket, merge SHA | `open → review_requested → merged` |

### 7.3 Tool contract

| mock tool | label | reference capability | required behavior |
|---|---|---|---|
| `search_engineering_repositories` | transformed | repository search/list | Search id or name with bounded results. |
| `search_engineering_pull_requests` | aligned | list pull requests | Enumerate a repository's pull requests with lifecycle filters; the discovery surface for PR ids. |
| `get_engineering_pull_request` | aligned | pull-request read | Return lifecycle and link fields or `not_found`. |
| `create_engineering_issue` | aligned | issue create | Require repository; persist exact title, priority, and support link. |
| `update_engineering_ticket_link` | lab extension | issue/PR metadata integration | Write PR→ticket and ticket→PR links atomically. |
| `update_engineering_review` | transformed | request review | Require an open PR and active reviewer; transition to review_requested. |
| `update_engineering_merge` | transformed | merge pull request | Require review_requested; store exact merge SHA; transition to merged. |

### 7.4 Engineering invariants

- An issue must be created in the requested repository, not merely linked to the
  right ticket.
- A pull request cannot merge before review is requested.
- Merge SHA and reviewer are exact requested outcomes.
- Bidirectional links must remain consistent.

### 7.5 Engineering acceptance scenarios

1. Creating an issue in a different valid repository receives reward 0.
2. Merging an open, unreviewed PR returns `precondition_failed`.
3. Review then merge preserves reviewer and exact SHA.
4. Linking a ticket changes both entities in one transaction.

### 7.6 Known GitHub deltas

- Numeric IDs, owner/repo coordinates, branches, commits, reviews, comments,
  checks, merge methods, draft state, labels, pagination, and GitHub permission
  scopes are simplified or omitted.
- Priority and support-ticket links are benchmark fields, not standard GitHub
  issue/PR fields.

## 8. Atlassian Confluence/Rovo knowledge requirements

### 8.1 Product intent

Atlassian Rovo MCP separates common, Jira, Confluence, and search tools into
permission groups. Its Confluence surface includes page search, page retrieval,
page creation/update, comments, spaces, and descendants. Northstar preserves
search/read/update and adds compliance records required by cross-system tasks.

### 8.2 Core entities and lifecycle

| entity | required fields | lifecycle |
|---|---|---|
| document | id, title, kind, status, version, body | `draft → published` |
| policy acknowledgement | document, employee, timestamp | append once per pair |
| audit finding | id, account, status, severity, evidence document | `open → closed` |
| audit event | entity type/id, action, detail, timestamp | append-only |

### 8.3 Tool contract

| mock tool | label | reference capability | required behavior |
|---|---|---|---|
| `search_knowledge_documents` | transformed | CQL/Rovo search | Search id, title, or body; optionally filter kind. |
| `get_knowledge_document` | aligned | get Confluence page | Return exact status, version, and body or `not_found`. |
| `update_knowledge_runbook` | transformed | update Confluence page | Publish exact body/version on an existing document. |
| `create_knowledge_policy_ack` | lab extension | compliance workflow | Require published document and active employee; remain unique per pair. |
| `update_knowledge_finding` | lab extension | compliance workflow | Require published evidence; close the exact finding against that document. |
| `create_knowledge_audit_event` | lab extension | enterprise audit log | Append an event for the exact entity type, id, and action. |

### 8.4 Knowledge invariants

- Document body and version are exact requested outcomes.
- Acknowledgement and finding closure require a published document.
- A finding records the evidence document used to close it.
- Audit events are append-only and bind entity type as well as entity id.

### 8.5 Knowledge acceptance scenarios

1. Publishing the wrong body or version receives reward 0.
2. A draft document cannot acknowledge policy or close a finding.
3. An audit event on the right id but wrong entity type receives reward 0.
4. Repeating the same acknowledgement does not create duplicates.

### 8.6 Known Atlassian deltas

- Spaces, parent/child pages, Atlassian document format, comments, Jira,
  Teamwork Graph, cloud IDs, CQL syntax, OAuth scopes, and Rovo inference are
  omitted.
- Acknowledgements, findings, and audit events are lab extensions inspired by
  enterprise governance, not native Confluence MCP tool names.

## 9. Composite workflow requirements

The composite host exposes all five bounded surfaces without merging their
state ownership. Cross-product tasks must pass identifiers explicitly.

The anchors in the final column substantiate the component capabilities, not
customer adoption of the full sequence.

| workflow | required system sequence | required terminal evidence | component research anchors |
|---|---|---|---|
| customer recovery | CRM + Support | account green, ticket escalated/resolved, exact interaction | `src-salesforce-mcp`, `src-salesforce-sobject-all-guide`, `src-zendesk-tickets-api` |
| billing remediation | Support + Billing | exact hold/refund/note/resolution | `src-zendesk-tickets-api`, `src-stripe-mcp`, `src-stripe-invoice-object` |
| incident response | Engineering + Support + Knowledge | critical ticket, repository-bound issue, exact runbook, audit | `src-github-mcp-server`, `src-zendesk-tickets-api`, `src-atlassian-rovo-supported-tools` |
| release coordination | Support + GitHub | bidirectional link, reviewer, exact merge SHA, resolution | `src-zendesk-tickets-api`, `src-github-mcp-server`, `src-github-rest-pulls` |
| compliance audit | Knowledge | exact publication, acknowledgement, finding evidence, audit | `src-atlassian-rovo-supported-tools` |
| account onboarding | CRM + Support + Knowledge | owner/contact/ticket/document/ack/interaction | `src-salesforce-mcp`, `src-zendesk-tickets-api`, `src-atlassian-rovo-supported-tools` |
| security triage | GitHub + Support + Knowledge | critical ticket/issue, review, exact runbook, finding evidence | `src-github-mcp-server`, `src-zendesk-tickets-api`, `src-atlassian-rovo-supported-tools` |
| knowledge maintenance | Support + Knowledge | exact document/note/resolution/audit | `src-zendesk-tickets-api`, `src-atlassian-rovo-supported-tools` |
| revenue retention | CRM + Support + Billing | release prerequisite, exact payment, owner/health/resolution/interaction | `src-salesforce-mcp`, `src-zendesk-tickets-api`, `src-stripe-mcp` |
| executive escalation | all five | critical/hold/review/health/audit evidence | all vendor-primary anchors above |

## 10. Product-parity acceptance gate

A release is admissible only when:

1. All 32 tools compile and advertise their input/output schemas.
2. Every mutation enforces identifier and lifecycle preconditions.
3. Every user-requested exact value has a final-state assertion.
4. The untouched seed fails every assertion.
5. All 100 canonical oracles pass.
6. All 100 alternate plans that omit only read operations pass.
7. Every single required-mutation omission is rejected.
8. Every wrong valid target or requested value is rejected.
9. No environment-owned tool errors appear in successful or fixture replays.
10. Product deltas remain explicit; generic tools are never represented as
    vendor-exact implementations.

## 11. Out of scope

- Live vendor accounts, credentials, customer data, rate limits, webhooks, or
  vendor SLAs.
- Full parity with any product's API or MCP server.
- Vendor trademarks as endorsements.
- Hidden product behavior not supported by primary documentation.
- Treating registry pages or community servers as more authoritative than
  vendor documentation.