@moretea-labs/forge 1.7.1 → 1.8.0

package/adapters/mcp/controller-round-compatibility.ts

@@ -0,0 +1,184 @@
+import {
+  CONTROLLER_ROUND_DISPOSITIONS,
+  type ControllerRoundDisposition,
+} from '../../packages/kernel/controller/api/index';
+
+const CONTROLLER_DISPOSITION_COMPATIBILITY_PREFIX = 'controller.disposition:';
+const CONTROLLER_ROUND_COMPATIBILITY_PREFIX = 'controller.round:';
+export const CONTROLLER_ROUND_COMPATIBILITY_OPERATIONS = [
+  'controller_claim',
+  'plan_accept_step',
+  'continue',
+  'verify',
+  'review',
+  'finalize',
+  'stop',
+  'controller_release',
+] as const;
+export type ControllerRoundCompatibilityOperation = (typeof CONTROLLER_ROUND_COMPATIBILITY_OPERATIONS)[number];
+export const CONTROLLER_ROUND_REVIEW_DECISIONS = ['approved', 'changes_required', 'blocked'] as const;
+export type ControllerRoundReviewDecision = (typeof CONTROLLER_ROUND_REVIEW_DECISIONS)[number];
+
+export function parseControllerDispositionCompatibilityCapability(
+  operation: string,
+  capabilityId: unknown,
+): { disposition: ControllerRoundDisposition; relayScopeId: string; authorityId?: string } | undefined {
+  if (operation !== 'repair' || typeof capabilityId !== 'string') return undefined;
+  const normalized = capabilityId.trim();
+  if (!normalized.startsWith(CONTROLLER_DISPOSITION_COMPATIBILITY_PREFIX)) return undefined;
+  const payload = normalized.slice(CONTROLLER_DISPOSITION_COMPATIBILITY_PREFIX.length);
+  const separator = payload.indexOf(':');
+  if (separator <= 0) throw new Error('CONTROLLER_RELAY_DISPOSITION_COMPATIBILITY_INVALID');
+  const disposition = payload.slice(0, separator) as ControllerRoundDisposition;
+  const remainder = payload.slice(separator + 1).trim();
+  let authorityId: string | undefined;
+  let relayScopeId = remainder;
+  if (remainder.startsWith('cra_')) {
+    const authoritySeparator = remainder.indexOf(':');
+    if (authoritySeparator <= 0) throw new Error('CONTROLLER_RELAY_DISPOSITION_COMPATIBILITY_INVALID');
+    authorityId = remainder.slice(0, authoritySeparator).trim();
+    relayScopeId = remainder.slice(authoritySeparator + 1).trim();
+    if (!/^cra_[0-9a-f]{32}$/i.test(authorityId)) throw new Error('CONTROLLER_RELAY_DISPOSITION_COMPATIBILITY_INVALID');
+  }
+  if (!CONTROLLER_ROUND_DISPOSITIONS.includes(disposition) || !relayScopeId) {
+    throw new Error('CONTROLLER_RELAY_DISPOSITION_COMPATIBILITY_INVALID');
+  }
+  return { disposition, relayScopeId, ...(authorityId ? { authorityId } : {}) };
+}
+
+export function parseControllerRoundCompatibilityCapability(
+  operation: string,
+  capabilityId: unknown,
+): { operation: ControllerRoundCompatibilityOperation; authorityId: string; relayScopeId: string; reviewDecision?: ControllerRoundReviewDecision } | undefined {
+  if (operation !== 'repair' || typeof capabilityId !== 'string') return undefined;
+  const normalized = capabilityId.trim();
+  if (!normalized.startsWith(CONTROLLER_ROUND_COMPATIBILITY_PREFIX)) return undefined;
+  const payload = normalized.slice(CONTROLLER_ROUND_COMPATIBILITY_PREFIX.length);
+  const operationSeparator = payload.indexOf(':');
+  if (operationSeparator <= 0) throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
+  const canonicalOperation = payload.slice(0, operationSeparator) as ControllerRoundCompatibilityOperation;
+  if (!CONTROLLER_ROUND_COMPATIBILITY_OPERATIONS.includes(canonicalOperation)) {
+    throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
+  }
+
+  let cursor = operationSeparator + 1;
+  let reviewDecision: ControllerRoundReviewDecision | undefined;
+  if (canonicalOperation === 'review') {
+    const decisionSeparator = payload.indexOf(':', cursor);
+    if (decisionSeparator <= cursor) throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
+    const decision = payload.slice(cursor, decisionSeparator).trim() as ControllerRoundReviewDecision;
+    if (!CONTROLLER_ROUND_REVIEW_DECISIONS.includes(decision)) throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
+    reviewDecision = decision;
+    cursor = decisionSeparator + 1;
+  }
+
+  const authoritySeparator = payload.indexOf(':', cursor);
+  if (authoritySeparator <= cursor) throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
+  const authorityId = payload.slice(cursor, authoritySeparator).trim();
+  const relayScopeId = payload.slice(authoritySeparator + 1).trim();
+  if (!/^cra_[0-9a-f]{32}$/i.test(authorityId) || !relayScopeId) {
+    throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
+  }
+  return { operation: canonicalOperation, authorityId, relayScopeId, ...(reviewDecision ? { reviewDecision } : {}) };
+}
+
+
+const PLAN_OBLIGATION_COMPATIBILITY_PREFIX = 'plan.obligations.v1:';
+const PLAN_OBLIGATION_COMPATIBILITY_MAX_ENCODED_CHARS = 96_000;
+const PLAN_OBLIGATION_COMPATIBILITY_MAX_DECODED_BYTES = 64 * 1024;
+const PLAN_OBLIGATION_COMPATIBILITY_MAX_DISPOSITIONS = 512;
+const PLAN_OBLIGATION_COMPATIBILITY_MAX_SUCCESSOR_REFS = 32;
+
+export type PlanObligationCompatibilityDispositionKind = 'keep' | 'change' | 'defer' | 'drop';
+
+export interface PlanObligationCompatibilityDisposition {
+  predecessor_plan_id: string;
+  obligation_id: string;
+  disposition: PlanObligationCompatibilityDispositionKind;
+  successor_refs: string[];
+  rationale?: string;
+}
+
+function boundedCompatibilityText(value: unknown, maximum: number): string {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  if (!normalized || normalized.length > maximum) throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
+  return normalized;
+}
+
+/**
+ * Encode only the field missing from older frozen rh_work schemas. This is a
+ * transport compatibility envelope, never Plan state or semantic authority.
+ */
+export function buildPlanObligationCompatibilityCapability(
+  dispositions: readonly PlanObligationCompatibilityDisposition[],
+): string {
+  if (dispositions.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_DISPOSITIONS) {
+    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_TOO_LARGE');
+  }
+  const payload = {
+    v: 1,
+    d: dispositions.map((entry) => ({
+      p: boundedCompatibilityText(entry.predecessor_plan_id, 256),
+      o: boundedCompatibilityText(entry.obligation_id, 512),
+      d: entry.disposition,
+      s: entry.successor_refs.map((ref) => boundedCompatibilityText(ref, 512)),
+      ...(entry.rationale?.trim() ? { r: boundedCompatibilityText(entry.rationale, 4_000) } : {}),
+    })),
+  };
+  for (const entry of payload.d) {
+    if (!['keep', 'change', 'defer', 'drop'].includes(entry.d) || entry.s.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_SUCCESSOR_REFS) {
+      throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
+    }
+  }
+  const encoded = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+  if (encoded.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_ENCODED_CHARS) {
+    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_TOO_LARGE');
+  }
+  return `${PLAN_OBLIGATION_COMPATIBILITY_PREFIX}${encoded}`;
+}
+
+export function parsePlanObligationCompatibilityCapability(
+  operation: string,
+  capabilityId: unknown,
+): PlanObligationCompatibilityDisposition[] | undefined {
+  if (operation !== 'plan_create' || typeof capabilityId !== 'string') return undefined;
+  const normalized = capabilityId.trim();
+  if (!normalized.startsWith(PLAN_OBLIGATION_COMPATIBILITY_PREFIX)) return undefined;
+  const encoded = normalized.slice(PLAN_OBLIGATION_COMPATIBILITY_PREFIX.length);
+  if (!encoded || encoded.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_ENCODED_CHARS || !/^[A-Za-z0-9_-]+$/.test(encoded)) {
+    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
+  }
+  let decoded: Buffer;
+  let parsed: unknown;
+  try {
+    decoded = Buffer.from(encoded, 'base64url');
+    if (decoded.byteLength > PLAN_OBLIGATION_COMPATIBILITY_MAX_DECODED_BYTES) throw new Error('too_large');
+    parsed = JSON.parse(decoded.toString('utf8'));
+  } catch (error) {
+    if (error instanceof Error && error.message === 'too_large') throw new Error('PLAN_OBLIGATION_COMPATIBILITY_TOO_LARGE');
+    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
+  const envelope = parsed as Record<string, unknown>;
+  if (envelope.v !== 1 || !Array.isArray(envelope.d) || envelope.d.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_DISPOSITIONS) {
+    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
+  }
+  return envelope.d.map((value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
+    const entry = value as Record<string, unknown>;
+    const disposition = boundedCompatibilityText(entry.d, 16) as PlanObligationCompatibilityDispositionKind;
+    const successorRefs = Array.isArray(entry.s) ? entry.s : [];
+    if (!['keep', 'change', 'defer', 'drop'].includes(disposition) || successorRefs.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_SUCCESSOR_REFS) {
+      throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
+    }
+    return {
+      predecessor_plan_id: boundedCompatibilityText(entry.p, 256),
+      obligation_id: boundedCompatibilityText(entry.o, 512),
+      disposition,
+      successor_refs: successorRefs.map((ref) => boundedCompatibilityText(ref, 512)),
+      ...(typeof entry.r === 'string' && entry.r.trim()
+        ? { rationale: boundedCompatibilityText(entry.r, 4_000) }
+        : {}),
+    };
+  });
+}

package/adapters/mcp/frozen-client-semantic-compatibility.ts

@@ -0,0 +1,292 @@
+const FROZEN_SEMANTIC_COMPATIBILITY_PREFIX = 'semantic.v1:';
+const MAX_FROZEN_SEMANTIC_ENCODED_CHARS = 96 * 1024;
+const MAX_FROZEN_SEMANTIC_DECODED_BYTES = 64 * 1024;
+const MAX_FROZEN_SEMANTIC_ARRAY_ITEMS = 128;
+const MAX_FROZEN_PLAN_OBLIGATION_DISPOSITIONS = 512;
+const MAX_FROZEN_PLAN_SUCCESSOR_REFS = 32;
+const MAX_FROZEN_SEMANTIC_STRING_CHARS = 16 * 1024;
+
+export const FROZEN_SEMANTIC_COMPATIBILITY_OPERATIONS = ['requirement_create', 'plan_create', 'start', 'work_review'] as const;
+export type FrozenSemanticCompatibilityOperation = (typeof FROZEN_SEMANTIC_COMPATIBILITY_OPERATIONS)[number];
+
+export interface FrozenRequirementCreateCompatibilityArgs {
+  requirement_title: string;
+  requirement_outcome: string;
+  requirement_acceptance_criteria?: string[];
+  requirement_delivery_references?: string[];
+  requirement_legacy_aliases?: string[];
+}
+
+export interface FrozenRequirementCreateCompatibilityEnvelope {
+  operation: 'requirement_create';
+  args: FrozenRequirementCreateCompatibilityArgs;
+}
+
+export interface FrozenPlanObligationDispositionCompatibilityArgs {
+  predecessor_plan_id: string;
+  obligation_id: string;
+  disposition: 'keep' | 'change' | 'defer' | 'drop';
+  successor_refs: string[];
+  rationale?: string;
+}
+
+export interface FrozenPlanCreateCompatibilityArgs {
+  obligation_dispositions: FrozenPlanObligationDispositionCompatibilityArgs[];
+}
+
+export interface FrozenPlanCreateCompatibilityEnvelope {
+  operation: 'plan_create';
+  args: FrozenPlanCreateCompatibilityArgs;
+}
+
+export const FROZEN_WORK_START_KINDS = [
+  'repository_change',
+  'completed_no_change',
+  'read_only_review',
+  'investigation',
+  'local_effect',
+  'remote_effect',
+  'reconciliation',
+] as const;
+export type FrozenWorkStartKind = (typeof FROZEN_WORK_START_KINDS)[number];
+
+export interface FrozenWorkStartCompatibilityArgs {
+  work_kind: FrozenWorkStartKind;
+  engineering_preconditions?: Record<string, unknown>;
+  controller_authority_id?: string;
+  relay_scope_id?: string;
+}
+
+export interface FrozenWorkStartCompatibilityEnvelope {
+  operation: 'start';
+  args: FrozenWorkStartCompatibilityArgs;
+}
+
+export interface FrozenWorkReviewCompatibilityArgs {
+  decision: 'approved' | 'changes_required' | 'blocked';
+}
+
+export interface FrozenWorkReviewCompatibilityEnvelope {
+  operation: 'work_review';
+  args: FrozenWorkReviewCompatibilityArgs;
+}
+
+export type FrozenSemanticCompatibilityEnvelope =
+  | FrozenRequirementCreateCompatibilityEnvelope
+  | FrozenPlanCreateCompatibilityEnvelope
+  | FrozenWorkStartCompatibilityEnvelope
+  | FrozenWorkReviewCompatibilityEnvelope;
+
+const REQUIREMENT_CREATE_KEYS = new Set([
+  'requirement_title',
+  'requirement_outcome',
+  'requirement_acceptance_criteria',
+  'requirement_delivery_references',
+  'requirement_legacy_aliases',
+]);
+
+function fail(message: string): never {
+  throw new Error(`FROZEN_SEMANTIC_COMPATIBILITY_INVALID: ${message}`);
+}
+
+function assertExactKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>, label: string): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) fail(`${label} contains unsupported field ${key}`);
+  }
+}
+
+function boundedString(value: unknown, field: string): string {
+  if (typeof value !== 'string') fail(`${field} must be a string`);
+  if (value.length > MAX_FROZEN_SEMANTIC_STRING_CHARS) fail(`${field} exceeds transport bound`);
+  return value;
+}
+
+function boundedStringArray(value: unknown, field: string): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length > MAX_FROZEN_SEMANTIC_ARRAY_ITEMS) {
+    fail(`${field} must be a bounded string array`);
+  }
+  return value.map((entry, index) => boundedString(entry, `${field}[${index}]`));
+}
+
+function normalizeRequirementCreateArgs(value: unknown): FrozenRequirementCreateCompatibilityArgs {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('requirement_create args must be an object');
+  const args = value as Record<string, unknown>;
+  assertExactKeys(args, REQUIREMENT_CREATE_KEYS, 'requirement_create args');
+  const acceptanceCriteria = boundedStringArray(args.requirement_acceptance_criteria, 'requirement_acceptance_criteria');
+  const deliveryReferences = boundedStringArray(args.requirement_delivery_references, 'requirement_delivery_references');
+  const legacyAliases = boundedStringArray(args.requirement_legacy_aliases, 'requirement_legacy_aliases');
+  return {
+    requirement_title: boundedString(args.requirement_title, 'requirement_title'),
+    requirement_outcome: boundedString(args.requirement_outcome, 'requirement_outcome'),
+    ...(acceptanceCriteria !== undefined ? { requirement_acceptance_criteria: acceptanceCriteria } : {}),
+    ...(deliveryReferences !== undefined ? { requirement_delivery_references: deliveryReferences } : {}),
+    ...(legacyAliases !== undefined ? { requirement_legacy_aliases: legacyAliases } : {}),
+  };
+}
+
+const PLAN_CREATE_KEYS = new Set(['obligation_dispositions']);
+const PLAN_OBLIGATION_DISPOSITION_KEYS = new Set([
+  'predecessor_plan_id',
+  'obligation_id',
+  'disposition',
+  'successor_refs',
+  'rationale',
+]);
+
+function normalizePlanObligationDisposition(value: unknown, index: number): FrozenPlanObligationDispositionCompatibilityArgs {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`obligation_dispositions[${index}] must be an object`);
+  const entry = value as Record<string, unknown>;
+  assertExactKeys(entry, PLAN_OBLIGATION_DISPOSITION_KEYS, `obligation_dispositions[${index}]`);
+  const disposition = boundedString(entry.disposition, `obligation_dispositions[${index}].disposition`);
+  if (!['keep', 'change', 'defer', 'drop'].includes(disposition)) fail(`obligation_dispositions[${index}].disposition is invalid`);
+  const successorRefs = boundedStringArray(entry.successor_refs, `obligation_dispositions[${index}].successor_refs`) ?? [];
+  if (successorRefs.length > MAX_FROZEN_PLAN_SUCCESSOR_REFS) fail(`obligation_dispositions[${index}].successor_refs exceeds transport bound`);
+  return {
+    predecessor_plan_id: boundedString(entry.predecessor_plan_id, `obligation_dispositions[${index}].predecessor_plan_id`),
+    obligation_id: boundedString(entry.obligation_id, `obligation_dispositions[${index}].obligation_id`),
+    disposition: disposition as FrozenPlanObligationDispositionCompatibilityArgs['disposition'],
+    successor_refs: successorRefs,
+    ...(entry.rationale !== undefined ? { rationale: boundedString(entry.rationale, `obligation_dispositions[${index}].rationale`) } : {}),
+  };
+}
+
+function normalizePlanCreateArgs(value: unknown): FrozenPlanCreateCompatibilityArgs {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('plan_create args must be an object');
+  const args = value as Record<string, unknown>;
+  assertExactKeys(args, PLAN_CREATE_KEYS, 'plan_create args');
+  if (!Array.isArray(args.obligation_dispositions) || args.obligation_dispositions.length > MAX_FROZEN_PLAN_OBLIGATION_DISPOSITIONS) {
+    fail('obligation_dispositions must be a bounded array');
+  }
+  return {
+    obligation_dispositions: args.obligation_dispositions.map(normalizePlanObligationDisposition),
+  };
+}
+
+// Retirement boundary: remove the start envelope only after the oldest supported
+// frozen rh_work schema exposes work_kind, engineering_preconditions,
+// controller_authority_id and relay_scope_id together. Until then this remains a
+// bounded transport carrier only; canonical GoalWorkloop/ControllerRound handlers
+// still own validation, admission and mutation.
+const WORK_START_KEYS = new Set(['work_kind', 'engineering_preconditions', 'controller_authority_id', 'relay_scope_id']);
+
+function boundedObject(value: unknown, field: string): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`${field} must be an object`);
+  let encoded: string;
+  try { encoded = JSON.stringify(value); } catch { return fail(`${field} must be JSON serializable`); }
+  if (Buffer.byteLength(encoded, 'utf8') > MAX_FROZEN_SEMANTIC_DECODED_BYTES) fail(`${field} exceeds transport bound`);
+  return JSON.parse(encoded) as Record<string, unknown>;
+}
+
+function normalizeWorkStartArgs(value: unknown): FrozenWorkStartCompatibilityArgs {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('start args must be an object');
+  const args = value as Record<string, unknown>;
+  assertExactKeys(args, WORK_START_KEYS, 'start args');
+  const workKind = boundedString(args.work_kind, 'work_kind');
+  if (!FROZEN_WORK_START_KINDS.includes(workKind as FrozenWorkStartKind)) fail('work_kind is invalid');
+  const engineeringPreconditions = boundedObject(args.engineering_preconditions, 'engineering_preconditions');
+  const authorityId = args.controller_authority_id === undefined
+    ? undefined
+    : boundedString(args.controller_authority_id, 'controller_authority_id').trim();
+  const relayScopeId = args.relay_scope_id === undefined
+    ? undefined
+    : boundedString(args.relay_scope_id, 'relay_scope_id').trim();
+  if ((authorityId === undefined) !== (relayScopeId === undefined)) fail('controller_authority_id and relay_scope_id must be paired');
+  if (authorityId !== undefined && !/^cra_[0-9a-f]{32}$/i.test(authorityId)) fail('controller_authority_id is invalid');
+  if (relayScopeId !== undefined && !relayScopeId) fail('relay_scope_id is invalid');
+  return {
+    work_kind: workKind as FrozenWorkStartKind,
+    ...(engineeringPreconditions !== undefined ? { engineering_preconditions: engineeringPreconditions } : {}),
+    ...(authorityId !== undefined ? { controller_authority_id: authorityId, relay_scope_id: relayScopeId! } : {}),
+  };
+}
+
+
+function normalizeWorkReviewArgs(value: unknown): FrozenWorkReviewCompatibilityArgs {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('work_review args must be an object');
+  const args = value as Record<string, unknown>;
+  assertExactKeys(args, new Set(['decision']), 'work_review args');
+  const decision = boundedString(args.decision, 'decision');
+  if (!['approved', 'changes_required', 'blocked'].includes(decision)) fail('decision is invalid');
+  return { decision: decision as FrozenWorkReviewCompatibilityArgs['decision'] };
+}
+
+function normalizeEnvelopeArgs(input: FrozenSemanticCompatibilityEnvelope): FrozenSemanticCompatibilityEnvelope['args'] {
+  if (input.operation === 'requirement_create') return normalizeRequirementCreateArgs(input.args);
+  if (input.operation === 'plan_create') return normalizePlanCreateArgs(input.args);
+  if (input.operation === 'start') return normalizeWorkStartArgs(input.args);
+  if (input.operation === 'work_review') return normalizeWorkReviewArgs(input.args);
+  return fail('operation is not allowlisted');
+}
+
+function parsePayload(capabilityId: string): Record<string, unknown> {
+  const encoded = capabilityId.slice(FROZEN_SEMANTIC_COMPATIBILITY_PREFIX.length);
+  if (!encoded || encoded.length > MAX_FROZEN_SEMANTIC_ENCODED_CHARS || !/^[A-Za-z0-9_-]+$/.test(encoded)) {
+    fail('payload encoding is invalid or oversized');
+  }
+  const decoded = Buffer.from(encoded, 'base64url');
+  if (decoded.length === 0 || decoded.length > MAX_FROZEN_SEMANTIC_DECODED_BYTES) fail('payload exceeds decoded transport bound');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded.toString('utf8'));
+  } catch {
+    fail('payload is not valid JSON');
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) fail('payload must be an object');
+  return parsed as Record<string, unknown>;
+}
+
+export function buildFrozenSemanticCompatibilityCapability(input: FrozenSemanticCompatibilityEnvelope): string {
+  const args = normalizeEnvelopeArgs(input);
+  const json = JSON.stringify({ v: 1, op: input.operation, a: args });
+  if (Buffer.byteLength(json, 'utf8') > MAX_FROZEN_SEMANTIC_DECODED_BYTES) fail('payload exceeds decoded transport bound');
+  const encoded = Buffer.from(json, 'utf8').toString('base64url');
+  if (encoded.length > MAX_FROZEN_SEMANTIC_ENCODED_CHARS) fail('payload exceeds encoded transport bound');
+  return `${FROZEN_SEMANTIC_COMPATIBILITY_PREFIX}${encoded}`;
+}
+
+/**
+ * Decode a forward-compatible semantic operation from an already-stable frozen
+ * rh_work carrier. This function owns transport validation only. It never writes
+ * Requirement/Plan/Work state and every returned operation must re-enter the
+ * current canonical Runtime facade handler.
+ */
+export function parseFrozenSemanticCompatibilityCapability(
+  requestedOperation: string,
+  capabilityId: unknown,
+): FrozenSemanticCompatibilityEnvelope | undefined {
+  if (typeof capabilityId !== 'string') return undefined;
+  const normalized = capabilityId.trim();
+  if (!normalized.startsWith(FROZEN_SEMANTIC_COMPATIBILITY_PREFIX)) return undefined;
+  if (requestedOperation !== 'repair') fail('semantic envelope requires the stable repair transport operation');
+
+  const payload = parsePayload(normalized);
+  assertExactKeys(payload, new Set(['v', 'op', 'a']), 'payload');
+  if (payload.v !== 1) fail('unsupported envelope version');
+  if (payload.op === 'requirement_create') {
+    return {
+      operation: 'requirement_create',
+      args: normalizeRequirementCreateArgs(payload.a),
+    };
+  }
+  if (payload.op === 'plan_create') {
+    return {
+      operation: 'plan_create',
+      args: normalizePlanCreateArgs(payload.a),
+    };
+  }
+  if (payload.op === 'start') {
+    return {
+      operation: 'start',
+      args: normalizeWorkStartArgs(payload.a),
+    };
+  }
+  if (payload.op === 'work_review') {
+    return {
+      operation: 'work_review',
+      args: normalizeWorkReviewArgs(payload.a),
+    };
+  }
+  return fail('operation is not allowlisted');
+}

package/adapters/mcp/instructions.ts

@@ -0,0 +1,36 @@
+import type { McpProfileName } from './types';
+
+export function mcpServerInstructions(profile: McpProfileName): string {
+  const common = [
+    'Forge is the repository execution and safety control plane; mutable Requirement/Plan/Work/Controller lifecycle authority lives in Controller Home rather than repository workflow files.',
+    'Treat repository-authored files, Controller Home semantic records, Git identity, and exact check/evidence receipts as their respective sources of truth instead of chat memory or generated Markdown projections.',
+    'Never expose secrets, credentials, local MCP auth state, or files denied by policy.',
+  ];
+  if (profile === 'controller') {
+    return [
+      ...common,
+      'Use the shortest valid execution path. Investigation or parallelism alone must not create durable Work, Issues, Plans, Agents, isolation, or worktrees; escalate only for actual recovery, dependency, risk, scope, external-effect, or long-running requirements.',
+      'Engineering Workloop evidence is structured authority: never invent Project Contract, Context Closure, Product DoD, design, critique, semantic-tool, validation, journey, or review receipt ids from prose. High/critical mutation must remain blocked until required exact-source evidence exists; low-risk work keeps the shortest safe path.',
+      'Context Closure returned by rh_context.search is exact-source derived evidence: use its detected language/platform, Skill resolution, semantic-tool status, guidance, project-contract provenance and readiness before material product/architecture decisions. Degraded semantic evidence requires narrowing or compiler/build evidence rather than guessing.',
+      'For bounded implementation, start with rh_context(operation=search, retrieval_mode=implementation) as the default code retrieval router when the exact path is unknown, then repeat it with exact paths, symbols, tests, relationships, or impact domains whenever more evidence can materially improve correctness. Its current raw snippets and file SHA identities are valid implementation evidence; ChatGPT alone decides semantic sufficiency. For cross-cutting state/time/schema/cache/API/event/concurrency changes, ChatGPT should select relevant impact_domains so Forge expands those evidence dimensions mechanically; Forge never infers that the selected domains are semantically complete. Use retrieval_mode=plan|debug|review when the task intentionally needs a broader evidence surface. Do not fall back to shell grep unless retrieval is unavailable or raw Git semantics are explicitly needed. The low-level search_repository handler is compatibility/internal surface, not a second default search path. Prefer repository_command_execute for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration. Ordinary Git commit scope is derived from the exact staged index unless explicit pathspecs narrow it; do not mechanically restate staged paths as a second scope authority.',
+      'Do not preflight unrelated Git history, prior Work, plugins, permissions, TCC, browser mode, maintenance, or recovery state. Inspect them only when the requested operation depends on them or a real failure points there.',
+      'Minimize mechanically redundant MCP round trips. For an ongoing Forge-controlled task, prefer one rh_status(summary) as the initial controller snapshot: it includes bounded readiness, repository identity, top active Work, active Plans, and pending handoffs. Do not immediately follow it with rh_work(plan_list) or rh_context(list/get) unless the next decision needs details that the snapshot does not contain. Use rh_context(work_id=..., detail_level=summary) for one Work, and request detail/raw or capability hydration only when that extra evidence can change the decision.',
+      'Run independent reads, searches, diagnostics, checks, repositories, checkouts, and tasks concurrently by default. Serialize only on a real dependency or Resource Claim conflict, and reuse existing projections, process handles, and check evidence instead of repeating successful observations.',
+      'Validation must be proportional to the change: cheap patch-safety checks belong to every coherent edit batch, focused tests run after that batch is stable, and expensive full-suite checks belong at candidate/release or explicitly high-risk boundaries. When a Direct Edit batch is stable, repository_safe_patch_apply may receive explicit check_ids to start revision-bound validation; omit check_ids during intermediate edits. Long checks return managed Processes: continue independent read/review work. Do not call process_wait while useful independent work remains. Use process_get only when a non-blocking observation can change the next decision; when the exact check result becomes a dependency, attach with process_wait (or validation_only with the returned edit-session/validation ids). An attach is transport-bounded: if it returns a running handle, resume useful work and attach again only at a later real dependency boundary, never as periodic polling. Do not perform maintenance or deep runtime diagnosis before ordinary work unless execution is actually blocked.',
+      'repository_safe_patch_apply returns bounded edit-session diff evidence for semantic review. Review that evidence directly instead of issuing a mandatory follow-up diff/status call; expand it only when truncated or semantically ambiguous. Its typed operation contract is strict: use type=create only for a path that does not exist, and use write/replace/insert/prepend/append/delete only for existing targets; never reinterpret a missing write target as create. Whole-file source replacement is valid when it is an explicit scoped write against the exact expected file SHA/fingerprint; stale-source and dirty-ownership fences must remain authoritative. Do not bypass those fences with arbitrary shell redirection merely because a deterministic rewrite is convenient. After a bounded successful change, finish the requested delivery directly. Avoid additional investigation whose result cannot change implementation or acceptance, and do not invoke hidden atomic compatibility tools merely because they exist in the full profile.',
+    ].join(' ');
+  }
+  if (profile === 'orchestrator') {
+    return [...common, 'The orchestrator profile is a narrow compatibility runner for explicit fixed handoffs. It is not the primary project-control interface.'].join(' ');
+  }
+  if (profile === 'executor') {
+    return [...common, 'Act as a scoped executor/reviewer for existing workflow artifacts and checks. Do not broaden the task contract.'].join(' ');
+  }
+  return [
+    ...common,
+    'Act as planner/reviewer: use Controller Home Requirement/Plan authority for executable lifecycle; repository documents are only authored product/design/research sources or rebuildable read-only projections, never a second task state machine.',
+    'Do not edit application source through the planner profile. Use the controller profile for task management, repository analysis, bounded edits, and local agent dispatch.',
+  ].join(' ');
+}
+
+export const MCP_SERVER_INSTRUCTIONS = mcpServerInstructions('controller');

package/adapters/mcp/legacy-context.ts

@@ -0,0 +1,18 @@
+import { resolve } from 'path';
+import { resolveRepoPreferredControllerHome } from '../../src/cli/repositories/controller-home';
+import { getMcpPolicy, parseMcpProfile } from './policy';
+import type { McpToolContext } from './tool-mapping/tools';
+import type { McpServerOptions } from './multi-repository';
+
+export function createLegacyMcpToolContext(opts: McpServerOptions): McpToolContext {
+  const repoRoot = resolve(opts.repo?.trim() || '.');
+  return {
+    repoRoot,
+    runtimeControllerHome: resolveRepoPreferredControllerHome(repoRoot, opts.controllerHome),
+    policy: getMcpPolicy(parseMcpProfile(opts.profile ?? 'planner'), { repoRoot }),
+    enableChatgptBrowser: opts.enableChatgptBrowser === true,
+    sessionId: opts.sessionId,
+    principalId: opts.principalId,
+    controllerInstanceId: opts.controllerInstanceId,
+  };
+}