@adrata/adrata-mcp 1.0.49 → 1.0.50

package/tools/threads/work-proposition-tools.js

@@ -0,0 +1,417 @@
+/**
+ * Proposition tools, the one graph read, and Galaxy document filing.
+ *
+ * A PROPOSITION is a claim about the world we act on ("enterprise buyers will
+ * pay for provable control") — the theory-of-change assumption, the leap of
+ * faith, the forecast. It is SHARED: many decisions and strategies rest on
+ * it, evidence updates it in one place, and when it falls everything that
+ * assumed it lights up (`standing: rests_on_falsified` on a linked decision,
+ * `at_risk` on a linked strategy, both derived on read). Its doctrine:
+ *
+ *   - A proposition with no FALSIFIER is a slogan; the falsifier is required.
+ *   - `confidence` on the row is the latest READING's value. It is never edited
+ *     directly: every change is a reading with its evidence and source, so the
+ *     history is a calibration record.
+ *   - Moving to `contested` or `falsified` needs a reading with evidence; the
+ *     API refuses the status change without one.
+ *   - A replacement is a NEW proposition with `supersedesPropositionId`; the
+ *     old row keeps its readings and its discussion.
+ *
+ * The GRAPH read is one route, any root (`<kind>:<id>`), walked both ways to
+ * a depth, as JSON or as a mermaid document an agent can paste into a Stream,
+ * a card or a decision body.
+ *
+ * DOCUMENTS: every noun can file a Galaxy document with a role (memo,
+ * outcome, evidence, source, artifact) and a reason, on
+ * `POST/DELETE /{family}/{id}/documents[/{documentId}]`.
+ *
+ * See work-thread-tools.js for the model and CONTRACT.md ("Propositions: the
+ * fifth noun", "Thread graphs you can generate", "Galaxy, and the ontology as
+ * the core of the system") for the routes.
+ */
+
+import {
+  AUDIENCES,
+  DOCUMENT_FAMILY_PATHS,
+  DOCUMENT_ROLES,
+  DOCUMENT_TARGET_TYPES,
+  GOVERNED_NOTE,
+  PROPOSITION_EVIDENCE_STATUSES,
+  PROPOSITION_LINK_TARGET_TYPES,
+  PROPOSITION_STATUSES,
+  THREAD_GRAPH_DEFAULT_DEPTH,
+  THREAD_GRAPH_FORMATS,
+  THREAD_GRAPH_MAX_NODES,
+  THREAD_GRAPH_ROOT_KINDS,
+  audienceQuery,
+  buildQuery,
+  compactBody,
+  governedArgs,
+  mermaidText,
+  parseGraphRoot,
+  validateBody,
+  validateConfidence,
+  validateDate,
+  validateDepth,
+  validateEnum,
+  validateReason,
+  validateStateReason,
+} from './shared.js';
+
+const BASE = '/api/v1/work-propositions';
+const GRAPH_PATH = '/api/v1/work-threads/graph';
+
+/** A required free-text field: non-blank, under the body ceiling. Trimmed. */
+function requiredText(value, field) {
+  const text = validateBody(value, field).trim();
+  if (!text) throw new Error(`${field} is required and cannot be blank`);
+  return text;
+}
+
+export function registerWorkPropositionTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+) {
+  server.tool(
+    'list_propositions',
+    'List propositions — the claims about the world we act on — each with its statement, status (proposed | supported | contested | falsified | superseded), current confidence 0-1 (the latest reading), its falsifier, audience, review date and how many goals, decisions, ideas and indicators rest on it. Pass targetType + targetId to see what one node ASSUMES. Read supersedesPropositionId to walk a replaced claim.',
+    {
+      status: z.enum(PROPOSITION_STATUSES).optional().describe('Narrow to one lifecycle status.'),
+      audience: z.array(z.enum(AUDIENCES)).optional().describe('Narrow to these audiences. Omit for all.'),
+      targetType: z.enum(PROPOSITION_LINK_TARGET_TYPES).optional().describe('With targetId: only the propositions this node rests on.'),
+      targetId: z.string().optional().describe('With targetType: the node id.'),
+    },
+    async (args) => {
+      if ((args.targetType && !args.targetId) || (!args.targetType && args.targetId)) {
+        throw new Error('targetType and targetId go together');
+      }
+      const query = buildQuery({
+        status: args.status,
+        audience: audienceQuery(args.audience),
+        targetType: args.targetType,
+        targetId: args.targetId,
+      });
+      const data = await api('GET', `${BASE}${query}`);
+      const items = data?.data || [];
+      return ok({ count: items.length, items });
+    }
+  );
+
+  server.tool(
+    'get_proposition',
+    'Read one proposition whole: statement, rationale, falsifier, status, the confidence HISTORY as readings (each with its evidence, source and when it was observed; the latest is current), everything that rests on it (the linked goals, decisions, ideas and indicators with their reasons), the Galaxy documents filed on it, and the proposition it supersedes or is superseded by.',
+    {
+      propositionId: z.string().describe('Proposition id from list_propositions.'),
+    },
+    async (args) => {
+      const data = await api('GET', `${BASE}/${encodeURIComponent(args.propositionId)}`);
+      const proposition = data?.data ?? null;
+      if (!proposition) return ok({ proposition: null });
+      const readings = Array.isArray(proposition.readings) ? proposition.readings : [];
+      const links = Array.isArray(proposition.links) ? proposition.links : [];
+      return ok({ readingCount: readings.length, linkCount: links.length, proposition });
+    }
+  );
+
+  server.tool(
+    'get_proposition_calibration',
+    'Read how well a person\'s stated confidence on propositions has matched how they resolved: the count stated, how many have resolved (supported or falsified), a Brier score once ten have resolved (null before that, with the count shown instead), and the split. Stated confidence at first reading is what is scored. Omit userId for the caller. Decision quality and outcome quality are shown side by side, never merged.',
+    {
+      userId: z.string().optional().describe('Whose calibration. Defaults to the caller.'),
+    },
+    async (args) => {
+      const query = buildQuery({ userId: args.userId });
+      const data = await api('GET', `${BASE}/calibration${query}`);
+      return ok({ userId: args.userId ?? null, calibration: data?.data ?? null });
+    }
+  );
+
+  server.tool(
+    'state_proposition',
+    `State a proposition — a claim about the world we act on — as PROPOSED: the statement as one sentence, the rationale, the FALSIFIER (the observation that would show it false; required, because a proposition with no falsifier is a slogan), the initial confidence 0-1 (recorded as the first reading, so calibration can score it later), audience and a review date. To replace a claim, state a NEW one with supersedesPropositionId — the old one moves to superseded and keeps its readings; never edit the old statement. Link what rests on it with link_proposition afterwards.${GOVERNED_NOTE}`,
+    {
+      statement: z.string().describe('The claim as one sentence, e.g. "sellers will not type into a CRM".'),
+      rationale: z.string().optional().describe('Why we believe it, markdown. Defaults to empty.'),
+      confidence: z.number().min(0).max(1).optional().describe('Stated probability it is true, 0-1. Becomes the first reading.'),
+      falsifier: z.string().describe('The observation that would show it false. Required.'),
+      audience: z.enum(AUDIENCES).describe('Who this claim is about or for.'),
+      reviewOn: z.string().optional().describe('When to re-read the claim against the evidence, YYYY-MM-DD.'),
+      supersedesPropositionId: z.string().optional().describe('The proposition this one replaces; it moves to superseded.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      validateEnum(args.audience, AUDIENCES, 'audience');
+      const body = compactBody({
+        statement: requiredText(args.statement, 'statement'),
+        rationale: args.rationale === undefined ? undefined : validateBody(args.rationale, 'rationale'),
+        confidence: validateConfidence(args.confidence),
+        falsifier: requiredText(args.falsifier, 'falsifier'),
+        audience: args.audience,
+        reviewOn: validateDate(args.reviewOn, 'reviewOn'),
+        supersedesPropositionId: args.supersedesPropositionId,
+      });
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path: BASE,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldCreate: body });
+      const data = await api('POST', BASE, { body, headers: buildMutationHeaders(args) });
+      return ok({ created: true, proposition: data?.data });
+    }
+  );
+
+  server.tool(
+    'record_proposition_reading',
+    `Append a reading to a proposition: the confidence 0-1 you now hold, the EVIDENCE that moved it (required — a confidence change with no evidence is a mood), the source the evidence was read from, and when it was observed (defaults to now). The row's confidence becomes this value; it is never edited any other way, so the readings ARE the calibration record. Readings are appended, never edited — a wrong reading is corrected by a new one that says so. Each call adds one row; do not retry with a fresh idempotencyKey. Record a reading BEFORE moving a proposition to contested or falsified: the API refuses those without one.${GOVERNED_NOTE}`,
+    {
+      propositionId: z.string().describe('Proposition id from list_propositions.'),
+      confidence: z.number().min(0).max(1).describe('The probability you now hold that the claim is true, 0-1.'),
+      evidence: z.string().describe('What was observed that moved the confidence. Required. Markdown.'),
+      source: z.string().describe('Where the evidence came from — a call, a document, a query, a run id. Required.'),
+      observedAt: z.string().optional().describe('ISO-8601 timestamp of the observation. Defaults to now.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      if (args.confidence === undefined || args.confidence === null) throw new Error('confidence is required, a number from 0 to 1');
+      const confidence = validateConfidence(args.confidence);
+      const evidence = requiredText(args.evidence, 'evidence');
+      const source = requiredText(args.source, 'source');
+      const path = `${BASE}/${encodeURIComponent(args.propositionId)}/readings`;
+      const body = compactBody({ confidence, evidence, source, observedAt: args.observedAt });
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldCreate: { propositionId: args.propositionId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders(args) });
+      return ok({ recorded: true, propositionId: args.propositionId, proposition: data?.data });
+    }
+  );
+
+  server.tool(
+    'set_proposition_status',
+    `Move a proposition through its lifecycle: proposed → supported, or to contested (the evidence cuts both ways) or falsified (the falsifier was observed). contested and falsified REQUIRE a reading with evidence first — record_proposition_reading, then this — and the API refuses the move without one. A falsified proposition marks every linked decision standing: rests_on_falsified and every linked strategy at_risk on read: that is the point of the noun. For superseded, prefer state_proposition with supersedesPropositionId, which does it in one transaction. The reason is recorded on the transition and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      propositionId: z.string().describe('Proposition id from list_propositions.'),
+      status: z.enum(PROPOSITION_STATUSES).describe('The new status.'),
+      ...governedArgs(z),
+      reason: z.string().describe('Why the status changes. Recorded on the transition; also the audit reason.'),
+    },
+    async (args) => {
+      validateEnum(args.status, PROPOSITION_STATUSES, 'status');
+      const reason = validateStateReason(args.status, args.reason);
+      const path = `${BASE}/${encodeURIComponent(args.propositionId)}`;
+      const body = { status: args.status, reason };
+      const preview = validateApiBridgeRequest({
+        method: 'PATCH',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldChange: { propositionId: args.propositionId, ...body },
+          needsReadingWithEvidence: PROPOSITION_EVIDENCE_STATUSES.has(args.status),
+        });
+      }
+      const data = await api('PATCH', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({ updated: true, proposition: data?.data });
+    }
+  );
+
+  server.tool(
+    'link_proposition',
+    `Say that a node ASSUMES this proposition: a goal (or strategy), a decision, an idea or an indicator rests on this claim. An edge with a reason; the target does not change. When the proposition is falsified, the linked decision and strategy are marked on read. Linking a pair that is already linked replaces the reason (an upsert on the pair). The reason is recorded on the link and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      propositionId: z.string().describe('Proposition id from list_propositions.'),
+      targetType: z.enum(PROPOSITION_LINK_TARGET_TYPES).describe('What kind of node rests on the claim.'),
+      targetId: z.string().describe('The node id (from list_goals, list_decisions, list_ideas or list_indicators).'),
+      ...governedArgs(z),
+      reason: z.string().describe('How that node rests on this claim, in a sentence. Recorded on the link; also the audit reason.'),
+    },
+    async (args) => {
+      validateEnum(args.targetType, PROPOSITION_LINK_TARGET_TYPES, 'targetType');
+      if (!String(args.targetId ?? '').trim()) throw new Error('targetId is required');
+      const reason = validateReason(args.reason);
+      const path = `${BASE}/${encodeURIComponent(args.propositionId)}/links`;
+      const body = { targetType: args.targetType, targetId: args.targetId, reason };
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldLink: { propositionId: args.propositionId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({
+        linked: true,
+        propositionId: args.propositionId,
+        targetType: args.targetType,
+        targetId: args.targetId,
+        proposition: data?.data,
+      });
+    }
+  );
+
+  server.tool(
+    'unlink_proposition',
+    `Remove the ASSUMES edge between a proposition and one node. Both are untouched — only the edge and the reason recorded on it go. Use this when a link was drawn in error. To say a claim no longer holds, do not unlink it: record a reading and move the status, so what rested on it is marked rather than forgotten. Removing an edge that is already gone is a no-op.${GOVERNED_NOTE}`,
+    {
+      propositionId: z.string().describe('Proposition id from list_propositions.'),
+      targetType: z.enum(PROPOSITION_LINK_TARGET_TYPES).describe('The kind of node the edge points at.'),
+      targetId: z.string().describe('The node id.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      validateEnum(args.targetType, PROPOSITION_LINK_TARGET_TYPES, 'targetType');
+      if (!String(args.targetId ?? '').trim()) throw new Error('targetId is required');
+      const path = `${BASE}/${encodeURIComponent(args.propositionId)}/links/${encodeURIComponent(args.targetType)}/${encodeURIComponent(args.targetId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'DELETE',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({
+          ...preview,
+          wouldChange: { propositionId: args.propositionId, targetType: args.targetType, targetId: args.targetId, removed: true },
+        });
+      }
+      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      return ok({
+        unlinked: true,
+        propositionId: args.propositionId,
+        targetType: args.targetType,
+        targetId: args.targetId,
+        proposition: data?.data,
+      });
+    }
+  );
+
+  server.tool(
+    'get_thread_graph',
+    `Generate the THREAD GRAPH around any node — the goal graph the owner drew, and its cousins — with no new storage. root is <kind>:<id> with kind one of ${THREAD_GRAPH_ROOT_KINDS.join(' | ')}; the walk goes both directions to depth (default ${THREAD_GRAPH_DEFAULT_DEPTH}, capped at ${THREAD_GRAPH_MAX_NODES} nodes). format json returns nodes [{key, kind, id, shortId, title, status|state|standing, audience}] and edges [{from, to, relation}] with relation in serves | measured_by | decided_by | realizes | relates | supersedes | amends | refines | depends_on | conflicts_with | assumes. format mermaid returns a graph LR document under \`mermaid\` with the same nodes and labelled edges — paste it into a Stream, a card or a decision body. shortId (G18, P3, D7, I2, X5) is stable per workspace, so it means the same node tomorrow and in an export.`,
+    {
+      root: z.string().describe('<kind>:<id>, e.g. goal:01J… or decision:01J…'),
+      depth: z.number().int().min(1).optional().describe(`How many edges out from the root, both directions. Default ${THREAD_GRAPH_DEFAULT_DEPTH}.`),
+      format: z.enum(THREAD_GRAPH_FORMATS).optional().describe('json (default) or mermaid.'),
+    },
+    async (args) => {
+      const { root } = parseGraphRoot(args.root);
+      const depth = validateDepth(args.depth);
+      const format = args.format === undefined ? undefined : validateEnum(args.format, THREAD_GRAPH_FORMATS, 'format');
+      const query = buildQuery({ root, depth, format });
+      const data = await api('GET', `${GRAPH_PATH}${query}`);
+      if (format === 'mermaid') {
+        const mermaid = mermaidText(data);
+        if (mermaid === null) throw new Error('the API returned no mermaid document for this root');
+        return ok({ root, depth: depth ?? THREAD_GRAPH_DEFAULT_DEPTH, format, mermaid });
+      }
+      const graph = data?.data ?? null;
+      if (!graph) return ok({ root, graph: null });
+      const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+      const edges = Array.isArray(graph.edges) ? graph.edges : [];
+      return ok({ root, depth: depth ?? THREAD_GRAPH_DEFAULT_DEPTH, format: 'json', nodeCount: nodes.length, edgeCount: edges.length, graph });
+    }
+  );
+
+  server.tool(
+    'file_document',
+    `File a Galaxy document on a thread noun with a ROLE: a decision's memo, a proposition's evidence file, an Oasis Thread's outcome artifact, an indicator's source spreadsheet, an idea's source. family is the noun (goal | proposition | decision | indicator | idea), id its id, documentId the Galaxy document, role one of memo | outcome | evidence | source | artifact. The document is linked, never copied or moved; it comes back on the noun's detail as documents[]. Filing the same document on the same node again replaces the role and reason (an upsert on the pair). The reason is recorded on the link and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      family: z.enum(DOCUMENT_TARGET_TYPES).describe('The noun the document is filed on.'),
+      id: z.string().describe('The noun\'s id (from list_goals, list_propositions, list_decisions, list_indicators or list_ideas).'),
+      documentId: z.string().describe('The Galaxy document id.'),
+      role: z.enum(DOCUMENT_ROLES).describe('memo | outcome | evidence | source | artifact.'),
+      ...governedArgs(z),
+      reason: z.string().describe('Why this document belongs on this node, in a sentence. Recorded on the link; also the audit reason.'),
+    },
+    async (args) => {
+      validateEnum(args.family, DOCUMENT_TARGET_TYPES, 'family');
+      validateEnum(args.role, DOCUMENT_ROLES, 'role');
+      if (!String(args.id ?? '').trim()) throw new Error('id is required');
+      if (!String(args.documentId ?? '').trim()) throw new Error('documentId is required');
+      const reason = validateReason(args.reason);
+      const path = `${DOCUMENT_FAMILY_PATHS[args.family]}/${encodeURIComponent(args.id)}/documents`;
+      const body = { documentId: args.documentId, role: args.role, reason };
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldLink: { family: args.family, id: args.id, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({ filed: true, family: args.family, id: args.id, documentId: args.documentId, role: args.role, target: data?.data });
+    }
+  );
+
+  server.tool(
+    'unfile_document',
+    `Remove one Galaxy document from a thread noun. The document itself is untouched in Galaxy and the noun is untouched — only the link, its role and its reason go. Use this when a document was filed on the wrong node; to replace a role, file_document again instead. Removing a link that is already gone is a no-op.${GOVERNED_NOTE}`,
+    {
+      family: z.enum(DOCUMENT_TARGET_TYPES).describe('The noun the document is filed on.'),
+      id: z.string().describe('The noun\'s id.'),
+      documentId: z.string().describe('The Galaxy document id to unfile.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      validateEnum(args.family, DOCUMENT_TARGET_TYPES, 'family');
+      if (!String(args.id ?? '').trim()) throw new Error('id is required');
+      if (!String(args.documentId ?? '').trim()) throw new Error('documentId is required');
+      const path = `${DOCUMENT_FAMILY_PATHS[args.family]}/${encodeURIComponent(args.id)}/documents/${encodeURIComponent(args.documentId)}`;
+      const preview = validateApiBridgeRequest({
+        method: 'DELETE',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) {
+        return ok({ ...preview, wouldChange: { family: args.family, id: args.id, documentId: args.documentId, removed: true } });
+      }
+      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      return ok({ unfiled: true, family: args.family, id: args.id, documentId: args.documentId, target: data?.data });
+    }
+  );
+}
+
+export const WORK_PROPOSITION_TOOL_NAMES = [
+  'list_propositions',
+  'get_proposition',
+  'get_proposition_calibration',
+  'state_proposition',
+  'record_proposition_reading',
+  'set_proposition_status',
+  'link_proposition',
+  'unlink_proposition',
+  'get_thread_graph',
+  'file_document',
+  'unfile_document',
+];

package/tools/threads/work-thread-tools.js

@@ -0,0 +1,165 @@
+/**
+ * Thread tools for the Adrata MCP server — Goals, Propositions, Indicators,
+ * Decisions, Ideas, and the Discussion that runs under all five. The
+ * "threads" family.
+ *
+ * The design: `spoq/epics/backlog/starfield-ideas/CONTRACT.md`. The short form
+ * an agent needs before touching these:
+ *
+ *   - SIX NOUNS. Goal (a goal, or a STRATEGY under one — a bet with a
+ *     hypothesis, a falsifier and a confidence). Indicator (a named measure
+ *     with a definition, unit, direction and target, plus readings). Decision
+ *     (a ruling written when made, never rewritten; reversals are NEW
+ *     decisions that supersede). Idea (a big idea with the vector it arrived
+ *     on and its source; its states are a history, not a flag). Scope/Card
+ *     (the existing initiative → epic → feature → card; untouched here).
+ *     Discussion (threaded, anchored, resolvable posts on any of the four new
+ *     nouns).
+ *   - FIVE EDGES, all joins with a reason: goal → scope (this initiative
+ *     realizes this goal), goal → idea (this idea serves it), idea → scope /
+ *     card / idea (realization and interconnection), decision → any node (this
+ *     ruling shaped that node), indicator → goal (this measure says whether
+ *     that goal is on track).
+ *   - AUDIENCE is on every new noun: seller | manager | leader are who Adrata
+ *     serves; builder is us building Adrata, Starfield and Portals; company is
+ *     the whole business. It is a LENS — the API never hides by it.
+ *   - VECTOR is where an idea came from (owner | customer | buyer_demand |
+ *     competitor | keynote | internal_audit | technology | regulation) and is
+ *     required with a source on capture.
+ *   - NOTHING here is a board citizen: no column, no position on a board, no
+ *     stored count. PROGRESS IS DERIVED on read from the cards reachable
+ *     through a node's scopes and direct links, as COUNTS, never a percentage
+ *     (hierarchy Decision 4). Indicator status is derived from the latest
+ *     reading against target and expected. Nothing is rewritten: every field
+ *     edit appends to the change log (list_thread_changes).
+ *   - Promotion of an idea to an epic is `add_to_roadmap` then `link_idea`;
+ *     there is deliberately no promote verb here.
+ *   - Decisions form a GRAPH: typed edges between decisions (supersedes |
+ *     amends | refines | depends_on | conflicts_with | relates_to). refines is
+ *     the sub-decision edge; conflicts_with records two live rulings the owner
+ *     has not picked between. get_decision_graph walks it.
+ *   - A PROPOSITION is the fifth noun: a claim about the world we act on,
+ *     with a required falsifier and a confidence that moves only through a
+ *     reading with evidence. Goals, decisions, ideas and indicators ASSUME
+ *     it (link_proposition); when it is falsified, what rests on it is marked
+ *     on read. get_thread_graph draws any node's neighbourhood, as JSON or
+ *     mermaid. Every noun can file a Galaxy document with a role
+ *     (file_document).
+ *
+ * Writes follow the same governed contract as every write on this server:
+ * dryRun defaults to TRUE; a live write needs dryRun:false AND approved:true
+ * AND a reason AND an idempotencyKey.
+ *
+ * The family is split by noun so no file passes the tools/ size ceiling:
+ * work-goal-tools.js, work-indicator-tools.js, work-decision-tools.js,
+ * work-idea-tools.js, work-discussion-tools.js, work-proposition-tools.js
+ * (propositions, the graph read and document filing), with the vocabularies
+ * and the pure helpers in shared.js. This module is the one registration point.
+ */
+
+import { registerWorkGoalTools, WORK_GOAL_TOOL_NAMES } from './work-goal-tools.js';
+import { registerWorkIndicatorTools, WORK_INDICATOR_TOOL_NAMES } from './work-indicator-tools.js';
+import { registerWorkDecisionTools, WORK_DECISION_TOOL_NAMES } from './work-decision-tools.js';
+import { registerWorkIdeaTools, WORK_IDEA_TOOL_NAMES } from './work-idea-tools.js';
+import { registerWorkDiscussionTools, WORK_DISCUSSION_TOOL_NAMES } from './work-discussion-tools.js';
+import { registerWorkPropositionTools, WORK_PROPOSITION_TOOL_NAMES } from './work-proposition-tools.js';
+
+export {
+  GOVERNED_NOTE,
+  AUDIENCES,
+  VECTORS,
+  GOAL_LEVELS,
+  GOAL_STATUSES,
+  IDEA_STATES,
+  DECISION_STATUSES,
+  POSITIONS,
+  INDICATOR_KINDS,
+  INDICATOR_DIRECTIONS,
+  DOORS,
+  DECISION_LINK_TARGET_TYPES,
+  DECISION_RELATIONS,
+  THREAD_TARGET_TYPES,
+  INDICATOR_STATUSES,
+  PROPOSITION_STATUSES,
+  PROPOSITION_LINK_TARGET_TYPES,
+  PROPOSITION_EVIDENCE_STATUSES,
+  DOCUMENT_TARGET_TYPES,
+  DOCUMENT_ROLES,
+  DOCUMENT_FAMILY_PATHS,
+  THREAD_GRAPH_ROOT_KINDS,
+  THREAD_GRAPH_RELATIONS,
+  THREAD_GRAPH_FORMATS,
+  THREAD_GRAPH_DEFAULT_DEPTH,
+  THREAD_GRAPH_MAX_NODES,
+  REASON_REQUIRED_STATES,
+  MAX_TITLE_CHARS,
+  MAX_REASON_CHARS,
+  MAX_BODY_CHARS,
+  indicatorStatus,
+  positionsTally,
+  summarizeThread,
+  validateTitle,
+  validateBody,
+  validateReason,
+  validateConfidence,
+  validateDate,
+  validateEnum,
+  validateGoalLevel,
+  validateStateReason,
+  pickExactlyOne,
+  parseGraphRoot,
+  validateDepth,
+  mermaidText,
+  audienceQuery,
+  buildQuery,
+} from './shared.js';
+
+/**
+ * Register every thread tool.
+ *
+ * @param {McpServer} server
+ * @param {object} deps - { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope }
+ */
+export function registerWorkThreadTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+) {
+  const deps = { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope };
+  registerWorkGoalTools(server, deps);
+  registerWorkIndicatorTools(server, deps);
+  registerWorkDecisionTools(server, deps);
+  registerWorkIdeaTools(server, deps);
+  registerWorkDiscussionTools(server, deps);
+  registerWorkPropositionTools(server, deps);
+}
+
+/** Tool names registered here, for the tier map and the toolset manifest. */
+export const WORK_THREAD_TOOL_NAMES = [
+  ...WORK_GOAL_TOOL_NAMES,
+  ...WORK_INDICATOR_TOOL_NAMES,
+  ...WORK_DECISION_TOOL_NAMES,
+  ...WORK_IDEA_TOOL_NAMES,
+  ...WORK_DISCUSSION_TOOL_NAMES,
+  ...WORK_PROPOSITION_TOOL_NAMES,
+];
+
+/** The writes shaped as upserts (ON CONFLICT, or one row per (decision, user)); the annotations file lists these as idempotent. */
+export const WORK_THREAD_UPSERT_WRITES = [
+  'link_goal',
+  'link_decision',
+  'link_idea',
+  'take_decision_position',
+  'resolve_discussion',
+  'relate_decisions',
+  'unrelate_decisions',
+  // Propositions: the assumes edge is keyed by (proposition, target); a
+  // document filing by (target, document). A repeat link/file rewrites the
+  // same row; a repeat unlink/unfile deletes a row already gone.
+  'link_proposition',
+  'unlink_proposition',
+  'file_document',
+  'unfile_document',
+];
+
+/** Reads, by the read-only name rule the annotations use. */
+export const WORK_THREAD_READ_TOOLS = WORK_THREAD_TOOL_NAMES.filter((n) => /^(list_|get_)/.test(n));