@llamaventures/cli 1.22.1 → 1.23.1

package/AGENT_BRIEFING.md

@@ -66,6 +66,7 @@ A teammate says "I just met them and heard…" or pastes a chunk of notes. Your
 2. **Split what they gave you into two kinds** — this is the whole data model:
    - **A source packet with 2+ facts, or facts + a note → ingest once.** Build a JSON object with `source`, `facts`, and optional `note`, then run `llama deal ingest <dealId> --file <packet.json>`. This is the preferred agent path: one atomic, deduplicated, retry-safe commit. Reuse an explicit `idempotencyKey` when retrying the same material. The matching MCP tool is `deal_ingest` and uses the same packet shape.
    - **Verifiable claims → facts.** `llama deal fact add <dealId> --category <cat> --claim "…" --source "<where it came from>" --source-url <url>`. A claim someone *relayed* ("their ARR is $3M", "raised from a16z") is a fact at **unverified** trust — it's hearsay until checked. Pass `--attested` ONLY if you actually verified it against a source yourself. In raw API terms, the fact text field is `claim` (`value` is only a compatibility alias), `source` is the human-readable provenance label, and `sourceUrl` is the canonical URL.
+     - **Trust and contest are separate axes.** A *contested* fact is excluded from what the Deal Agent treats as current, whatever its trust rung — so a fact can read as both `human-vouched` and suppressed. `fact verify --status confirmed` does **not** lift a contest; the response tells you when one is still standing. To lift one: `llama deal fact uncontest <dealId> <factId> --reason "…"`. The lifted contest is kept in the fact's history, not erased.
    - **Their judgment / impression → a note.** `llama post <dealId> "…"`. "Founder seemed evasive", "I'd lean pass", "worth a second meeting" — opinion, not fact. Attributed, never "verified".
    - A pasted blob → pull the verifiable claims out as facts, capture their take as a note.
 3. **Read it back before you claim it's saved.** A generic tool call returning `{ok:true}` is NOT proof the content is where the user will look for it. `deal ingest` is the exception because its response is built from the rows and note block read back after commit: confirm `createdFacts`, `skippedFacts`, `note`, and `summary` in that receipt. For every other write, run `llama deal feed <dealId>` and confirm your fact/note actually appears. Never say "记好了 / saved" from a request acknowledgment alone — the #1 failure is an agent writing to the wrong surface (e.g. the brief, which is the Memo and does NOT appear in the feed) and reporting success anyway. If the authoritative ingest receipt or the feed read-back does not contain the material, fix it before reporting success.
@@ -217,6 +218,7 @@ llama deal create "Company" --description "..." --source-direction Outbound --st
 llama deal create "Company" --description "..." --source-direction Outbound --status Outreached --deal-owner "owner@llamaventures.vc"
 llama deal create "Company" --description "..." --source-direction Inbound --status Sourced --deal-owner "Exact Name"
 llama deal update <dealId> <field> <value>
+llama deal fact uncontest <dealId> <factId> --reason "..."   # lift a wrong contest; verify does NOT
 #   writable: status theirStage stage notes dealOwner source sourceDirection description website
 #             location founders proposedAmount roundSize valuation sector subsector
 #             foundedYear leadInvestor investors   (each write logs a deal_events row)

package/CHANGELOG.md

@@ -6,6 +6,48 @@ 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
+- `llama deal fact uncontest <dealId> <factId> --reason "..."` lifts a contest
+  that turned out to be wrong. Contesting a fact removes it from what the Deal
+  Agent treats as current, and until now nothing could put it back — so a true
+  claim contested on weak evidence stayed suppressed in every regenerated brief
+  and memo. The lifted contest is kept in the fact's history server-side, not
+  erased. Requires Llama Command >= 3.21.0.
+
+### Changed
+- `--help` and `AGENT_BRIEFING.md` now state that **trust and contest are
+  separate axes**: `fact verify --status confirmed` does NOT lift a contest, and
+  a contested fact stays excluded from synthesis whatever its trust rung. The
+  server now returns a warning when a verify leaves a contest standing.
+- `deal update` help says what `notes` is for — the one-line Summary headline at
+  the top of the deal page (~280 chars), not a place for meeting notes. It was
+  previously listed among 20 field names with no semantics, so the honest
+  reading was "notes" and long text landed in a headline slot.
+
+### Note
+This release also carries the unpublished 1.22.2 fix below.
+
+## [1.22.2] - 2026-08-04
+
+### Fixed
+- `llama claim` and `llama nominate` now require `--reason` and send it to
+  Llama Command's audited Owner-label endpoint. The CLI no longer emits a
+  request that Core must reject before recording the responsibility change.
+
 ## [1.22.1] - 2026-08-04
 
 ### Changed

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;
@@ -457,8 +478,7 @@ server.registerTool(
   {
     description:
       "Create a new pipeline deal. Source defaults to the caller's user record. " +
-      "Owner assignment goes through the partner-approval queue (status: pending) " +
-      "until a partner approves it via /partner/approvals.",
+      "Owner is an audited responsibility label, not an operating-permission boundary.",
     inputSchema: {
       companyName: z.string(),
       description: z.string().optional().describe("one-liner: what they do"),
@@ -495,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.",
@@ -505,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,12 +391,14 @@ 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.
+      'notes' is the ONE-LINE judgment shown as the Summary headline at the top of
+      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"
@@ -415,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>]
@@ -446,12 +461,12 @@ Deal links (separate from brief link blocks — these live in deal_links):
   llama deal link restore <dealId> <linkId>
 
 Ownership:
-  llama claim <dealId>                                       # propose self as owner
-  llama nominate <dealId> --user <userId>                    # partner nominates someone else
-  llama nominations list                                     # pending nominations for me
-  llama nominations decide <approvalId> accepted|declined    # accept/decline a nomination
+  llama claim <dealId> --reason "..."                        # set yourself as Owner
+  llama nominate <dealId> --user <userId> --reason "..."     # set another teammate as Owner
+  Owner is an audited responsibility label, not a permission boundary. Any
+  internal teammate can change it after Partner Support; reason is mandatory.
 
-Approvals (partner queue — self-claim approvals):
+Approvals (Partner queue — contribution decisions):
   llama approvals list
   llama approvals decide <approvalId> approved|rejected [--note "..."]
 
@@ -503,6 +518,9 @@ Deal facts (AI-extracted or human-asserted, with verification):
   llama deal fact list <dealId>
   llama deal fact add <dealId> --category <cat> --claim "<text>" [--source "..."] [--source-url <url>] [--confidence high|medium|low] [--attested]
   llama deal fact verify <dealId> <factId> --status confirmed|disputed [--corrected-value "..."]
+  llama deal fact uncontest <dealId> <factId> --reason "<why the contest was wrong>"
+    contest and trust are separate axes: 'verify --status confirmed' does NOT lift a contest,
+    and a contested fact stays excluded from what the Deal Agent treats as current.
 
 Mentions / Inbox:
   llama mentions                                       # default: my unresolved cues
@@ -1440,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>");
@@ -1458,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;
   }
@@ -1491,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) {
@@ -1826,7 +1909,29 @@ async function main() {
       return;
     }
 
-    throw new Error(`Unknown fact sub-command "${sub}". Use list, add, or verify.`);
+    // Lift a contest that turned out to be wrong. Contesting a claim removes
+    // it from everything the Deal Agent treats as current; before this existed
+    // there was no way back, so a TRUE claim contested on weak evidence stayed
+    // suppressed in every regenerated brief and memo. `verify --status
+    // confirmed` does NOT do this — trust and contest are separate axes.
+    if (sub === "uncontest") {
+      const factId = rest[2];
+      const reason = flags.reason !== undefined && flags.reason !== true ? String(flags.reason).trim() : "";
+      if (!factId || !reason) {
+        throw new Error(
+          `Usage: llama deal fact uncontest <dealId> <factId> --reason "<why the contest was wrong>"`
+        );
+      }
+      // @core-api-operation POST /api/deals/{dealId}/facts/{factId}/uncontest
+      print(await request(
+        "POST",
+        `/api/deals/${encodeURIComponent(dealId)}/facts/${encodeURIComponent(factId)}/uncontest`,
+        { reason }
+      ));
+      return;
+    }
+
+    throw new Error(`Unknown fact sub-command "${sub}". Use list, add, verify, or uncontest.`);
   }
 
   // ----- Brief refresh: trigger stale-section re-eval watcher run -----
@@ -1890,12 +1995,16 @@ async function main() {
   // ----- Ownership: self-claim -----
   if (area === "claim") {
     const dealId = action; // second positional
-    if (!dealId) throw new Error("Usage: llama claim <dealId>");
+    const { flags } = parseFlags(rest, ["reason"]);
+    const reason = typeof flags.reason === "string" ? flags.reason.trim() : "";
+    if (!dealId || !reason) {
+      throw new Error('Usage: llama claim <dealId> --reason "<why this person should own it>"');
+    }
     const me = await request("GET", "/api/me");
     print(await request(
       "POST",
       `/api/deals/${encodeURIComponent(dealId)}/propose-owner`,
-      { userId: me.id }
+      { userId: me.id, reason }
     ));
     return;
   }
@@ -1903,15 +2012,16 @@ async function main() {
   // ----- Ownership: partner nominates someone else -----
   if (area === "nominate") {
     const dealId = action;
-    const { flags } = parseFlags(rest);
+    const { flags } = parseFlags(rest, ["user", "reason"]);
     const userId = Number(flags.user);
-    if (!dealId || !Number.isFinite(userId)) {
-      throw new Error("Usage: llama nominate <dealId> --user <userId>");
+    const reason = typeof flags.reason === "string" ? flags.reason.trim() : "";
+    if (!dealId || !Number.isFinite(userId) || !reason) {
+      throw new Error('Usage: llama nominate <dealId> --user <userId> --reason "<why>"');
     }
     print(await request(
       "POST",
       `/api/deals/${encodeURIComponent(dealId)}/propose-owner`,
-      { userId }
+      { userId, reason }
     ));
     return;
   }

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"
@@ -186,6 +194,10 @@
       "method": "PATCH",
       "path": "/api/deals/{dealId}/facts/{factId}"
     },
+    {
+      "method": "POST",
+      "path": "/api/deals/{dealId}/facts/{factId}/uncontest"
+    },
     {
       "method": "GET",
       "path": "/api/deals/{dealId}/feed"

package/lib/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "1.22.1",
-  "sourceSha": "3280cbaa5ef4ea18ac3ecff7785d15112f9e9fdb",
+  "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.22.1",
+  "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",