@moretea-labs/forge 1.8.0 → 1.8.2

package/scripts/check-mcp-compatibility.ts

@@ -1,46 +1,45 @@
 import { readFileSync } from 'fs';
 import { FORGE_TOOL_SURFACE, FORGE_VERSION, forgeToolSurfaceFingerprint } from '../src/cli/controller/runtime-config';
-import { runtimePolicy } from '../src/cli/mcp/multi-repository';
-import { buildMcpToolDefinitions } from '../src/cli/mcp/tools';
-import { accessToolDefinitions } from '../src/cli/mcp/access-tools';
-import { repositoryToolDefinitions } from '../src/cli/mcp/repository-tools';
-import { runtimeToolDefinitions } from '../src/runtime/gateway/mcp/runtime-tools';
-import { executionToolDefinitions } from '../src/runtime/gateway/mcp/execution-tools';
-import { processToolDefinitions } from '../src/runtime/gateway/mcp/process-tools';
-import {
-  buildPlanObligationCompatibilityCapability,
-  parseControllerRoundCompatibilityCapability,
-  parsePlanObligationCompatibilityCapability,
-} from '../adapters/mcp/controller-round-compatibility';
-import {
-  buildFrozenSemanticCompatibilityCapability,
-  parseFrozenSemanticCompatibilityCapability,
-} from '../adapters/mcp/frozen-client-semantic-compatibility';
-import {
-  ADVANCED_CONTROLLER_TOOL_NAMES,
-  CORE_CONTROLLER_TOOL_NAMES,
-  DEFAULT_CONTROLLER_TOOL_NAMES,
-  PREFERRED_FACADE_TOOL_NAMES,
-  STABLE_CONTROLLER_TOOL_NAMES,
-} from '../src/cli/mcp/toolset';
+import { injectCognitionSettlementFields } from '../adapters/mcp/runtime-gateway/cognition-settlement';
+import { injectDurableCommandFields } from '../adapters/mcp/runtime-gateway/router';
+import { runtimePolicy } from '../adapters/mcp/multi-repository';
+import { buildMcpToolDefinitions } from '../adapters/mcp/tool-mapping/tools';
+import { controllerExposureSnapshot } from '../adapters/mcp/toolset';
+import type { MultiRepositoryMcpToolContext } from '../adapters/mcp/multi-repository';
+import { accessToolDefinitions } from '../adapters/mcp/tool-mapping/access-tools';
+import { repositoryToolDefinitions } from '../adapters/mcp/tool-mapping/repository-tools';
+import { runtimeToolDefinitions } from '../adapters/mcp/runtime-gateway/runtime-tools';
+import { executionToolDefinitions } from '../adapters/mcp/runtime-gateway/execution-tools';
+import { processToolDefinitions } from '../adapters/mcp/runtime-gateway/process-tools';
+import { PREFERRED_CONTROLLER_TOOL_NAMES, PREFERRED_FACADE_TOOL_NAMES } from '../adapters/mcp/toolset';
 
-// The served ChatGPT schema is intentionally much smaller than the exhaustive
-// compatibility catalog. Keep a tight budget so accidental tool additions are
-// caught before they become discovery latency and schema-cache churn.
-const MAX_DEFAULT_TOOL_COUNT = 24;
+// The preferred model-routing list remains small; actual tools/list always
+// exposes the complete authoritative registry, without exposure modes.
+const MAX_PREFERRED_TOOL_COUNT = 24;
+const EXPECTED_EXPOSED_NAME_FINGERPRINT = '10db066a55335555';
 
 // #197 decomposition authority: the public/frozen Tool Contract is an explicit
 // baseline, independent from whichever internal adapter currently defines a
 // tool. Adapter extraction may move implementation ownership without silently
 // changing names, descriptions, input schemas, or annotations.
-const EXPECTED_STABLE_CONTROLLER_TOOL_NAMES = [
-  'rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work',
-  'repository_list', 'repository_get', 'repository_register', 'repository_command_execute',
+const EXPECTED_PREFERRED_CONTROLLER_TOOL_NAMES = [
+  'rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work', 'capability_execute',
+  'repository_list', 'repository_get', 'repository_register', 'execute_command',
   'read_repository_file', 'repository_safe_patch_apply', 'run_check', 'plugin_action_execute',
   'process_get', 'process_wait', 'process_logs', 'process_cancel', 'result_read', 'result_search',
 ] as const;
-const EXPECTED_STABLE_TOOL_NAME_FINGERPRINT = '8e6613493e480a26';
-const EXPECTED_STABLE_TOOL_SCHEMA_FINGERPRINT = 'a6c8a8cb0af7f7d8';
+// The stable bounded surface now includes the generic typed capability executor
+// already shipped on main. V3 Work objective relations intentionally extend only
+// the existing rh_work input schema; both changes must invalidate stale Connector
+// schema snapshots without adding a parallel execution or graph authority.
+const EXPECTED_PREFERRED_TOOL_NAME_FINGERPRINT = 'f22e635a213b45fa';
+// Every public object-schema tool carries shared transport metadata only through
+// the final tools/list materialization path. Tool schema revisions
+// intentionally invalidate stale Connector schema snapshots.
+// 2026-10-15: rh_context gained model-authored search_terms in 5a0f8d839.
+// Removing only that property from the current frozen surface reproduces the
+// preceding 9bd588d157f66fdf fingerprint; the new surface is intentional.
+const EXPECTED_PREFERRED_TOOL_SCHEMA_FINGERPRINT = '793a6c1d07070dc2';
 
 const policy = runtimePolicy(process.cwd(), {
   profile: 'controller',
@@ -62,192 +61,89 @@ const sourceGroups = Object.fromEntries(
 const allDefinitions = Object.values(sourceDefinitionGroups).flat();
 const definitionByName = new Map(allDefinitions.map((tool) => [tool.name, tool]));
 const fullNames = [...new Set(Object.values(sourceGroups).flat())];
-const defaultNames: string[] = [...DEFAULT_CONTROLLER_TOOL_NAMES];
-const coreNames: string[] = [...CORE_CONTROLLER_TOOL_NAMES];
-const advancedNames: string[] = [...ADVANCED_CONTROLLER_TOOL_NAMES];
-const catalogNames: string[] = [...STABLE_CONTROLLER_TOOL_NAMES];
+const defaultNames: string[] = [...PREFERRED_CONTROLLER_TOOL_NAMES];
 const preferredNames: string[] = [...PREFERRED_FACADE_TOOL_NAMES];
 const defaultFingerprint = forgeToolSurfaceFingerprint(defaultNames);
-const stableDefinitions = defaultNames.map((name) => definitionByName.get(name)).filter((tool) => tool !== undefined);
+const stableDefinitions = defaultNames
+  .map((name) => definitionByName.get(name)).filter((tool) => tool !== undefined)
+  .map((tool) => injectCognitionSettlementFields(injectDurableCommandFields(tool)));
 const stableSchemaFingerprint = forgeToolSurfaceFingerprint(stableDefinitions);
-const catalogFingerprint = forgeToolSurfaceFingerprint(catalogNames);
 const fullFingerprint = forgeToolSurfaceFingerprint(fullNames);
 const duplicateDefault = defaultNames.filter((name, index) => defaultNames.indexOf(name) !== index);
 const missingDefault = defaultNames.filter((name) => !fullNames.includes(name));
-const missingCatalog = catalogNames.filter((name) => !fullNames.includes(name));
 const sourceCollisions = Object.entries(sourceGroups).flatMap(([group, names], groupIndex, entries) =>
   names.filter((name) => entries.slice(0, groupIndex).some(([, earlier]) => earlier.includes(name)))
     .map((name) => `${group}:${name}`));
-const currentToolNames = new Set([
-  ...sourceGroups.runtime,
-  ...sourceGroups.execution,
-  ...sourceGroups.process,
-  ...sourceGroups.access,
-  ...sourceGroups.repository,
-]);
-const legacyHandlerSource = readFileSync(new URL('../src/cli/mcp/legacy-tool-service.ts', import.meta.url), 'utf8');
-const legacyHandlerNames = [...legacyHandlerSource.matchAll(/case\s+["']([^"']+)["']\s*:/g)].map((match) => match[1]);
-const legacyHandlerCollisions = [...new Set(legacyHandlerNames.filter((name) => currentToolNames.has(name)))].sort();
+const recoveryMcpSource = readFileSync(new URL('../src/runtime/standalone-recovery/mcp-server.ts', import.meta.url), 'utf8');
+const recoveryStatelessMarkers = [
+  'createMcpHandler',
+  'toNodeHandler',
+  "legacy: 'stateless'",
+  "responseMode: 'auto'",
+];
+const recoverySessionAuthorityMarkers = [
+  'McpSessionRegistry',
+  'NodeStreamableHTTPServerTransport',
+  'Mcp-Session-Reset',
+  'sessionIdGenerator',
+];
 
 const failures: string[] = [];
-if (defaultNames.join('\n') !== EXPECTED_STABLE_CONTROLLER_TOOL_NAMES.join('\n')) {
-  failures.push(`stable ChatGPT Tool Contract names changed: ${defaultNames.join(', ')}`);
+for (const marker of recoveryStatelessMarkers) {
+  if (!recoveryMcpSource.includes(marker)) {
+    failures.push(`Standalone Recovery MCP must remain stateless across protocol eras: missing ${marker}`);
+  }
 }
-if (defaultFingerprint !== EXPECTED_STABLE_TOOL_NAME_FINGERPRINT) {
-  failures.push(`stable ChatGPT tool-name fingerprint changed: ${defaultFingerprint} != ${EXPECTED_STABLE_TOOL_NAME_FINGERPRINT}`);
+for (const marker of recoverySessionAuthorityMarkers) {
+  if (recoveryMcpSource.includes(marker)) {
+    failures.push(`Standalone Recovery MCP must not own transport-session state: found ${marker}`);
+  }
 }
-if (stableDefinitions.length !== defaultNames.length) {
-  failures.push(`stable ChatGPT Tool Contract definitions are incomplete: ${stableDefinitions.length}/${defaultNames.length}`);
-} else if (stableSchemaFingerprint !== EXPECTED_STABLE_TOOL_SCHEMA_FINGERPRINT) {
-  failures.push(`stable ChatGPT Tool Contract schema fingerprint changed: ${stableSchemaFingerprint} != ${EXPECTED_STABLE_TOOL_SCHEMA_FINGERPRINT}`);
+if (defaultNames.join('\n') !== EXPECTED_PREFERRED_CONTROLLER_TOOL_NAMES.join('\n')) {
+  failures.push(`preferred-name schema contract names changed: ${defaultNames.join(', ')}`);
 }
-if (defaultNames.length > MAX_DEFAULT_TOOL_COUNT) {
-  failures.push(`default ChatGPT tools/list exceeds the schema budget: ${defaultNames.length} > ${MAX_DEFAULT_TOOL_COUNT}`);
+if (defaultFingerprint !== EXPECTED_PREFERRED_TOOL_NAME_FINGERPRINT) {
+  failures.push(`stable ChatGPT tool-name fingerprint changed: ${defaultFingerprint} != ${EXPECTED_PREFERRED_TOOL_NAME_FINGERPRINT}`);
 }
-if (duplicateDefault.length) failures.push(`default duplicate names: ${[...new Set(duplicateDefault)].join(', ')}`);
-if (missingDefault.length) failures.push(`default tools missing from registered definitions: ${missingDefault.join(', ')}`);
-if (missingCatalog.length) failures.push(`compatibility catalog tools missing from registered definitions: ${missingCatalog.join(', ')}`);
-if (sourceCollisions.length) failures.push(`tool schema authority collisions: ${sourceCollisions.join(', ')}`);
-if (legacyHandlerCollisions.length) failures.push(`legacy execution authority collisions: ${legacyHandlerCollisions.join(', ')}`);
-if (coreNames.join('\n') !== defaultNames.join('\n')) {
-  failures.push('core surface must alias the bounded default ChatGPT surface');
+if (stableDefinitions.length !== defaultNames.length) {
+  failures.push(`preferred-name schema contract definitions are incomplete: ${stableDefinitions.length}/${defaultNames.length}`);
+} else if (stableSchemaFingerprint !== EXPECTED_PREFERRED_TOOL_SCHEMA_FINGERPRINT) {
+  failures.push(`preferred-name schema contract schema fingerprint changed: ${stableSchemaFingerprint} != ${EXPECTED_PREFERRED_TOOL_SCHEMA_FINGERPRINT}`);
 }
-if (advancedNames.join('\n') !== defaultNames.join('\n')) {
-  failures.push('advanced surface must alias the bounded default ChatGPT surface');
+if (defaultNames.length > MAX_PREFERRED_TOOL_COUNT) {
+  failures.push(`preferred controller tool list exceeds its advisory size budget: ${defaultNames.length} > ${MAX_PREFERRED_TOOL_COUNT}`);
 }
+if (duplicateDefault.length) failures.push(`preferred-name duplicate names: ${[...new Set(duplicateDefault)].join(', ')}`);
+if (missingDefault.length) failures.push(`preferred tools missing from registered definitions: ${missingDefault.join(', ')}`);
+if (sourceCollisions.length) failures.push(`tool schema authority collisions: ${sourceCollisions.join(', ')}`);
 for (const name of ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work']) {
   if (!preferredNames.includes(name)) failures.push(`preferred facade surface missing: ${name}`);
-  if (!defaultNames.includes(name)) failures.push(`default surface missing facade tool: ${name}`);
+  if (!defaultNames.includes(name)) failures.push(`preferred list missing facade tool: ${name}`);
 }
 if (fullNames.length < defaultNames.length) {
-  failures.push(`full compatibility surface is smaller than default surface: ${fullNames.length} < ${defaultNames.length}`);
+  failures.push('complete MCP registry is missing preferred capability names');
 }
-
-const rhWorkDefinition = runtimeToolDefinitions.find((tool) => tool.name === 'rh_work');
-const rhWorkProperties = (rhWorkDefinition?.inputSchema?.properties ?? {}) as Record<string, unknown>;
-if (!('capability_id' in rhWorkProperties)) failures.push('rh_work compatibility carrier capability_id is missing');
-if (!('obligation_dispositions' in rhWorkProperties)) failures.push('rh_work native obligation_dispositions schema is missing');
-
-const planCompatibilityFixture = [
-  {
-    predecessor_plan_id: 'PLAN-predecessor',
-    obligation_id: 'step:p0:acceptance:0',
-    disposition: 'change' as const,
-    successor_refs: ['step:p0:acceptance:0'],
-    rationale: 'successor expands the same obligation',
-  },
-  {
-    predecessor_plan_id: 'PLAN-predecessor',
-    obligation_id: 'step:p1',
-    disposition: 'keep' as const,
-    successor_refs: ['step:p1'],
-  },
-];
-try {
-  const capability = buildPlanObligationCompatibilityCapability(planCompatibilityFixture);
-  const parsed = parsePlanObligationCompatibilityCapability('plan_create', capability);
-  if (JSON.stringify(parsed) !== JSON.stringify(planCompatibilityFixture)) {
-    failures.push('frozen Plan obligation compatibility round-trip changed the typed payload');
-  }
-  if (parsePlanObligationCompatibilityCapability('repair', capability) !== undefined) {
-    failures.push('frozen Plan obligation compatibility must be scoped to plan_create');
-  }
-  try {
-    parsePlanObligationCompatibilityCapability('plan_create', 'plan.obligations.v1:not+base64');
-    failures.push('frozen Plan obligation compatibility accepted malformed payload');
-  } catch {
-    // Expected: malformed frozen-client transport input remains fail-closed.
-  }
-} catch (error) {
-  failures.push(`frozen Plan obligation compatibility failed: ${error instanceof Error ? error.message : String(error)}`);
+if (fullFingerprint !== EXPECTED_EXPOSED_NAME_FINGERPRINT) {
+  failures.push(`complete MCP tool-name fingerprint changed: ${fullFingerprint} != ${EXPECTED_EXPOSED_NAME_FINGERPRINT}`);
 }
-
-try {
-  const authorityId = `cra_${'a'.repeat(32)}`;
-  const relayScopeId = 'goal:work-frozen-review-compatibility';
-  const parsedReview = parseControllerRoundCompatibilityCapability(
-    'repair',
-    `controller.round:review:approved:${authorityId}:${relayScopeId}`,
-  );
-  if (JSON.stringify(parsedReview) !== JSON.stringify({ operation: 'review', authorityId, relayScopeId, reviewDecision: 'approved' })) {
-    failures.push('frozen ControllerRound review compatibility changed authority, scope, or review decision');
-  }
-  const parsedVerify = parseControllerRoundCompatibilityCapability(
-    'repair',
-    `controller.round:verify:${authorityId}:${relayScopeId}`,
-  );
-  if (JSON.stringify(parsedVerify) !== JSON.stringify({ operation: 'verify', authorityId, relayScopeId })) {
-    failures.push('legacy ControllerRound compatibility changed non-review operation semantics');
-  }
-  for (const invalid of [
-    `controller.round:review:${authorityId}:${relayScopeId}`,
-    `controller.round:review:maybe:${authorityId}:${relayScopeId}`,
-  ]) {
-    try {
-      parseControllerRoundCompatibilityCapability('repair', invalid);
-      failures.push('frozen ControllerRound review compatibility accepted a missing or invalid explicit decision');
-    } catch {
-      // Expected: frozen review must carry one explicit canonical review decision.
-    }
-  }
-} catch (error) {
-  failures.push(`frozen ControllerRound review compatibility failed: ${error instanceof Error ? error.message : String(error)}`);
+const projectedNames = controllerExposureSnapshot({
+  policy, toolset: 'full', controllerHome: process.cwd(), repoRoot: process.cwd(),
+} as MultiRepositoryMcpToolContext).actualToolNames.sort();
+if (projectedNames.join('\n') !== [...fullNames].sort().join('\n')) {
+  failures.push('controller_capabilities expectation differs from the complete MCP registry');
 }
 
-try {
-  const semanticFixture = {
-    operation: 'requirement_create' as const,
-    args: {
-      requirement_title: 'Frozen semantic compatibility',
-      requirement_outcome: 'Use the canonical Requirement authority through an old rh_work schema.',
-      requirement_acceptance_criteria: ['Compatibility remains transport-only.'],
-    },
-  };
-  const capability = buildFrozenSemanticCompatibilityCapability(semanticFixture);
-  const parsed = parseFrozenSemanticCompatibilityCapability('repair', capability);
-  if (JSON.stringify(parsed) !== JSON.stringify(semanticFixture)) {
-    failures.push('frozen semantic compatibility round-trip changed the typed payload');
-  }
-  const planFixture = {
-    operation: 'plan_create' as const,
-    args: {
-      obligation_dispositions: [{
-        predecessor_plan_id: 'PLAN-R1',
-        obligation_id: 'obl-example',
-        disposition: 'keep' as const,
-        successor_refs: ['step:implementation'],
-      }],
-    },
-  };
-  const planCapability = buildFrozenSemanticCompatibilityCapability(planFixture);
-  const parsedPlan = parseFrozenSemanticCompatibilityCapability('repair', planCapability);
-  if (JSON.stringify(parsedPlan) !== JSON.stringify(planFixture)) {
-    failures.push('frozen Plan successor semantic compatibility changed obligation dispositions');
-  }
-  try {
-    parseFrozenSemanticCompatibilityCapability('plan_create', capability);
-    failures.push('frozen semantic compatibility accepted a non-repair transport operation');
-  } catch {
-    // Expected: the generic semantic envelope is reachable only through the stable repair transport.
-  }
-  const unknownOperation = `semantic.v1:${Buffer.from(JSON.stringify({ v: 1, op: 'finalize', a: {} }), 'utf8').toString('base64url')}`;
-  try {
-    parseFrozenSemanticCompatibilityCapability('repair', unknownOperation);
-    failures.push('frozen semantic compatibility accepted an operation outside the explicit allowlist');
-  } catch {
-    // Expected: compatibility cannot grow into an arbitrary-operation tunnel.
-  }
-  const unknownField = `semantic.v1:${Buffer.from(JSON.stringify({ v: 1, op: 'requirement_create', a: { requirement_title: 'x', requirement_outcome: 'y', remote_write: true } }), 'utf8').toString('base64url')}`;
-  try {
-    parseFrozenSemanticCompatibilityCapability('repair', unknownField);
-    failures.push('frozen semantic compatibility accepted an unknown operation argument');
-  } catch {
-    // Expected: each allowlisted operation has an exact transport schema.
-  }
-} catch (error) {
-  failures.push(`frozen semantic compatibility failed: ${error instanceof Error ? error.message : String(error)}`);
+const rhWorkDefinition = runtimeToolDefinitions.find((tool) => tool.name === 'rh_work');
+const rhWorkProperties = (rhWorkDefinition?.inputSchema?.properties ?? {}) as Record<string, unknown>;
+for (const field of [
+  'checkout_id',
+  'workflow_id',
+  'workflow_run_id',
+  'outcome_observation',
+  'experience_draft',
+] as const) {
+  if (!(field in rhWorkProperties)) failures.push(`stable rh_work Tool Contract missing ${field}`);
 }
-
 if (failures.length) {
   console.error('[mcp-compatibility] FAILED');
   for (const failure of failures) console.error(`- ${failure}`);
@@ -258,16 +154,13 @@ console.log(JSON.stringify({
   status: 'ok',
   toolSurface: FORGE_TOOL_SURFACE,
   version: FORGE_VERSION,
-  stableToolCount: defaultNames.length,
-  stableFingerprint: defaultFingerprint,
-  stableSchemaFingerprint,
-  defaultToolBudget: MAX_DEFAULT_TOOL_COUNT,
-  compatibilityCatalogToolCount: catalogNames.length,
-  compatibilityCatalogFingerprint: catalogFingerprint,
-  fullCompatibilityToolCount: fullNames.length,
-  fullCompatibilityFingerprint: fullFingerprint,
+  preferredToolCount: defaultNames.length,
+  preferredFingerprint: defaultFingerprint,
+  preferredSchemaFingerprint: stableSchemaFingerprint,
+  preferredToolBudget: MAX_PREFERRED_TOOL_COUNT,
+  exposedToolCount: fullNames.length,
+  exposedNameFingerprint: fullFingerprint,
   sourceToolCounts: Object.fromEntries(Object.entries(sourceGroups).map(([name, tools]) => [name, tools.length])),
   sourceCollisions: [...new Set(sourceCollisions)].sort(),
-  legacyHandlerCollisions,
   accessModeChangesSchema: false,
 }, null, 2));

package/scripts/check-package-identity.mjs

@@ -8,7 +8,6 @@ const scriptDir = dirname(fileURLToPath(import.meta.url));
 const root = resolve(scriptDir, "..");
 const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
 const lock = JSON.parse(readFileSync(resolve(root, "package-lock.json"), "utf8"));
-const skill = JSON.parse(readFileSync(resolve(root, "assets/skill-version.json"), "utf8"));
 
 const expectedName = "@moretea-labs/forge";
 const requiredFiles = [
@@ -62,10 +61,6 @@ function requireReusableTarballPublisher() {
 if (pkg.name !== expectedName) fail(`package.json name is ${pkg.name}`);
 const versionMatch = String(pkg.version ?? "").match(/^(\d+\.\d+\.\d+)(?:-rc\.(\d+))?$/);
 if (!versionMatch) fail(`package.json version is not a stable or rc semantic version: ${pkg.version}`);
-const coreVersion = versionMatch[1];
-if (coreVersion !== skill.version || coreVersion !== skill.templateVersion) {
-  fail(`package core version ${coreVersion} must match workflow versions ${skill.version}/${skill.templateVersion}`);
-}
 if (pkg.publishConfig?.access !== "public") fail("publishConfig.access must be public");
 if (pkg.publishConfig?.provenance !== true) fail("publishConfig.provenance must be true");
 if (pkg.publishConfig?.tag !== undefined) fail("publishConfig.tag must be omitted");