@smartmemory/compose 0.3.5-beta → 0.3.7

package/lib/stratum-mcp-client.js

@@ -19,10 +19,49 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import YAML from 'yaml';
 import { validateBuildStreamEvent } from './build-stream-schema.js';
+import { appendEvent, resolveDispatchLedgerCwd } from './dispatch-ledger.js';
 import { resolveStratumMcpConnection } from './stratum-engine.js';
 
 const RUNTIME_INPUT_REF = /^\$\.input\.([A-Za-z_][A-Za-z0-9_]*)$/;
 
+function finiteOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function nonemptyStringOrNull(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function isBlockedDispatch(value) {
+  const candidates = [
+    value?.status,
+    value?.outcome,
+    value?.code,
+    value?.error?.status,
+    value?.error?.code,
+  ];
+  return candidates.some((candidate) => {
+    const normalized = typeof candidate === 'string' ? candidate.toLowerCase() : '';
+    return normalized === 'blocked'
+      || normalized === 'budget_exhausted'
+      || normalized === 'budget-exhausted';
+  });
+}
+
+function attachDispatchId(value, dispatchId) {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return;
+  try {
+    Object.defineProperty(value, 'dispatchId', {
+      configurable: true,
+      enumerable: false,
+      value: dispatchId,
+    });
+  } catch {
+    // A frozen third-party value cannot carry metadata. Dispatch behavior still
+    // wins over observability.
+  }
+}
+
 /**
  * Resolve producer-owned authoring values that TS v1 deliberately requires to
  * be literals. Compose knows these values at plan time, so mutate a cloned spec
@@ -147,6 +186,86 @@ export class StratumMcpClient {
   // STRAT-PAR-STREAM: subscribers keyed by `${flowId}::${stepId}` → Set<handler>
   #eventSubs = new Map();
 
+  #recordAgentDispatch(dispatchId, agentType, opts, resultOrError, outcome, elapsedMs) {
+    try {
+      const context = opts.telemetry && typeof opts.telemetry === 'object'
+        ? opts.telemetry
+        : {};
+      const returnedTelemetry = resultOrError?.telemetry
+        && typeof resultOrError.telemetry === 'object'
+        ? resultOrError.telemetry
+        : {};
+      const usage = resultOrError?.usage && typeof resultOrError.usage === 'object'
+        ? resultOrError.usage
+        : {};
+      const effortIntended = Object.hasOwn(context, 'effort_intended')
+        ? nonemptyStringOrNull(context.effort_intended)
+        : nonemptyStringOrNull(opts.effort);
+      const event = {
+        kind: 'dispatch',
+        dispatch_id: dispatchId,
+        site: nonemptyStringOrNull(context.site) ?? 'unattributed',
+        agent: String(agentType ?? 'claude').split(':', 1)[0] || 'claude',
+        outcome,
+        model: nonemptyStringOrNull(returnedTelemetry.model)
+          ?? nonemptyStringOrNull(usage.model),
+        effort_intended: effortIntended,
+        effort_executed: nonemptyStringOrNull(returnedTelemetry.effort),
+        tokens_in: null,
+        tokens_out: null,
+        tokens_total: finiteOrNull(usage.tokens),
+        usd: finiteOrNull(usage.usd),
+        duration_ms: finiteOrNull(usage.ms)
+          ?? finiteOrNull(returnedTelemetry.durationMs)
+          ?? finiteOrNull(elapsedMs),
+      };
+      for (const [field, value] of [
+        ['build_id', context.build_id],
+        ['feature_code', context.feature_code],
+        ['step_id', context.step_id],
+      ]) {
+        if (nonemptyStringOrNull(value) !== null) event[field] = value;
+      }
+      if (finiteOrNull(context.attempt) !== null) event.attempt = context.attempt;
+      appendEvent(resolveDispatchLedgerCwd(context.project_cwd), event);
+    } catch {
+      // Dispatch capture is fail-open by contract.
+    }
+  }
+
+  async #dispatchAgentRun(agentType, prompt, opts, callOpts) {
+    const dispatchId = randomUUID();
+    const startedAt = Date.now();
+    try {
+      const result = await this.#callTool(
+        'stratum_agent_run',
+        buildAgentRunRequest(agentType, prompt, opts),
+        callOpts,
+      );
+      this.#recordAgentDispatch(
+        dispatchId,
+        agentType,
+        opts,
+        result,
+        isBlockedDispatch(result) ? 'blocked' : 'ok',
+        Date.now() - startedAt,
+      );
+      attachDispatchId(result, dispatchId);
+      return result;
+    } catch (error) {
+      this.#recordAgentDispatch(
+        dispatchId,
+        agentType,
+        opts,
+        error,
+        isBlockedDispatch(error) ? 'blocked' : 'error',
+        Date.now() - startedAt,
+      );
+      attachDispatchId(error, dispatchId);
+      throw error;
+    }
+  }
+
   /**
    * Subscribe to BuildStreamEvent push notifications scoped to a (flowId, stepId).
    * Handler receives a parsed BuildStreamEvent envelope. Returns an unsubscribe fn.
@@ -515,9 +634,12 @@ export class StratumMcpClient {
     // those knobs are resolved compose-side (resolveAgentConfig) and applied at
     // this seam — the engine's connector honors model + sandboxMode. `cwd` is
     // required, so default to the process cwd when the caller omits it.
-    return this.#callTool('stratum_agent_run',
-      buildAgentRunRequest(agentType, prompt, opts),
-      { subscribeProgress: true, correlationId });
+    return this.#dispatchAgentRun(
+      agentType,
+      prompt,
+      opts,
+      { subscribeProgress: true, correlationId },
+    );
   }
 
   /**
@@ -531,9 +653,12 @@ export class StratumMcpClient {
    * @returns {Promise<string>}
    */
   async runAgentText(agentType, prompt, opts = {}) {
-    const result = await this.#callTool('stratum_agent_run',
-      buildAgentRunRequest(agentType, prompt, opts),
-      { subscribeProgress: false });
+    const result = await this.#dispatchAgentRun(
+      agentType,
+      prompt,
+      opts,
+      { subscribeProgress: false },
+    );
     return result?.text ?? '';
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.3.5-beta",
+  "version": "0.3.7",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",
@@ -85,7 +85,7 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@smartmemory/stratum": "0.3.2",
+    "@smartmemory/stratum": "^0.3.3",
     "@tanstack/react-virtual": "^3.13.23",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",

package/server/compose-mcp-tools.js

@@ -806,6 +806,55 @@ export function toolGetWorkspace() {
 
 export function _getBinding() { return _binding?.id ?? null; }
 
+// ---------------------------------------------------------------------------
+// Judgment writer — COMP-JUDGMENT-WRITER (S06)
+// ---------------------------------------------------------------------------
+
+export async function toolJudgmentPositionCreate(args) {
+  const { judgmentPositionCreate } = await import('../lib/judgment-writer.js');
+  return judgmentPositionCreate(getTargetRoot(), args);
+}
+
+export async function toolJudgmentPositionAmend(args) {
+  const { judgmentPositionAmend } = await import('../lib/judgment-writer.js');
+  return judgmentPositionAmend(getTargetRoot(), args);
+}
+
+export async function toolJudgmentJointAdd(args) {
+  const { judgmentJointAdd } = await import('../lib/judgment-writer.js');
+  return judgmentJointAdd(getTargetRoot(), args);
+}
+
+export async function toolJudgmentTransition(args) {
+  const { judgmentTransition } = await import('../lib/judgment-writer.js');
+  return judgmentTransition(getTargetRoot(), args);
+}
+
+export async function toolJudgmentLedgerAppend(args) {
+  const { judgmentLedgerAppend } = await import('../lib/judgment-writer.js');
+  return judgmentLedgerAppend(getTargetRoot(), args);
+}
+
+export async function toolJudgmentPersonWrite(args) {
+  const { judgmentPersonWrite } = await import('../lib/judgment-writer.js');
+  return judgmentPersonWrite(getTargetRoot(), args);
+}
+
+export async function toolJudgmentSituationWrite(args) {
+  const { judgmentSituationWrite } = await import('../lib/judgment-writer.js');
+  return judgmentSituationWrite(getTargetRoot(), args);
+}
+
+export async function toolJudgmentGoalWrite(args) {
+  const { judgmentGoalWrite } = await import('../lib/judgment-writer.js');
+  return judgmentGoalWrite(getTargetRoot(), args);
+}
+
+export async function toolGetJudgmentState() {
+  const { getJudgmentState } = await import('../lib/judgment-writer.js');
+  return getJudgmentState(getTargetRoot());
+}
+
 // ---------------------------------------------------------------------------
 // COMP-MCP-ENFORCE-1 — phase-scoped MCP tool gate (profile × phase)
 //
@@ -897,4 +946,3 @@ export function assertToolPhaseAllowed(tool, args = {}, _testCtx) {
     throw e;
   }
 }
-

package/server/compose-mcp.js

@@ -68,6 +68,15 @@ import {
   toolGetWorkspace,
   toolWriteCheckpoint,
   toolComposeResume,
+  toolJudgmentPositionCreate,
+  toolJudgmentPositionAmend,
+  toolJudgmentJointAdd,
+  toolJudgmentTransition,
+  toolJudgmentLedgerAppend,
+  toolJudgmentPersonWrite,
+  toolJudgmentSituationWrite,
+  toolJudgmentGoalWrite,
+  toolGetJudgmentState,
   _getBinding,
   assertToolPhaseAllowed,
   _getSessionProfile,
@@ -681,6 +690,208 @@ const TOOLS = [
       },
     },
   },
+
+  // -------------------------------------------------------------------------
+  // Judgment writer — COMP-JUDGMENT-WRITER (the only legitimate write path to
+  // docs/judgment canon; records canonical, markdown generated). Terse
+  // schemas by design (token budget); the writer self-validates against
+  // contracts/judgment-record.schema.json — inputSchema is advisory.
+  // -------------------------------------------------------------------------
+  {
+    name: 'judgment_position_create',
+    description: 'Create a judgment position revision (new chain, update, supersession via supersedes, or tombstone via retracted). ASSERT grounding requires an elicitation block. Provenance is writer-stamped.',
+    inputSchema: {
+      type: 'object',
+      required: ['slug', 'claims', 'conviction'],
+      properties: {
+        slug: { type: 'string' },
+        claims: { type: 'array', description: 'Claims: {id, text, grounding EXT|INT|ASSERT|DERIVED|AGENT, supports[], elicitation?}.' },
+        conviction: { type: 'object', description: '{level high|medium|low, source stated|inferred}' },
+        rejected_alternatives: { type: 'array', description: '{what, why}[]' },
+        supersedes: { type: 'string', description: '<slug>#r<N> being superseded.' },
+        retracted: { type: 'boolean', description: 'true → tombstone revision.' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_position_amend',
+    description: 'Scoped amendment (P6): new revision changing ONE claim\'s grounding and/or the conviction block. Anything else is supersession via judgment_position_create.',
+    inputSchema: {
+      type: 'object',
+      required: ['slug'],
+      properties: {
+        slug: { type: 'string' },
+        claim_id: { type: 'string' },
+        grounding: { type: 'string', description: 'New grounding for claim_id.' },
+        elicitation: { type: 'object', description: 'Required if new grounding is ASSERT.' },
+        conviction: { type: 'object' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_joint_add',
+    description: 'Add a judgment joint (born open). Both branches and a coarse cost bucket are required; EXT/STRADDLE method packages may be attached now or at dispose time.',
+    inputSchema: {
+      type: 'object',
+      required: ['slug', 'question', 'branch_true', 'branch_false', 'resolve_by', 'cost', 'rank'],
+      properties: {
+        slug: { type: 'string' },
+        question: { type: 'string' },
+        branch_true: { type: 'string' },
+        branch_false: { type: 'string' },
+        resolve_by: { type: 'string', description: 'EXT|INT|CONSTRUCT|ASSERT|STRADDLE' },
+        cost: { type: 'string', description: 'hours|days|weeks|months' },
+        rank: { type: 'string', description: 'high|medium' },
+        ext: { type: 'object', description: 'EXT package: {sharpened_question, bar, falsifier} or {judgment_dispatch: true, reason}.' },
+        straddle: { type: 'object', description: '{discriminating_signal, kill_criteria}' },
+        flags: { type: 'array' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_transition',
+    description: 'Joint state machine (edge→artifact table enforced; Stratum-guarded where capabilities.guard). Provide the target state plus its required artifact (resolution/dissolution/reopen/redispose), and/or a rank change (atomic rank ledger event).',
+    inputSchema: {
+      type: 'object',
+      required: ['slug'],
+      properties: {
+        slug: { type: 'string' },
+        to: { type: 'string', description: 'open|under_test|resolved|inconclusive|superseded|dissolved' },
+        resolution: { type: 'object', description: '{outcome resolved|inconclusive|failed_to_run|superseded, …outcome-specific fields, ext_result?, elicitation?}' },
+        dissolution: { type: 'object', description: '{decomposed_into[]}' },
+        reopen: { type: 'object', description: '{shaken_evidence_ref} (P6)' },
+        redispose: { type: 'object', description: '{new_resolve_by, ext?, straddle?} (retry inconclusive with a different method)' },
+        ext: { type: 'object', description: 'EXT package attached at dispose time.' },
+        straddle: { type: 'object' },
+        rank: { type: 'object', description: '{to: high|medium}' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_ledger_append',
+    description: 'Append a judgment ledger event (kind-specific required fields enforced: commit-decide needs trigger+open_joints+prediction; postmortem needs recall_verdict+attribution and grades prediction_ref; override needs reason). Commit/CONSTRUCT events spawn prediction records.',
+    inputSchema: {
+      type: 'object',
+      required: ['kind', 'title'],
+      properties: {
+        kind: { type: 'string', description: 'decide|kill|override|escalate|calibrate|postmortem|rank|note|correct|open' },
+        title: { type: 'string' },
+        body: { type: 'string' },
+        refs: { type: 'array' },
+        rejected: { type: 'array' },
+        conviction: { type: 'object' },
+        trigger: { type: 'string', description: 'On decide: earned|forced|exhausted (marks a commit-moment decide).' },
+        open_joints: { type: 'array' },
+        prediction: { type: 'object', description: '{text, outcome_criteria}' },
+        disposition: { type: 'string', description: 'Method disposed with; CONSTRUCT requires prediction.' },
+        recall_verdict: { type: 'string' },
+        attribution: { type: 'string' },
+        prediction_ref: { type: 'string' },
+        prediction_grade: { type: 'string', description: 'right|right-wrong-reason|wrong' },
+        reason: { type: 'string' },
+        rests_on: { type: 'array', description: 'On commit-moment decide: goal clause refs (goal:v<N>#c<N>) the commit rests on; resolved through the effective goal chain.' },
+        anchor: { type: 'string', description: 'On note: projection anchor (register-header, joint:<slug>, …).' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_person_write',
+    description: 'Write person canon by op. create adds a person; open_field supports create, fill, and reopen; edge/load_link support create and remove; correct supports divergence pair/clear. Provenance is writer-stamped.',
+    inputSchema: {
+      type: 'object',
+      required: ['op'],
+      properties: {
+        op: { type: 'string', enum: ['create', 'add_fact', 'correct', 'open_field', 'edge', 'load_link'] },
+        slug: { type: 'string' },
+        display_name: { type: 'string' },
+        section: { type: 'string', description: 'role|life|stated|revealed' },
+        text: { type: 'string' },
+        channel: { type: 'string', description: 'said|observed|secondhand|inferred' },
+        via: { type: 'string', description: 'Source attribution for a secondhand fact; not provenance.' },
+        at: { type: 'string', description: 'ISO date (YYYY-MM-DD).' },
+        fact_id: { type: 'string' },
+        pair_with: { type: 'string', description: 'Pair stated↔revealed divergence on correct.' },
+        clear: { type: 'array', description: 'On correct: exactly ["diverges_with"].', items: { type: 'string' } },
+        name: { type: 'string', description: 'open_field create branch.' },
+        open_field_id: { type: 'string' },
+        filled_by: { type: 'string' },
+        reopen: { type: 'boolean' },
+        reason: { type: 'string' },
+        to: { type: 'string', description: 'edge create branch target person slug.' },
+        kind: { type: 'string', description: 'edge create branch kind.' },
+        edge_id: { type: 'string' },
+        remove: { type: 'boolean' },
+        fact: { type: 'string', description: 'load_link create branch fact ID.' },
+        carries: { type: 'string' },
+        load_link_id: { type: 'string' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_situation_write',
+    description: 'Write situation-entity canon by op. create adds an entity; owed supports create, give, and reopen; load_link supports create and remove. Provenance is writer-stamped.',
+    inputSchema: {
+      type: 'object',
+      required: ['op'],
+      properties: {
+        op: { type: 'string', enum: ['create', 'add_fact', 'correct', 'owed', 'load_link'] },
+        slug: { type: 'string' },
+        display_name: { type: 'string' },
+        text: { type: 'string' },
+        channel: { type: 'string', description: 'said|observed|secondhand|inferred' },
+        via: { type: 'string', description: 'Source attribution for a secondhand fact; not provenance.' },
+        at: { type: 'string', description: 'ISO date (YYYY-MM-DD).' },
+        fact_id: { type: 'string' },
+        name: { type: 'string', description: 'owed create branch.' },
+        why_load_bearing: { type: 'string' },
+        owed_id: { type: 'string' },
+        filled_by: { type: 'string' },
+        reopen: { type: 'boolean' },
+        reason: { type: 'string' },
+        remove: { type: 'boolean' },
+        fact: { type: 'string', description: 'load_link create branch fact ID.' },
+        carries: { type: 'string' },
+        load_link_id: { type: 'string' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'judgment_goal_write',
+    description: 'Write goal canon by op. Ordinary cuts require elicited clauses, provocation, and owner ratification. Every non-migrate op is migration-locked while a live legacy objective requires migration; migrate is the one-shot, fail-closed cutover that lifts the lock and takes no payload. joint_link/load_link support create and remove. Provenance and intents are writer-owned.',
+    inputSchema: {
+      type: 'object',
+      required: ['op'],
+      properties: {
+        op: { type: 'string', enum: ['cut', 'correct', 'joint_link', 'load_link', 'migrate'] },
+        clauses: { type: 'array', description: 'cut: {text, channel, elicitation, secondhand source attribution?}[]' },
+        provocation: { type: 'object', description: 'cut: {quote, at}' },
+        ratification: { type: 'object', description: 'cut: {asked, answered_at, answer_ref, quote}' },
+        diff_note: { type: 'string' },
+        clause_id: { type: 'string', description: 'correct branch clause ID.' },
+        text: { type: 'string', description: 'correct branch replacement wording.' },
+        joint: { type: 'string', description: 'joint_link create branch joint slug.' },
+        joint_link_id: { type: 'string' },
+        remove: { type: 'boolean' },
+        reason: { type: 'string' },
+        clause: { type: 'string', description: 'load_link create branch v<N>#c<N> reference.' },
+        carries: { type: 'string' },
+        load_link_id: { type: 'string' },
+        idempotency_key: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'get_judgment_state',
+    description: 'Judgment canon snapshot: positions (derived status), joints, under-test, open predictions, recent ledger. Replays pending judgment intents first.',
+    inputSchema: { type: 'object', properties: {} },
+  },
 ];
 
 // ---------------------------------------------------------------------------
@@ -774,6 +985,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'propose_followup':         result = await toolProposeFollowup(args); break;
       case 'write_checkpoint':         result = await toolWriteCheckpoint(args); break;
       case 'compose_resume':           result = await toolComposeResume(args); break;
+      case 'judgment_position_create': result = await toolJudgmentPositionCreate(args); break;
+      case 'judgment_position_amend':  result = await toolJudgmentPositionAmend(args); break;
+      case 'judgment_joint_add':       result = await toolJudgmentJointAdd(args); break;
+      case 'judgment_transition':      result = await toolJudgmentTransition(args); break;
+      case 'judgment_ledger_append':   result = await toolJudgmentLedgerAppend(args); break;
+      case 'judgment_person_write':    result = await toolJudgmentPersonWrite(args); break;
+      case 'judgment_situation_write': result = await toolJudgmentSituationWrite(args); break;
+      case 'judgment_goal_write':      result = await toolJudgmentGoalWrite(args); break;
+      case 'get_judgment_state':       result = await toolGetJudgmentState(args); break;
       // agent_run removed — STRAT-DEDUP-AGENTRUN v1. Use mcp__stratum__stratum_agent_run.
       default:
         return {

package/server/mcp-tool-policy.js

@@ -36,6 +36,7 @@ const REVIEWER_ALLOW = [
   'get_pending_gates', 'get_changelog_entries', 'get_journal_entries', 'get_completions',
   'validate_feature', 'validate_project', 'roadmap_diff', 'get_roadmap', 'roadmap_graph_check', 'assess_feature_artifacts',
   'set_workspace', 'get_workspace', 'bind_session',
+  'get_judgment_state', // COMP-JUDGMENT-WRITER: read-only; the eight judgment write tools stay reviewer-denied
 ];
 
 export const PROFILE_POLICY = {