@adrata/adrata-mcp 1.0.49 → 1.0.51

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

@@ -0,0 +1,368 @@
+/**
+ * Decision tools: a ruling with context, choice, rationale and consequences,
+ * in the register's own doctrine — written when made, never rewritten,
+ * reversals are NEW decisions that supersede the old. People take a position
+ * (support / concern / object) and discuss it before and after. See
+ * work-thread-tools.js for the model and CONTRACT.md for the routes.
+ *
+ * Ownership (company/decisions/2026-08-06-spoq-roadmap-sync.md, applied): a
+ * decision with `sourcePath` set is git-owned for title, body, status,
+ * decided_on and door — the import script writes those and the API answers
+ * 409 naming the file if a tool tries. Positions, discussion, links,
+ * confidence, reversal condition, review date and outcome are Starfield-owned
+ * on every decision. An app-born decision that reaches `decided` comes back
+ * with `gitHalf` text telling the caller to write the company/decisions/ file,
+ * exactly as add_to_roadmap does for epics; surface it, do not swallow it.
+ */
+
+import {
+  AUDIENCES,
+  DECISION_LINK_TARGET_TYPES,
+  DECISION_RELATIONS,
+  DECISION_STATUSES,
+  DOORS,
+  GOVERNED_NOTE,
+  OUTCOME_VERDICTS,
+  POSITIONS,
+  audienceQuery,
+  buildQuery,
+  compactBody,
+  governedArgs,
+  tallyFrom,
+  validateBody,
+  validateConfidence,
+  validateDate,
+  validateEnum,
+  validateReason,
+  validateStateReason,
+  validateTitle,
+} from './shared.js';
+
+const BASE = '/api/v1/work-decisions';
+
+export function registerWorkDecisionTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+) {
+  server.tool(
+    'list_decisions',
+    'List decisions — each with its status (proposed | discussing | decided | superseded | reversed), door (one_way = hard to reverse, two_way = cheap to reverse), audience, a positions tally {support, concern, object} and how many discussion posts it has. Pass targetType + targetId to see the decisions that shaped one goal, idea, scope, card or indicator. Reversals are new decisions, and one may replace several at once: read the supersedes edges (decision_graph, or the detail\'s parents) to walk the chain — supersedesDecisionId is only a fast pointer at the most recent predecessor.',
+    {
+      status: z.enum(DECISION_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(DECISION_LINK_TARGET_TYPES).optional().describe('With targetId: only decisions linked to this node.'),
+      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_decision',
+    'Read one decision whole: title, body (context, choice, rationale, consequences), alternatives considered, door, confidence at decision time, reversal condition, review date, outcome if recorded, the nodes it links to (with titles), who holds which position, and the last 50 discussion posts. `tally` is the support/concern/object count.',
+    {
+      decisionId: z.string().describe('Decision id from list_decisions.'),
+    },
+    async (args) => {
+      const data = await api('GET', `${BASE}/${encodeURIComponent(args.decisionId)}`);
+      const decision = data?.data ?? null;
+      if (!decision) return ok({ decision: null, tally: null });
+      return ok({ tally: decision.tally ?? tallyFrom(decision.positions), decision });
+    }
+  );
+
+  server.tool(
+    'record_decision',
+    `Record a decision as PROPOSED: title, body in the register's shape (context, choice, rationale, consequences), audience, door (one_way | two_way), the ALTERNATIVES considered (a decision with no alternatives is a fact, not a decision), the decider's confidence 0-1 (scored later against the outcome), the reversal condition (what observation would change the call) and a review date. To reverse or replace an existing decision, record a NEW one with supersedesDecisionId — the old one moves to superseded in the same transaction; never edit the old text. sourcePath is for imports from company/decisions/ only; a decision born here has none and the API will hand you the git half when it is decided.${GOVERNED_NOTE}`,
+    {
+      title: z.string().describe('The ruling as a sentence, at most 160 characters.'),
+      body: z.string().describe('Markdown: context, choice, rationale, consequences.'),
+      audience: z.enum(AUDIENCES).describe('Who this decision is for.'),
+      door: z.enum(DOORS).optional().describe('one_way = hard to reverse, decide slowly; two_way = cheap to reverse. Default two_way.'),
+      alternatives: z.string().optional().describe('Markdown list of the options considered and why each lost.'),
+      confidence: z.number().min(0).max(1).optional().describe('Decider\'s confidence at decision time, 0-1. Frozen once decided.'),
+      reversalCondition: z.string().optional().describe('What observation would change this call.'),
+      reviewOn: z.string().optional().describe('When to re-read the call against the outcome, YYYY-MM-DD.'),
+      supersedesDecisionId: z.string().optional().describe('The decision this one replaces; it moves to superseded.'),
+      sourcePath: z.string().optional().describe('Imports only: the company/decisions/ file. Omit for a decision born here.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      const body = compactBody({
+        title: validateTitle(args.title),
+        body: validateBody(args.body),
+        audience: args.audience,
+        door: args.door,
+        alternatives: args.alternatives,
+        confidence: validateConfidence(args.confidence),
+        reversalCondition: args.reversalCondition,
+        reviewOn: validateDate(args.reviewOn, 'reviewOn'),
+        supersedesDecisionId: args.supersedesDecisionId,
+        sourcePath: args.sourcePath,
+      });
+      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, decision: data?.data, gitHalf: data?.gitHalf ?? data?.data?.gitHalf ?? null });
+    }
+  );
+
+  server.tool(
+    'set_decision_status',
+    `Move a decision through its lifecycle: proposed → discussing → decided, or to superseded / reversed (prefer record_decision with supersedesDecisionId for those — a reversal is a new decision). decided needs decidedOn (defaults to today) and records the caller as the decider. A decision with sourcePath is git-owned for status and the API answers 409 naming the file; change the file instead. When an app-born decision becomes decided, the response carries gitHalf: write the company/decisions/ file. The reason is recorded on the transition and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      decisionId: z.string().describe('Decision id from list_decisions.'),
+      status: z.enum(DECISION_STATUSES).describe('The new status.'),
+      decidedOn: z.string().optional().describe('For decided: the day it was decided, YYYY-MM-DD. Defaults to today.'),
+      ...governedArgs(z),
+      reason: z.string().describe('Why the status changes. Recorded on the transition; also the audit reason.'),
+    },
+    async (args) => {
+      validateEnum(args.status, DECISION_STATUSES, 'status');
+      const reason = validateStateReason(args.status, args.reason);
+      const path = `${BASE}/${encodeURIComponent(args.decisionId)}`;
+      const body = compactBody({
+        status: args.status,
+        reason,
+        decidedOn: validateDate(args.decidedOn, 'decidedOn'),
+      });
+      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: { decisionId: args.decisionId, ...body } });
+      const data = await api('PATCH', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({
+        updated: true,
+        decision: data?.data,
+        gitHalf: data?.gitHalf ?? data?.data?.gitHalf ?? null,
+      });
+    }
+  );
+
+  server.tool(
+    'record_decision_outcome',
+    `Record what ACTUALLY happened after a decided decision — once, separately from the decision text, because decision quality and outcome quality are different things and the confidence stated at decision time is scored against this. The verdict (held | partly | did_not_hold) is what calibration scores: without it the outcome is prose the Brier score cannot read, so it is required here. Only after status is decided; the API refuses a second outcome. Write what was observed, not a re-argument of the call.${GOVERNED_NOTE}`,
+    {
+      decisionId: z.string().describe('Decision id from list_decisions.'),
+      verdict: z.enum(OUTCOME_VERDICTS).describe('Did the decision\'s own prediction hold? held | partly | did_not_hold. Calibration needs it.'),
+      outcome: z.string().describe('What happened, as observed. Markdown.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      validateEnum(args.verdict, OUTCOME_VERDICTS, 'verdict');
+      const outcome = validateBody(args.outcome, 'outcome');
+      if (!outcome.trim()) throw new Error('outcome is required and cannot be blank');
+      const path = `${BASE}/${encodeURIComponent(args.decisionId)}/outcome`;
+      const body = { verdict: args.verdict, outcome };
+      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, wouldChange: { decisionId: args.decisionId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders(args) });
+      return ok({ recorded: true, decision: data?.data });
+    }
+  );
+
+  server.tool(
+    'take_decision_position',
+    `Take the CALLER'S position on a decision: support, concern or object, with an optional note. One position per person per decision — calling again replaces it (an upsert), so changing your mind is the same call. "We all discussed it" is this record plus the discussion; take a position honestly and put the argument in post_discussion.${GOVERNED_NOTE}`,
+    {
+      decisionId: z.string().describe('Decision id from list_decisions.'),
+      position: z.enum(POSITIONS).describe('support | concern | object.'),
+      note: z.string().optional().describe('One line on why. The argument itself belongs in post_discussion.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      validateEnum(args.position, POSITIONS, 'position');
+      const path = `${BASE}/${encodeURIComponent(args.decisionId)}/position`;
+      const body = compactBody({ position: args.position, note: args.note });
+      const preview = validateApiBridgeRequest({
+        method: 'PUT',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldChange: { decisionId: args.decisionId, ...body } });
+      const data = await api('PUT', path, { body, headers: buildMutationHeaders(args) });
+      const decision = data?.data;
+      return ok({
+        taken: true,
+        decisionId: args.decisionId,
+        position: args.position,
+        tally: decision?.tally ?? tallyFrom(decision?.positions),
+      });
+    }
+  );
+
+  server.tool(
+    'link_decision',
+    `Say that this decision SHAPED a node: a goal, an idea, a scope (initiative/epic), a card (work_item) or an indicator. An edge with a reason; the target does not change. Linking a pair that is already linked replaces the reason (an upsert). The reason is recorded on the link and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      decisionId: z.string().describe('Decision id from list_decisions.'),
+      targetType: z.enum(DECISION_LINK_TARGET_TYPES).describe('What kind of node the decision shaped.'),
+      targetId: z.string().describe('The node id (from list_goals, list_ideas, list_work_scopes, a card id, or list_indicators).'),
+      ...governedArgs(z),
+      reason: z.string().describe('How the decision shaped this node, in a sentence. Recorded on the link; also the audit reason.'),
+    },
+    async (args) => {
+      validateEnum(args.targetType, DECISION_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.decisionId)}/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: { decisionId: args.decisionId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({ linked: true, decisionId: args.decisionId, targetType: args.targetType, targetId: args.targetId, decision: data?.data });
+    }
+  );
+
+  server.tool(
+    'get_decision_graph',
+    'Read the decision GRAPH around one decision: the decisions it relates to and those that relate to it, each edge typed (supersedes | amends | refines | depends_on | conflicts_with | relates_to) with its reason. refines edges are the sub-decisions: a big ruling broken into the smaller calls that implement it. conflicts_with edges are two live rulings the owner has not picked between — read those before acting on either. Use this to walk a decision chain instead of paging through list_decisions.',
+    {
+      decisionId: z.string().describe('Decision id from list_decisions; the graph is centred on it.'),
+    },
+    async (args) => {
+      const data = await api('GET', `${BASE}/${encodeURIComponent(args.decisionId)}/graph`);
+      const graph = data?.data ?? null;
+      if (!graph) return ok({ graph: null });
+      const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+      const edges = Array.isArray(graph.edges) ? graph.edges : Array.isArray(graph.relations) ? graph.relations : [];
+      return ok({ decisionId: args.decisionId, nodeCount: nodes.length, edgeCount: edges.length, graph });
+    }
+  );
+
+  server.tool(
+    'relate_decisions',
+    `Draw a typed edge from one decision to another. refines = the related decision is a SUB-DECISION of this one (a smaller call that implements the bigger ruling). supersedes = this decision replaces the target, and the target moves to superseded exactly as record_decision with supersedesDecisionId does. amends = this one changes part of the target without replacing it. depends_on = this one only holds while the target does. conflicts_with = two LIVE rulings the owner has not picked between — record the conflict rather than silently choosing. relates_to = connected, none of the above. The pair plus the relation is the key: relating the same pair the same way again replaces the reason (an upsert). The reason is recorded on the edge and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      decisionId: z.string().describe('The decision the edge starts from, from list_decisions.'),
+      relatedDecisionId: z.string().describe('The decision the edge points at.'),
+      relation: z.enum(DECISION_RELATIONS).describe('supersedes | amends | refines | depends_on | conflicts_with | relates_to.'),
+      ...governedArgs(z),
+      reason: z.string().describe('Why they relate this way, in a sentence. Recorded on the edge; also the audit reason.'),
+    },
+    async (args) => {
+      validateEnum(args.relation, DECISION_RELATIONS, 'relation');
+      if (!String(args.relatedDecisionId ?? '').trim()) throw new Error('relatedDecisionId is required');
+      if (args.relatedDecisionId === args.decisionId) throw new Error('a decision cannot relate to itself');
+      const reason = validateReason(args.reason);
+      const path = `${BASE}/${encodeURIComponent(args.decisionId)}/relations`;
+      const body = { relatedDecisionId: args.relatedDecisionId, relation: args.relation, 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: { decisionId: args.decisionId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({
+        related: true,
+        decisionId: args.decisionId,
+        relatedDecisionId: args.relatedDecisionId,
+        relation: args.relation,
+        decision: data?.data,
+      });
+    }
+  );
+
+  server.tool(
+    'unrelate_decisions',
+    `Remove one typed edge between two decisions. Both decisions are untouched — only the edge goes, and only the edge with exactly this relation; a pair related two ways keeps the other edge. Use this when an edge was drawn in error. To say a ruling no longer applies, do not unrelate it: record the superseding decision instead, so the history stays. Removing an edge that is already gone is a no-op.${GOVERNED_NOTE}`,
+    {
+      decisionId: z.string().describe('The decision the edge starts from.'),
+      relatedDecisionId: z.string().describe('The decision the edge points at.'),
+      relation: z.enum(DECISION_RELATIONS).describe('The relation of the edge to remove.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      validateEnum(args.relation, DECISION_RELATIONS, 'relation');
+      if (!String(args.relatedDecisionId ?? '').trim()) throw new Error('relatedDecisionId is required');
+      const path = `${BASE}/${encodeURIComponent(args.decisionId)}/relations/${encodeURIComponent(args.relatedDecisionId)}/${encodeURIComponent(args.relation)}`;
+      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: { decisionId: args.decisionId, relatedDecisionId: args.relatedDecisionId, relation: args.relation, removed: true },
+        });
+      }
+      const data = await api('DELETE', path, { headers: buildMutationHeaders(args) });
+      return ok({
+        unrelated: true,
+        decisionId: args.decisionId,
+        relatedDecisionId: args.relatedDecisionId,
+        relation: args.relation,
+        decision: data?.data,
+      });
+    }
+  );
+}
+
+export const WORK_DECISION_TOOL_NAMES = [
+  'list_decisions',
+  'get_decision',
+  'get_decision_graph',
+  'record_decision',
+  'set_decision_status',
+  'record_decision_outcome',
+  'take_decision_position',
+  'link_decision',
+  'relate_decisions',
+  'unrelate_decisions',
+];

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

@@ -0,0 +1,125 @@
+/**
+ * Discussion and history tools: the threaded, anchored, resolvable posts that
+ * run under every thread noun (goal | idea | decision | indicator), and the
+ * field-change log that is the git half of the same nouns — who changed what,
+ * when, and what it said before. See work-thread-tools.js for the model and
+ * CONTRACT.md for the routes.
+ */
+
+import { GOVERNED_NOTE, THREAD_TARGET_TYPES, buildQuery, compactBody, governedArgs, validateBody, validateEnum } from './shared.js';
+
+const DISCUSSIONS = '/api/v1/work-discussions';
+const CHANGES = '/api/v1/work-thread-changes';
+
+function requireTarget(args) {
+  validateEnum(args.targetType, THREAD_TARGET_TYPES, 'targetType');
+  if (!String(args.targetId ?? '').trim()) throw new Error('targetId is required');
+}
+
+export function registerWorkDiscussionTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+) {
+  server.tool(
+    'list_discussion',
+    'Read the discussion under one goal, idea, decision or indicator: a flat list, oldest first, each post with inReplyTo (the thread), anchorText (the passage of the body it is about, null = the whole thing), resolvedAt and its author. Resolved threads are hidden unless includeResolved. Read this BEFORE arguing a point or taking a position — the objection you are about to raise has often been raised.',
+    {
+      targetType: z.enum(THREAD_TARGET_TYPES).describe('What the discussion hangs off.'),
+      targetId: z.string().describe('The goal, idea, decision or indicator id.'),
+      includeResolved: z.boolean().optional().describe('Also return resolved threads. Default false.'),
+    },
+    async (args) => {
+      requireTarget(args);
+      const query = buildQuery({
+        targetType: args.targetType,
+        targetId: args.targetId,
+        includeResolved: args.includeResolved ? 'true' : undefined,
+      });
+      const data = await api('GET', `${DISCUSSIONS}${query}`);
+      const items = data?.data || [];
+      return ok({ count: items.length, items });
+    }
+  );
+
+  server.tool(
+    'list_thread_changes',
+    'Read the field-change log for one goal, idea, decision or indicator: every PATCH and state move as a row with field, oldValue, newValue, who changed it, when, and the reason — newest first. Never rewritten. This is "blame" and "diff" for the thread nouns; use it to answer "what did this say before" and "who changed the target date".',
+    {
+      targetType: z.enum(THREAD_TARGET_TYPES).describe('What the log is for.'),
+      targetId: z.string().describe('The goal, idea, decision or indicator id.'),
+    },
+    async (args) => {
+      requireTarget(args);
+      const query = buildQuery({ targetType: args.targetType, targetId: args.targetId });
+      const data = await api('GET', `${CHANGES}${query}`);
+      const items = data?.data || [];
+      return ok({ count: items.length, items });
+    }
+  );
+
+  server.tool(
+    'post_discussion',
+    `Post to the discussion under a goal, idea, decision or indicator. Reply to a post with inReplyTo; anchor the comment to a passage of the target's body with anchorText (quote it exactly, as a Google Docs comment is pinned to a selection) or omit it to comment on the whole thing. Posts are appended, never edited by a tool; each call adds one row, so do not retry with a fresh idempotencyKey. Put the argument here and the verdict in take_decision_position.${GOVERNED_NOTE}`,
+    {
+      targetType: z.enum(THREAD_TARGET_TYPES).describe('What the post hangs off.'),
+      targetId: z.string().describe('The goal, idea, decision or indicator id.'),
+      body: z.string().describe('Markdown. Say the thing; cite the evidence.'),
+      inReplyTo: z.string().optional().describe('Post id this replies to, from list_discussion. Omit to start a thread.'),
+      anchorText: z.string().optional().describe('The exact passage of the target\'s body this is about. Omit for the whole thing.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      requireTarget(args);
+      const text = validateBody(args.body);
+      if (!text.trim()) throw new Error('body is required and cannot be blank');
+      const body = compactBody({
+        targetType: args.targetType,
+        targetId: args.targetId,
+        body: text,
+        inReplyTo: args.inReplyTo,
+        anchorText: args.anchorText,
+      });
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path: DISCUSSIONS,
+        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', DISCUSSIONS, { body, headers: buildMutationHeaders(args) });
+      return ok({ posted: true, post: data?.data });
+    }
+  );
+
+  server.tool(
+    'resolve_discussion',
+    `Resolve a discussion thread (resolved: true) or reopen it (resolved: false). Root posts only — replies inherit. Resolving hides the thread from list_discussion by default; nothing is deleted and the posts stay readable with includeResolved. Any member may resolve; resolve when the point is settled or absorbed into the body, not to silence it.${GOVERNED_NOTE}`,
+    {
+      postId: z.string().describe('The ROOT post id of the thread, from list_discussion.'),
+      resolved: z.boolean().describe('true to resolve, false to reopen.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      if (typeof args.resolved !== 'boolean') throw new Error('resolved must be true or false');
+      const method = args.resolved ? 'POST' : 'DELETE';
+      const path = `${DISCUSSIONS}/${encodeURIComponent(args.postId)}/resolve`;
+      const preview = validateApiBridgeRequest({
+        method,
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldChange: { postId: args.postId, resolved: args.resolved } });
+      const data = await api(method, path, { headers: buildMutationHeaders(args) });
+      return ok({ updated: true, postId: args.postId, resolved: args.resolved, post: data?.data });
+    }
+  );
+}
+
+export const WORK_DISCUSSION_TOOL_NAMES = ['list_discussion', 'list_thread_changes', 'post_discussion', 'resolve_discussion'];

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

@@ -0,0 +1,145 @@
+/**
+ * Goal tools: a goal, the strategies under it (the bets), and the edges that
+ * say which initiatives and ideas realize them. See work-thread-tools.js for
+ * the model and CONTRACT.md for the routes.
+ */
+
+import {
+  AUDIENCES,
+  GOAL_LEVELS,
+  GOVERNED_NOTE,
+  audienceQuery,
+  buildQuery,
+  compactBody,
+  governedArgs,
+  pickExactlyOne,
+  summarizeThread,
+  validateBody,
+  validateConfidence,
+  validateDate,
+  validateGoalLevel,
+  validateReason,
+  validateTitle,
+} from './shared.js';
+
+const BASE = '/api/v1/work-goals';
+
+export function registerWorkGoalTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+) {
+  server.tool(
+    'list_goals',
+    'List the goal THREADS, compact: each goal with its strategies nested, each strategy with its indicators (latest reading plus derived status: no_reading | achieved | on_track | off_track | unknown_pace), progress as COUNTS over the cards its scopes reach, and how many decisions shaped it. Nothing here is a board: no columns, no stored progress. Filter by audience (seller/manager/leader are who Adrata serves; builder is us building it; company is the whole business) and by level. Start here; get_goal_thread needs an id from this list.',
+    {
+      audience: z
+        .array(z.enum(AUDIENCES))
+        .optional()
+        .describe('Narrow to these audiences. Omit for all — the API never hides by audience; this is a lens.'),
+      level: z.enum(GOAL_LEVELS).optional().describe('goal (top) or strategy (a bet under a goal). Omit for both.'),
+      includeArchived: z.boolean().optional().describe('Include archived goals. Default false.'),
+    },
+    async (args) => {
+      const query = buildQuery({
+        audience: audienceQuery(args.audience),
+        level: args.level,
+        includeArchived: args.includeArchived ? 'true' : undefined,
+      });
+      const data = await api('GET', `${BASE}${query}`);
+      const items = data?.data || [];
+      return ok({ count: items.length, items });
+    }
+  );
+
+  server.tool(
+    'get_goal_thread',
+    'Read one goal as a THREAD: the goal, its strategies, the initiatives/epics linked to it with their progress counts, the ideas that serve it with their state, the decisions that shaped it with a support/concern/object tally, its indicators with the last 12 readings, and the discussion count. `summary` is the compact form to read first; `thread` is the whole thing. Use this to answer "what are we doing about X and is it working".',
+    {
+      goalId: z.string().describe('Goal or strategy id from list_goals.'),
+    },
+    async (args) => {
+      const data = await api('GET', `${BASE}/${encodeURIComponent(args.goalId)}`);
+      const thread = data?.data ?? null;
+      if (!thread) return ok({ thread: null, summary: null });
+      return ok({ summary: summarizeThread(thread), thread });
+    }
+  );
+
+  server.tool(
+    'create_goal',
+    `Create a goal, or a STRATEGY under a goal (level: strategy + parentGoalId). A strategy is a bet: give its hypothesis (what we expect), its falsifier (what observation would prove it wrong) and a confidence 0-1, so it can be scored when it resolves. Goals are Starfield-owned and born here; the app is the writer. Check list_goals first — two goals with one intent is a tree nobody trusts. Progress is never set: it is derived from the cards its linked scopes reach.${GOVERNED_NOTE}`,
+    {
+      level: z.enum(GOAL_LEVELS).describe('goal = the outcome; strategy = one of the ways to reach a goal (needs parentGoalId).'),
+      title: z.string().describe('The outcome as a statement, at most 160 characters.'),
+      body: z.string().optional().describe('Markdown. Why this goal, what "achieved" looks like.'),
+      audience: z.enum(AUDIENCES).describe('Who this is for. company for the whole business; builder for us building Adrata/Starfield.'),
+      parentGoalId: z.string().optional().describe('REQUIRED for a strategy: the goal it serves. Must be absent for a goal.'),
+      hypothesis: z.string().optional().describe('Strategy: what we expect to happen if we do this.'),
+      falsifier: z.string().optional().describe('Strategy: the observation that would prove the bet wrong.'),
+      confidence: z.number().min(0).max(1).optional().describe('Strategy: stated probability the bet pays off, 0-1.'),
+      targetOn: z.string().optional().describe('Target day, YYYY-MM-DD.'),
+      revenueOutcomeId: z.string().optional().describe('The revenue outcome this goal rolls up to, when one exists.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      validateGoalLevel(args.level, args.parentGoalId);
+      const body = compactBody({
+        level: args.level,
+        title: validateTitle(args.title),
+        body: args.body === undefined ? undefined : validateBody(args.body),
+        audience: args.audience,
+        parentGoalId: args.parentGoalId,
+        hypothesis: args.hypothesis,
+        falsifier: args.falsifier,
+        confidence: validateConfidence(args.confidence),
+        targetOn: validateDate(args.targetOn, 'targetOn'),
+        revenueOutcomeId: args.revenueOutcomeId,
+      });
+      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, goal: data?.data });
+    }
+  );
+
+  server.tool(
+    'link_goal',
+    `Say that an initiative/epic (scopeId) REALIZES this goal or strategy, or that an idea (ideaId) SERVES it. Exactly one of scopeId | ideaId. The scope and the idea do not move or change; this is an edge with a reason, and the goal's progress is derived from the cards the linked scopes reach. Linking a pair that is already linked replaces the reason (an upsert). The reason is recorded on the link and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      goalId: z.string().describe('Goal or strategy id from list_goals.'),
+      scopeId: z.string().optional().describe('Initiative or epic id from list_work_scopes. Exactly one of scopeId | ideaId.'),
+      ideaId: z.string().optional().describe('Idea id from list_ideas. Exactly one of scopeId | ideaId.'),
+      ...governedArgs(z),
+      reason: z.string().describe('Why this scope realizes / this idea serves the goal, in a sentence. Recorded on the link; also the audit reason.'),
+    },
+    async (args) => {
+      const { key, value } = pickExactlyOne({ scopeId: args.scopeId, ideaId: args.ideaId });
+      const reason = validateReason(args.reason);
+      const segment = key === 'scopeId' ? 'scopes' : 'ideas';
+      const path = `${BASE}/${encodeURIComponent(args.goalId)}/${segment}`;
+      const body = { [key]: value, 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: { goalId: args.goalId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({ linked: true, goalId: args.goalId, [key]: value, goal: data?.data });
+    }
+  );
+}
+
+export const WORK_GOAL_TOOL_NAMES = ['list_goals', 'get_goal_thread', 'create_goal', 'link_goal'];