@figs-so/cli 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -9,6 +9,35 @@ as **one versioned thing.** When a newer CLI runs, `figs status` / `doctor` / `i
 baked stance is behind and point here; read from your baseline forward, refresh the file you load each
 session, then `figs init --yes` to re-stamp. Newest first.
 
+## 1.6.0 — coherent asks + a coherent org chart
+
+*2026-06-14*
+
+Two coherence fixes: the ask⇄answer contract is enforced, and departments converge at link.
+
+**The ask⇄answer contract, enforced — not just advised.** Options belong to questions, verdicts to
+sign-offs — they can't overlap, so a "double verdict" (cite one path, rule another) is impossible.
+
+- **Sign-offs take no options.** `figs ask sign-off --option` is **refused** — a sign-off's answer is
+  the verdict (approve / request-changes / reject); an option there only restates one. What approval
+  sets in motion stays `--on-approve`; any caveat rides in the reply note.
+- **A verdict cites no option.** `figs answer --approve` / `--request-changes` / `--reject` no longer
+  accepts `--chosen` (that pairing *was* the contradiction). `--chosen` is question-only.
+- **Guide + spec say so.** `GUIDE.md` and `SPEC.md` now mark `options` question-only and `chosen`
+  answer-only. The `.figs` schema is unchanged and stays **`figs-spec v2`** — a tightening of what the
+  verbs mint, not a wire change; existing records still validate and render.
+
+**Departments converge at `figs link`.** `department` is free-text you author locally, before any
+workspace exists — so independently-built agents drift ("Member Retention" vs "Member Success" vs
+"Member Ops") and the org chart fragments into columns of one.
+
+- **Link surfaces the workspace's departments** and compares them to your `agent.json#org.department`:
+  confirms a match, flags yours as new (with the existing list to pick from), or prompts when it's unset.
+- **Print-only — you reconcile your own charter.** Link never writes `agent.json`; you adopt an existing
+  department and push. No app-side merge/rename, no new flag — just a nudge at the one connected moment.
+- **Spec unchanged**, still **`figs-spec v2`** — `department` was already free-text; this is link-time
+  guidance, not a wire change.
+
 ## 1.5.0 — Figs as your operating system
 
 *2026-06-14*

package/GUIDE.md

@@ -197,7 +197,9 @@ description of who you are.
    agent never logs in**; auth is the human's job. Already set up on this machine? `figs status` says so
    — **skip straight to `figs link`** (don't re-run `login`). The flow: `figs login` → `figs link`
    (connect to a workspace; bare lists them, or `--workspace <slug>`) → `figs push`. Nothing recorded
-   before linking is lost — push sends it all.
+   before linking is lost — push sends it all. **`figs link` prints the workspace's existing
+   departments** — reconcile `agent.json#org.department` to one before you push, so you land in the
+   right org-chart column instead of a column of one.
 
 > **After your first `figs push`, stop.** This is the moment your user sees you appear. Give them the
 > link — **`<endpoint>/w/<workspaceId>`** (in `config.json`; `figs push` prints it) — ask them to look,
@@ -217,7 +219,7 @@ CLI attaches it on push.
 | `status` | | Free text — **your lifecycle**: `"in_dev"` while being built, `"active"` once operating (flip it when you start real work). Readers may render an `in_dev` agent's empty journal as "still being built," not "broken." |
 | `mandate` | | **Your charter** — one sentence: what you're accountable for. Shown loudest. |
 | `avatar` | | `{ "seed": "<string>" }` — seeds your avatar. |
-| `org` | | `{ "department": "..." }` — **`department` groups you on the org chart.** |
+| `org` | | `{ "department": "..." }` — **`department` groups you on the org chart.** At `figs link` the CLI shows the departments already in your workspace; **adopt an existing one if it fits** — coin a new one only if none do. Coherent grouping is the whole point of the chart. |
 | `runtime` | | e.g. `"Claude Code"`. |
 | `cadence` | | e.g. `"Monthly"`. |
 | `steps` | | `string[]` — your **fixed, ordered procedure**, numbered. Only if your work has one. |
@@ -402,14 +404,20 @@ figs ask question --title 'No bridge rule for prefixed invoice numbers' \
 - **`to`**: `"manager"` (accountable for your *work*) · `"builder"` (maintains *you* — broken, creds,
   self-edit flags). Omit if genuinely either.
 - `found` / `need` — **the case**: what you saw, what you need back. Write these so a *stranger* (the
-  human deciding, and the future session acting) can act from the ask **alone**. `options[]` — **short,
-  stable, quotable** candidate answers (a reply cites one *verbatim*) — and **only when there are
-  discrete paths to choose**: a clear standalone question (`how much did we spend in May?`) needs none.
-  Options are *candidates, not a cage* — **your human may also reply in free text**, so `found`/`need`
-  must stand on their own. On a **sign-off**, options are answer paths (`"Approved — file the 15 ready
-  charges"`), and **`--on-approve '<step>'`** (repeatable, ordered) states what approval sets in motion
-  — an approval authorizes exactly those steps; flag anything irreversible. `--attach` the **exact
-  content to approve** (a verdict blesses what the ask carries).
+  human deciding, and the future session acting) can act from the ask **alone**.
+- **Options are question-only — and so is the answer⇄verdict split, so get the type right.**
+  - On a **question**, `options[]` are **short, stable, quotable** candidate answers (a reply cites one
+    *verbatim*) — and **only when there are discrete paths to choose**: a clear standalone question
+    (`how much did we spend in May?`) needs none. Options are *candidates, not a cage* — **your human may
+    also reply in free text**, so `found`/`need` must stand on their own.
+  - On a **sign-off**, the answer is the **verdict** (approve / request-changes / reject) — that *is*
+    the choice, so a sign-off takes **no options.** An option on a sign-off just restates a verdict
+    (`"Hold"`, `"Reject"`, `"Approve as written"`) — the human already has those buttons, and citing
+    one path while ruling another is a contradiction. `figs ask sign-off --option` is **refused.**
+    Instead, **`--on-approve '<step>'`** (repeatable, ordered) states what approval sets in motion — an
+    approval authorizes exactly those steps; flag anything irreversible. Any caveat ("approve, but only
+    the 15") rides in the reply note, not an option. `--attach` the **exact content to approve** (a
+    verdict blesses what the ask carries).
 - For long texts, `--stdin` a JSON object. The line it writes:
 
 ```json
@@ -441,9 +449,10 @@ Figs app. Either way you bring the reply into the record and act on it:
   figs answer acme-bridge --chosen 'Strip the alpha prefix' --by 'Sarah (accounting)'
   ```
 
-  `--by` names the **human** who said it (not you). `--chosen` is checked verbatim against the ask's
-  options. On a sign-off use `--approve` / `--request-changes` / `--reject` (a qualified verdict may
-  also carry `--chosen`). **Transcribe their words — never author the reply yourself.**
+  `--by` names the **human** who said it (not you). On a **question**, `--chosen` is checked verbatim
+  against the ask's options (or `--text` for free text). On a **sign-off** use `--approve` /
+  `--request-changes` / `--reject` — the verdict *is* the answer; it **takes no `--chosen`** (any caveat
+  goes in `--text`). **Transcribe their words — never author the reply yourself.**
 
 - **Then act, then close.** `figs close` is a **pure close** — it reads the newest reply on file and
   derives the outcome, citing it:

package/SPEC.md

@@ -82,7 +82,7 @@ and the CLI attaches it on push. Everything else is optional and rendered when p
 | `avatar` | `{ seed: string }` | | Seed for the generated avatar. |
 | `role` | string | | Short title, e.g. "Reconciliation Officer". |
 | `status` | string | | Free-text lifecycle, e.g. `in_dev`, `active`. |
-| `org` | `{ department?: string }` | | `department` groups the agent into an org-chart column. |
+| `org` | `{ department?: string }` | | `department` groups the agent into an org-chart column. Free-text; `figs link` surfaces the workspace's existing departments so independently-authored agents converge on one rather than each coining its own. |
 | `runtime` | string | | What runs it, e.g. "Claude Code". |
 | `cadence` | string | | How often it runs, e.g. "Monthly". |
 | `mandate` | string | | One-paragraph statement of what it's responsible for. |
@@ -172,7 +172,7 @@ edge of its autonomy.
 | `run` | string | | The run `id` this ask was raised during. **Optional** — asks also arise outside runs. |
 | `found` | string | | What the agent found / why it's stuck. |
 | `need` | string | | What it needs from the human. |
-| `options` | string[] | | Candidate answers — **short, stable, quotable** strings: a reply cites one *verbatim* (§6.2). On a **sign-off** they are qualified-verdict paths (e.g. `"Approved — file the 15 ready charges"`). |
+| `options` | string[] | | **Question-only.** Candidate answers — **short, stable, quotable** strings: a reply cites one *verbatim* (§6.2). **Invalid on a `sign-off`** — a sign-off's answer is the verdict (approve / request-changes / reject), so an option there only restates a verdict; `figs ask sign-off --option` is refused. What approval triggers is `onApprove`. |
 | `onApprove` | string[] | | **Sign-off only.** The ordered steps approval sets in motion — **an approval authorizes exactly these steps, in order**; flag anything irreversible in the step. The agent's declared intent, not a bound plan. Invalid on a `question`. |
 | `details` | `{ l, v }[]` | | Labelled facts (e.g. amount at risk). |
 | `attachments` | string[] | | File names under `artifacts/` attached to this ask (the exact content to review — §7). |
@@ -203,7 +203,7 @@ The close is derived from the newest reply on the ask and cites it.
 | Field | Type | Meaning |
 |---|---|---|
 | `note` | string | The agent's one-line account of the close. |
-| `chosen` | string | The decision taken — **verbatim** one of the ask's `options[]` (copied from the cited reply). |
+| `chosen` | string | The option taken — **verbatim** one of the ask's `options[]`, copied from the cited reply. **Question closes only** (a verdict carries no `chosen`). |
 | `run` | string | The job the reply set in motion (mirror of `ask.run`) — so a reader can navigate answer → work → outcome. |
 | `via` | `"figs"` \| `"human"` \| `"self"` | How it closed: `figs` = derived from a reply on file, citing it (`answer`) · `human` = an out-of-band reply with no event cited · `self` = the blocker cleared on its own. |
 | `answer` | string | The `messages.jsonl` event id the close acted on — written by `figs close` (attribution by mechanism, never typed). **Trust derives from that event's mint origin** (§6.3), not from this field. |
@@ -225,9 +225,9 @@ immutable, ids minted once, they **accumulate** (no fold) — an ask can carry a
 | `by` | string | ✓ | Who said it (the human). |
 | `ts` | string (ISO-8601 w/ offset) | ✓ | Machine-stamped (server clock for reader-minted, CLI clock for transcribed). |
 | `source` | `"app"` \| `"chat"` \| … | | **Where the reply arrived** (display metadata, *not* trust) — `app` = in the reader, `chat` = transcribed by the agent. Extensible (`slack`, `email`, …). |
-| `chosen` | string | | The option cited, **verbatim** from the ask's `options[]`. |
-| `text` | string | | Free-text reply. |
-| `verdict` | `"approved"` \| `"changes-requested"` \| `"rejected"` | | On a `verdict` message. |
+| `chosen` | string | | **Answer-only.** The option cited, **verbatim** from the ask's `options[]`. A `verdict` message carries no `chosen` (options are question-only; the verdict is the whole answer). |
+| `text` | string | | Free-text reply (an answer, or a caveat riding with a verdict). |
+| `verdict` | `"approved"` \| `"changes-requested"` \| `"rejected"` | | On a `verdict` message (a sign-off ruling). `rejected` is also the human-side close of any open ask. |
 
 **The trust rule (normative):** a reader derives the *verified* grade from **mint origin** — a message
 the reader minted itself is attested; a message that arrived via push (transcribed by an agent) is

package/figs.mjs

@@ -130,6 +130,8 @@ const COMMANDS = {
       "needed; get it from the app). --endpoint overrides the destination (default app.figs.so).",
       "Verifies the workspace when you're logged in; a UUID set while logged out is accepted",
       "but unverified until your first `figs push`. Writes endpoint + workspaceId into config.json.",
+      "Shows the departments already in the workspace — adopt an existing one in agent.json#org.department",
+      "if it fits (coherent org-chart grouping is the point); only coin a new one if none do.",
       "To unlink, delete those two fields from .figs/config.json (your identity + work stay).",
     ],
     eg: "figs link --workspace acme-corp",
@@ -198,16 +200,16 @@ const COMMANDS = {
       "sign-off (give me a verdict). Two types — the type IS the contract.",
       "Two strangers read every ask — a human deciding, a future session acting;",
       "the record must carry everything both need: --found (what you saw), --need",
-      "(what you need), --option (repeatable; short, stable, quotable — answers cite",
-      "one verbatim; the option is the label, context goes in --found/--detail),",
-      "--detail 'Label=Value' (repeatable), --attach <file> (repeatable; a verdict",
-      "blesses what the ask carries — attach the exact content for review + a brief:",
-      "what to do once approved and what it requires).",
-      "On a sign-off, --option entries are answer paths — the human's verdict can",
-      "cite one verbatim ('Approved — file the 15 ready charges') — and",
-      "--on-approve '<step>' (repeatable, ordered; sign-off only) states what",
-      "approval sets in motion: an approval authorizes exactly the steps you stated.",
-      "Flag anything irreversible in the step itself.",
+      "(what you need), --detail 'Label=Value' (repeatable), --attach <file>",
+      "(repeatable; a verdict blesses what the ask carries — attach the exact content",
+      "for review + a brief: what to do once approved and what it requires).",
+      "QUESTION → --option (repeatable; short, stable, quotable — a reply cites one",
+      "verbatim; the option is the label, context goes in --found/--detail). Options are",
+      "candidates, not a cage — your human may also free-text. Options are QUESTION-ONLY.",
+      "SIGN-OFF → the answer is the VERDICT (approve / request-changes / reject); it takes",
+      "NO --option (an option there just restates a verdict). --on-approve '<step>'",
+      "(repeatable, ordered; sign-off only) states what approval sets in motion: an",
+      "approval authorizes exactly those steps. Flag anything irreversible in the step.",
       "--run <run-id> links the run this came out of — explicit id only (other",
       "sessions may report concurrently; `figs report` prints the id it wrote).",
       "--stdin reads a full JSON object instead of flags (long texts; attachments still via --attach).",
@@ -227,8 +229,8 @@ const COMMANDS = {
       "type commands; you transcribe what they said. --by names the HUMAN who said it, not you.",
       "question → --chosen '<option verbatim>' (checked against the ask's options) or",
       "--text '<what they said>'. sign-off → --approve | --request-changes | --reject",
-      "(a qualified verdict may also carry --chosen). Transcribe verbatim — never summarize,",
-      "never author the reply yourself.",
+      "(a verdict cites no option — put any caveat in --text). Transcribe verbatim —",
+      "never summarize, never author the reply yourself.",
       "Just don't RE-transcribe a reply that already came through the app: it's attested and",
       "syncs down on its own (figs inbox), and a re-typed copy would downgrade it — so answer",
       "REFUSES if the ask already has an app reply (--force only for a separate out-of-band one).",
@@ -1169,14 +1171,19 @@ async function link() {
   const token = getToken()
 
   let workspaceId
+  // The resolved workspace row (carries `departments` for the convergence
+  // nudge below). Absent only on the logged-out-UUID path — we can't fetch it.
+  let matched
   if (wsArg && isUuid(wsArg)) {
     workspaceId = wsArg
     if (token) {
       // Verify access when we can; a network blip just defers it to first push.
       const r = await request("GET", "/api/workspaces", null, token)
-      if (r.ok && !(r.data.workspaces ?? []).some((w) => w.id === wsArg)) {
+      const got = (r.data.workspaces ?? []).find((w) => w.id === wsArg)
+      if (r.ok && !got) {
         die(`workspace ${wsArg} isn't one you can access — run \`figs link\` (no flag) to list yours`)
       }
+      matched = got
     } else {
       console.warn("figs: ! linked by UUID while logged out — unverified until your first `figs push`")
     }
@@ -1190,6 +1197,7 @@ async function link() {
     const match = (r.data.workspaces ?? []).find((w) => w.slug === wsArg || w.id === wsArg)
     if (!match) die(`no workspace matching "${wsArg}" — run \`figs link\` (no flag) to list yours`)
     workspaceId = match.id
+    matched = match
   } else {
     // Bare `figs link` — list; with exactly one, link it outright.
     if (!token) {
@@ -1201,6 +1209,7 @@ async function link() {
     if (list.length === 0) die(`no workspaces yet — create one at ${endpoint}, then re-run \`figs link\``)
     if (list.length === 1) {
       workspaceId = list[0].id
+      matched = list[0]
       console.log(`figs: linking to ${list[0].slug} (${list[0].name})`)
     } else {
       console.log("figs: which workspace? re-run with one:")
@@ -1216,9 +1225,50 @@ async function link() {
     JSON.stringify({ agentId: config.agentId, endpoint, workspaceId }, null, 2) + "\n",
   )
   console.log(`figs: ✓ linked — workspace ${workspaceId} @ ${endpoint}`)
+  printDepartmentGuidance(matched)
   console.log("        next: `figs push` publishes everything recorded so far")
 }
 
+/**
+ * Steer department convergence at the one connected moment. `department` is
+ * free-text the agent authors locally (account-free, before any workspace
+ * exists) — so independently-authored agents drift ("Member Retention" vs
+ * "Member Success" vs "Member Ops") and the org chart fragments. Link is where
+ * we can finally compare the local charter against what the workspace already
+ * uses and nudge the agent to adopt an existing department. Print-only: the
+ * agent reconciles its own `agent.json` (link never writes the charter). Skips
+ * silently when we couldn't fetch the workspace (logged-out UUID) or an older
+ * app didn't return `departments`.
+ */
+function printDepartmentGuidance(workspace) {
+  if (!workspace || !Array.isArray(workspace.departments)) return
+  const existing = workspace.departments.filter(Boolean)
+  const raw = readJson(join(repoDir, "agent.json"), {})?.org?.department
+  const mine = typeof raw === "string" ? raw.trim() : ""
+  // A `<…>` stub or empty value isn't a real choice yet.
+  const unset = !mine || mine.includes("<")
+  const list = existing.join(" · ")
+
+  if (existing.length === 0) {
+    console.log(
+      unset
+        ? "        no departments here yet — you're the first; set agent.json#org.department to a broad team name"
+        : `        first department here — you're starting "${mine}"`,
+    )
+    return
+  }
+  const hit = existing.find((d) => d.toLowerCase() === mine.toLowerCase())
+  if (hit) {
+    console.log(`        ✓ department "${hit}" — grouping with the rest of the workspace`)
+  } else if (!unset) {
+    console.log(`        ! department "${mine}" is new here. Existing: ${list}`)
+    console.log("          → if one fits, set agent.json#org.department to match — coherent grouping is the point")
+  } else {
+    console.log(`        departments here: ${list}`)
+    console.log("          → set agent.json#org.department to one (or a new one if none fit)")
+  }
+}
+
 async function init() {
   // Purely local — `init` never touches the network, so it can never need an
   // account. The one gate is consent, not connectivity: Figs turns a repo into a
@@ -1708,6 +1758,14 @@ async function answerCmd() {
 
   const chosen = flag("--chosen")
   const text = flag("--text")
+  // A verdict cites no option — options are question-only. On a sign-off the verdict
+  // (approve / request-changes / reject) is the whole answer; pairing it with --chosen
+  // is the "double verdict" (cite one path, rule another). Refuse it at the mint point.
+  if (verdicts.length && chosen) {
+    die(
+      "a verdict cites no option — options are for questions. On a sign-off the verdict (approve / request-changes / reject) is the whole answer; put any caveat in --text '<note>'",
+    )
+  }
   const msg = {
     id: genId("msg"),
     kind: verdicts.length ? "verdict" : "answer",
@@ -2062,6 +2120,17 @@ async function askCmd() {
   if (!ask.to) ask.to = "manager"
   const options = flagAll("--option")
   if (options.length) ask.options = options
+  // Options are question-only: they're candidate answers a reply cites. A sign-off's
+  // answer is the VERDICT (approve / request-changes / reject) — never an option. An
+  // option on a sign-off restates a verdict ("Hold", "Reject") and lets a reader cite
+  // one verdict while clicking another. Refuse it at the authoring mint point. (Catches
+  // --stdin options too — ask.options is the merged value.) What approval triggers goes
+  // in --on-approve; any caveat rides in the reply note.
+  if (ask.options?.length && ask.type === "sign-off") {
+    die(
+      "--option is sign-off-illegal: options are for questions (a reply cites one). A sign-off's answer is the verdict (approve / request-changes / reject) — put what approval sets in motion in --on-approve, and any caveat in the reply note",
+    )
+  }
   for (const o of ask.options ?? []) {
     if (o.length > 80) {
       console.warn(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {