@llamaventures/cli 1.23.0 → 1.23.1

package/CHANGELOG.md

@@ -6,6 +6,18 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.23.1] - 2026-08-05
+
+### Added
+- Add the canonical `llama workflow` command family and typed MCP tools for
+  reading and changing Investment Workflow V2 through one versioned API.
+- Add audited workflow initialization for legacy migration and formal post-IC
+  execution status updates for Term Sheet, Verbal Commit, and Invested.
+
+### Changed
+- Reject direct Deal status writes and retired `stage_gates` / `stage4_gate`
+  mutations so CLI and MCP cannot bypass the server state machine.
+
 ## [1.23.0] - 2026-08-05
 
 ### Added

package/README.md

@@ -100,7 +100,10 @@ llama activity updated-deals --since 7d # meaningful updates grouped by deal
 llama deal create "Acme AI" --source alex --deal-owner owner@llamaventures.vc --source-direction Outbound --status Interested
 llama deal ingest <dealId> --file packet.json  # atomic multi-fact + optional Feed note; retry-safe
 llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
-llama deal update <dealId> status Diligence
+llama workflow show <dealId>
+llama workflow initialize <dealId> --reason "Migrate legacy workflow state without changing stage"
+llama workflow proceed <dealId> --transition begin_preliminary --reason "Ready to begin research"
+llama workflow execution-status <dealId> invested --reason "Wire confirmed"
 llama post <dealId> "note body"
 llama post <dealId> "@name please respond" --cue  # only after explicit approval
 llama brief add-text <dealId> --heading "..." --body "..."
@@ -115,6 +118,10 @@ Status vocabulary — `Interested`: tracked before any contact ·
 signal exists. `sourceDirection` is separate: `Inbound` came to the firm,
 `Outbound` we reached out first.
 
+Deal stage is controlled only by Investment Workflow V2. Direct
+`deal update ... status ...` and legacy `stage_gates` writes are rejected;
+use `llama workflow show` followed by the matching formal workflow command.
+
 For a deck, meeting note, email, or research packet, prefer `deal ingest` over a
 loop of `deal fact add` calls. The JSON object accepts `source`, up to 50
 `facts`, an optional `note`, and an optional `idempotencyKey`. The server commits

package/README.zh-CN.md

@@ -122,7 +122,10 @@ llama activity updated-deals --since 7d # 按 deal 聚合的实质更新
 llama deal create "Acme AI" --source alex --deal-owner owner@llamaventures.vc --source-direction Outbound --status Interested
 llama deal ingest <dealId> --file packet.json  # 多条 facts + 可选 Feed note，一次提交且可安全重试
 llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
-llama deal update <dealId> status Diligence
+llama workflow show <dealId>
+llama workflow initialize <dealId> --reason "迁移旧状态，不改变当前阶段"
+llama workflow proceed <dealId> --transition begin_preliminary --reason "开始初步研究"
+llama workflow execution-status <dealId> invested --reason "已确认打款"
 llama post <dealId> "备注内容"
 llama post <dealId> "@name 请回复" --cue  # 仅在用户明确授权后使用
 llama brief add-text <dealId> --heading "..." --body "..."

package/bin/llama-mcp.mjs

@@ -74,6 +74,27 @@ function jsonResult(value, isError = false) {
   return textResult(JSON.stringify(value, null, 2), isError);
 }
 
+async function callWorkflow(dealId, type, fields) {
+  try {
+    const path = `/api/deals/${encodeURIComponent(dealId)}/workflow`;
+    // @core-api-operation GET /api/deals/{dealId}/workflow
+    const current = await request("GET", path);
+    const expectedRevision = current?.workflow?.revision;
+    if (!Number.isInteger(expectedRevision)) {
+      return textResult("Error: Investment Workflow V2 is not initialized for this deal.", true);
+    }
+    // @core-api-operation POST /api/deals/{dealId}/workflow
+    return callApi("POST", path, {
+      type,
+      requestId: `mcp:${type}:${randomUUID()}`,
+      expectedRevision,
+      ...fields,
+    });
+  } catch (err) {
+    return textResult(`Error: ${err?.message ?? String(err)}`, true);
+  }
+}
+
 function splitSources(value) {
   if (Array.isArray(value)) return value.filter(Boolean);
   if (!value || value === true) return undefined;
@@ -494,7 +515,7 @@ server.registerTool(
   "deal_update",
   {
     description:
-      "Update a single whitelisted field on a deal. Writable fields: status, theirStage, " +
+      "Update a single non-workflow field on a deal. Writable fields: theirStage, " +
       "notes, stage, dealOwner, source, sourceDirection, description, website, location, founders, " +
       "proposedAmount, roundSize, valuation, sector, subsector, foundedYear, leadInvestor, " +
       "investors. Logs a field_change event in deal_events.",
@@ -504,8 +525,93 @@ server.registerTool(
       value: z.union([z.string(), z.number(), z.null()]).describe("new value"),
     },
   },
-  async ({ dealId, field, value }) =>
-    callApi("POST", "/api/deals/update", { dealId, field, value })
+  async ({ dealId, field, value }) => {
+    if (field === "status") {
+      return textResult("Error: Direct status writes are retired. Use the workflow_* tools.", true);
+    }
+    return callApi("POST", "/api/deals/update", { dealId, field, value });
+  }
+);
+
+server.registerTool(
+  "workflow_show",
+  {
+    description: "Read the canonical Investment Workflow V2 state, revision, current transition, and blockers for a deal.",
+    inputSchema: { dealId: z.string() },
+  },
+  async ({ dealId }) => callApi("GET", `/api/deals/${encodeURIComponent(dealId)}/workflow`),
+);
+
+server.registerTool(
+  "workflow_initialize",
+  {
+    description: "Persist the canonical Investment Workflow V2 bootstrap state for an unmigrated deal without changing its semantic stage. Intended for audited migration and recovery.",
+    inputSchema: { dealId: z.string(), reason: z.string().min(1) },
+  },
+  async ({ dealId, reason }) => callWorkflow(dealId, "initialize", { reason }),
+);
+
+server.registerTool(
+  "workflow_request_partner_support",
+  {
+    description: "Submit a formal Partner Support request. Core refuses it until every current stage requirement is satisfied or waived.",
+    inputSchema: { dealId: z.string(), partnerId: z.string(), reason: z.string().min(1) },
+  },
+  async ({ dealId, partnerId, reason }) => callWorkflow(dealId, "request_partner_support", { partnerId, reason }),
+);
+
+server.registerTool(
+  "workflow_decide_partner_support",
+  {
+    description: "Record the named Partner's own Support, Need more, or Pass decision. Core verifies caller identity; never use on another person's behalf.",
+    inputSchema: { dealId: z.string(), decision: z.enum(["support", "need_more", "pass"]), reason: z.string().min(1) },
+  },
+  async ({ dealId, decision, reason }) => callWorkflow(dealId, "partner_support_decision", { decision, reason }),
+);
+
+server.registerTool(
+  "workflow_proceed",
+  {
+    description: "Apply the current formal workflow transition. Core re-evaluates every guard atomically.",
+    inputSchema: { dealId: z.string(), transitionKey: z.string(), reason: z.string().min(1) },
+  },
+  async ({ dealId, transitionKey, reason }) => callWorkflow(dealId, "proceed", { transitionKey, reason }),
+);
+
+server.registerTool(
+  "workflow_resolve_guard",
+  {
+    description: "Record an audited workflow guard resolution. Waivers require a concrete reason and remain visible in history.",
+    inputSchema: { dealId: z.string(), guardKey: z.string(), status: z.enum(["satisfied", "unsatisfied", "waived"]), reason: z.string().min(1) },
+  },
+  async ({ dealId, guardKey, status, reason }) => callWorkflow(dealId, "resolve_guard", { guardKey, status, reason }),
+);
+
+server.registerTool(
+  "workflow_control",
+  {
+    description: "Hold, resume, pass, restore, or return a deal through the canonical workflow control path.",
+    inputSchema: { dealId: z.string(), action: z.enum(["hold", "resume", "pass", "restore", "return"]), reason: z.string().min(1), holdDisposition: z.enum(["stalled", "future"]).optional() },
+  },
+  async ({ dealId, action, reason, holdDisposition }) => callWorkflow(dealId, "control", { action, reason, ...(holdDisposition ? { holdDisposition } : {}) }),
+);
+
+server.registerTool(
+  "workflow_vote",
+  {
+    description: "Cast the signed-in Partner's own Formal IC vote through Investment Workflow V2.",
+    inputSchema: { dealId: z.string(), vote: z.enum(["yes", "no"]), reason: z.string().min(1) },
+  },
+  async ({ dealId, vote, reason }) => callWorkflow(dealId, "cast_vote", { vote, reason }),
+);
+
+server.registerTool(
+  "workflow_update_execution_status",
+  {
+    description: "Update the canonical post-IC execution status. Available only after the formal IC decision.",
+    inputSchema: { dealId: z.string(), executionStatus: z.enum(["Term Sheet", "Verbal Commit", "Invested"]), reason: z.string().min(1) },
+  },
+  async ({ dealId, executionStatus, reason }) => callWorkflow(dealId, "update_execution_status", { executionStatus, reason }),
 );
 
 // ============================================================

package/bin/llama.mjs

@@ -391,7 +391,7 @@ Deals:
   llama deal show <dealId>
   llama deal feed <dealId>                                     # every contribution (facts + notes), human-typed or assistant-drafted, newest first
   llama deal update <dealId> <field> <value>
-      Writable fields: status, theirStage, stage, notes, dealOwner, source, sourceDirection,
+      Writable fields: theirStage, stage, notes, source, sourceDirection,
       description, website, location, founders, founderInfo, proposedAmount,
       roundSize, valuation, deckLink, folderUrl, sector, subsector,
       foundedYear, leadInvestor, investors, agentActive.
@@ -399,7 +399,6 @@ Deals:
       the deal page (~280 chars). Meeting notes and narrative go in a comment
       (llama post); verifiable claims go in facts (llama deal fact add).
       e.g.  llama deal update <dealId> website https://acme.ai
-            llama deal update <dealId> status Interested
             llama deal update <dealId> sector "Developer Tools"
             llama deal update <dealId> foundedYear 2024
             llama deal update <dealId> leadInvestor "Acme Capital"
@@ -418,6 +417,19 @@ Deals:
                             [--limit 200] [--offset 0]
   llama deal list [--owner ...] [--status ...] [...same flags as search]
 
+Investment Workflow V2 (the only stage-write surface):
+  llama workflow show <dealId>
+  llama workflow initialize <dealId> --reason "..."   # audited legacy migration/bootstrap
+  llama workflow request-support <dealId> --partner <userId> --reason "..."
+  llama workflow decide-support <dealId> support|need_more|pass --reason "..."
+  llama workflow proceed <dealId> --transition <key> --reason "..."
+  llama workflow waive <dealId> --guard <key> --reason "..."
+  llama workflow control <dealId> hold|resume|pass|restore|return --reason "..." [--disposition stalled|future]
+  llama workflow organize-ic <dealId> --note "..."
+  llama workflow vote <dealId> yes|no --reason "..."
+  llama workflow reassign-owner <dealId> --owner <userId> --reason "..."
+  llama workflow execution-status <dealId> term-sheet|verbal-commit|invested --reason "..."
+
 Agent activity (read-only, cheap read model over append-only activity):
   llama activity new-deals [--since 24h|7d|<ISO>] [--limit 50]
   llama activity updated-deals [--since 24h|7d|<ISO>] [--limit 50] [--deal <uuid>]
@@ -1446,6 +1458,65 @@ async function main() {
     return;
   }
 
+  if (area === "workflow") {
+    const dealId = rest[0];
+    if (!dealId) throw new Error("Usage: llama workflow show|initialize|request-support|decide-support|proceed|waive|control|organize-ic|vote|reassign-owner|execution-status <dealId> [...flags]");
+    if (action === "show") {
+      print(await request("GET", `/api/deals/${encodeURIComponent(dealId)}/workflow`));
+      return;
+    }
+    const { flags, positional } = parseFlags(rest.slice(1));
+    const current = await request("GET", `/api/deals/${encodeURIComponent(dealId)}/workflow`);
+    const expectedRevision = current?.workflow?.revision;
+    if (!Number.isInteger(expectedRevision)) {
+      throw new Error("This deal has no initialized Investment Workflow V2 state. Open its workflow panel once, then retry.");
+    }
+    const base = {
+      requestId: `cli:${action}:${randomUUID()}`,
+      expectedRevision,
+    };
+    let command;
+    if (action === "initialize") {
+      if (!flags.reason) throw new Error('Usage: llama workflow initialize <dealId> --reason "..."');
+      command = { ...base, type: "initialize", reason: String(flags.reason) };
+    } else if (action === "request-support") {
+      if (!flags.partner || !flags.reason) throw new Error('Usage: llama workflow request-support <dealId> --partner <userId> --reason "..."');
+      command = { ...base, type: "request_partner_support", partnerId: String(flags.partner), reason: String(flags.reason) };
+    } else if (action === "decide-support") {
+      const decision = positional[0];
+      if (!["support", "need_more", "pass"].includes(decision) || !flags.reason) throw new Error('Usage: llama workflow decide-support <dealId> support|need_more|pass --reason "..."');
+      command = { ...base, type: "partner_support_decision", decision, reason: String(flags.reason) };
+    } else if (action === "proceed") {
+      if (!flags.transition || !flags.reason) throw new Error('Usage: llama workflow proceed <dealId> --transition <key> --reason "..."');
+      command = { ...base, type: "proceed", transitionKey: String(flags.transition), reason: String(flags.reason) };
+    } else if (action === "waive") {
+      if (!flags.guard || !flags.reason) throw new Error('Usage: llama workflow waive <dealId> --guard <key> --reason "..."');
+      command = { ...base, type: "resolve_guard", guardKey: String(flags.guard), status: "waived", reason: String(flags.reason) };
+    } else if (action === "control") {
+      const control = positional[0];
+      if (!["hold", "resume", "pass", "restore", "return"].includes(control) || !flags.reason) throw new Error('Usage: llama workflow control <dealId> hold|resume|pass|restore|return --reason "..." [--disposition stalled|future]');
+      command = { ...base, type: "control", action: control, reason: String(flags.reason), ...(flags.disposition ? { holdDisposition: String(flags.disposition) } : {}) };
+    } else if (action === "organize-ic") {
+      if (!flags.note) throw new Error('Usage: llama workflow organize-ic <dealId> --note "..."');
+      command = { ...base, type: "organize_ic", note: String(flags.note) };
+    } else if (action === "vote") {
+      const vote = positional[0];
+      if (!["yes", "no"].includes(vote) || !flags.reason) throw new Error('Usage: llama workflow vote <dealId> yes|no --reason "..."');
+      command = { ...base, type: "cast_vote", vote, reason: String(flags.reason) };
+    } else if (action === "reassign-owner") {
+      if (!flags.owner || !flags.reason) throw new Error('Usage: llama workflow reassign-owner <dealId> --owner <userId> --reason "..."');
+      command = { ...base, type: "reassign_owner", ownerId: String(flags.owner), ownerName: "resolved by server", reason: String(flags.reason) };
+    } else if (action === "execution-status") {
+      const status = { "term-sheet": "Term Sheet", "verbal-commit": "Verbal Commit", invested: "Invested" }[positional[0]];
+      if (!status || !flags.reason) throw new Error('Usage: llama workflow execution-status <dealId> term-sheet|verbal-commit|invested --reason "..."');
+      command = { ...base, type: "update_execution_status", executionStatus: status, reason: String(flags.reason) };
+    } else {
+      throw new Error(`Unknown workflow command "${action || ""}".`);
+    }
+    print(await request("POST", `/api/deals/${encodeURIComponent(dealId)}/workflow`, command));
+    return;
+  }
+
   if (area === "deal" && action === "show") {
     const dealId = rest[0];
     if (!dealId) throw new Error("Usage: llama deal show <dealId>");
@@ -1464,6 +1535,9 @@ async function main() {
     const [dealId, field, ...valueParts] = rest;
     const value = valueParts.join(" ");
     if (!dealId || !field) throw new Error("Usage: llama deal update <dealId> <field> <value>");
+    if (field === "status") {
+      throw new Error("Direct status writes are retired. Use `llama workflow show <dealId>` and a formal `llama workflow ...` command.");
+    }
     print(await request("POST", "/api/deals/update", { dealId, field, value }));
     return;
   }
@@ -1497,6 +1571,9 @@ async function main() {
     const sub = rest[0];
     const dealId = rest[1];
     const key = rest[2];
+    if (["stage_gates", "stage4_gate"].includes(key)) {
+      throw new Error(`Legacy ${key} is retired. Use \`llama workflow ...\` commands.`);
+    }
     if (sub === "set") {
       const raw = rest.slice(3).join(" ");
       if (!dealId || !key || !raw) {

package/contracts/core-api.json

@@ -1,9 +1,9 @@
 {
   "format": "llama.core-api-contract.v1",
   "name": "llama-core-api",
-  "apiVersion": "3.5.0",
+  "apiVersion": "3.23.0",
   "openapiVersion": "3.0.3",
-  "sha256": "31c7d23ee06bd4282aa2451698604cc30df4792d4a0e9674593a809b4eb55767",
-  "pathCount": 216,
-  "operationCount": 281
+  "sha256": "b959a28605693097ba8d8d9345729070d54fcce08f004abcfe9b8c2fd2dabc6d",
+  "pathCount": 233,
+  "operationCount": 304
 }

package/contracts/investment-workflow-v2.md

@@ -0,0 +1,19 @@
+# Investment Workflow V2 client contract
+
+CLI and MCP treat `GET/POST /api/deals/{dealId}/workflow` as the only workflow
+read/write surface. A write must first read the current revision, submit one
+typed command with a unique request id, and display the canonical response.
+
+Never add a client shortcut that writes `deals.status`,
+`extra.investment_workflow_v2` snapshots, `extra.stage_gates`, or
+`extra.stage4_gate`. Partner
+decisions are always made by the authenticated Partner; admin capability does
+not imply permission to impersonate a decision maker.
+
+`workflow initialize` is the audited bootstrap command for legacy migration.
+It persists the state returned by `workflow show` without advancing a stage or
+resolving a guard. Never translate legacy approvals into V2 approvals silently.
+
+Post-IC compatibility status is also owned by V2. Use `workflow
+execution-status` / `workflow_update_execution_status` for Term Sheet, Verbal
+Commit, and Invested; never reopen direct `deal update ... status` writes.

package/contracts/required-operations.json

@@ -78,6 +78,14 @@
       "method": "GET",
       "path": "/api/deals/{dealId}"
     },
+    {
+      "method": "GET",
+      "path": "/api/deals/{dealId}/workflow"
+    },
+    {
+      "method": "POST",
+      "path": "/api/deals/{dealId}/workflow"
+    },
     {
       "method": "POST",
       "path": "/api/deals/{dealId}/agent-runs/{runId}/revert"

package/lib/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "1.23.0",
-  "sourceSha": "3f3fb4ae90469e4c561bc8ad319c59d877d0fcf2",
+  "packageVersion": "1.23.1",
+  "sourceSha": "8d5824095c03137b224bdbff50bc6be144d37486",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "3.5.0",
+    "apiVersion": "3.23.0",
     "openapiVersion": "3.0.3",
-    "sha256": "31c7d23ee06bd4282aa2451698604cc30df4792d4a0e9674593a809b4eb55767"
+    "sha256": "b959a28605693097ba8d8d9345729070d54fcce08f004abcfe9b8c2fd2dabc6d"
   }
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@llamaventures/cli",
-  "version": "1.23.0",
+  "version": "1.23.1",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {
     "test": "npm run test:agent-routing && npm run test:contract",
     "test:agent-routing": "node scripts/verify-agent-routing.mjs",
-    "test:contract": "node --test scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/server-compatibility.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
+    "test:contract": "node --test scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/investment-workflow-contract.test.mjs scripts/server-compatibility.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
     "verify:artifact": "node scripts/verify-release-artifact.mjs",
     "verify:release": "npm test && npm run verify:artifact && node scripts/verify-tarball-clean.mjs",
     "prepack": "node scripts/prepare-build-manifest.mjs",