let-them-talk 5.2.5 → 5.4.0

package/events/schema.js

@@ -0,0 +1,432 @@
+const EVENT_STREAMS = Object.freeze({
+  RUNTIME: 'runtime',
+  BRANCH: 'branch',
+});
+
+const CANONICAL_EVENT_SCHEMA_VERSION = 1;
+
+const REQUIRED_EVENT_ENVELOPE_FIELDS = Object.freeze([
+  'event_id',
+  'stream',
+  'branch_id',
+  'seq',
+  'type',
+  'occurred_at',
+  'schema_version',
+  'actor_agent',
+  'session_id',
+  'command_id',
+  'causation_id',
+  'correlation_id',
+  'payload',
+]);
+
+const DEFAULT_COLLABORATION_STREAM = EVENT_STREAMS.BRANCH;
+
+const EVENT_SCOPE_SPLIT = Object.freeze({
+  defaultStream: DEFAULT_COLLABORATION_STREAM,
+  runtimeGlobalFamilies: Object.freeze([
+    'agent',
+    'profile',
+    'lock',
+    'branch',
+    'migration',
+  ]),
+  branchLocalFamilies: Object.freeze([
+    'session',
+    'conversation',
+    'message',
+    'task',
+    'workflow',
+    'workspace',
+    'decision',
+    'kb',
+    'review',
+    'dependency',
+    'vote',
+    'rule',
+    'progress',
+    'evidence',
+  ]),
+});
+
+function resolveFamilyStream(family) {
+  return EVENT_SCOPE_SPLIT.runtimeGlobalFamilies.includes(family)
+    ? EVENT_STREAMS.RUNTIME
+    : EVENT_SCOPE_SPLIT.defaultStream;
+}
+
+function freezeFamilyDefinition(definition) {
+  return Object.freeze({
+    family: definition.family,
+    scope: definition.scope,
+    projectionTargets: Object.freeze([...definition.projectionTargets]),
+    types: Object.freeze([...definition.types]),
+    summary: definition.summary,
+  });
+}
+
+const FAMILY_DEFINITIONS = Object.freeze([
+  freezeFamilyDefinition({
+    family: 'agent',
+    scope: resolveFamilyStream('agent'),
+    projectionTargets: ['agents-index', 'sessions-index'],
+    types: [
+      'agent.registered',
+      'agent.unregistered',
+      'agent.status_updated',
+      'agent.heartbeat_recorded',
+      'agent.branch_assigned',
+      'agent.listening_updated',
+    ],
+    summary: 'Runtime-global agent identity, liveness, and branch-assignment state.',
+  }),
+  freezeFamilyDefinition({
+    family: 'profile',
+    scope: resolveFamilyStream('profile'),
+    projectionTargets: ['profiles'],
+    types: ['profile.updated'],
+    summary: 'Runtime-global agent profile updates.',
+  }),
+  freezeFamilyDefinition({
+    family: 'lock',
+    scope: resolveFamilyStream('lock'),
+    projectionTargets: ['locks'],
+    types: ['lock.acquired', 'lock.released'],
+    summary: 'Runtime-global file lock ownership with branch/session context when present.',
+  }),
+  freezeFamilyDefinition({
+    family: 'branch',
+    scope: resolveFamilyStream('branch'),
+    projectionTargets: ['branch-index'],
+    types: ['branch.created'],
+    summary: 'Runtime-global branch registry lifecycle.',
+  }),
+  freezeFamilyDefinition({
+    family: 'migration',
+    scope: resolveFamilyStream('migration'),
+    projectionTargets: ['manifest'],
+    types: ['migration.started', 'migration.completed', 'migration.failed'],
+    summary: 'Runtime-global storage/runtime migration metadata.',
+  }),
+  freezeFamilyDefinition({
+    family: 'session',
+    scope: resolveFamilyStream('session'),
+    projectionTargets: ['sessions', 'sessions-index'],
+    types: [
+      'session.started',
+      'session.resumed',
+      'session.interrupted',
+      'session.completed',
+      'session.failed',
+      'session.abandoned',
+    ],
+    summary: 'Branch-scoped agent execution lifecycle and recovery state.',
+  }),
+  freezeFamilyDefinition({
+    family: 'conversation',
+    scope: resolveFamilyStream('conversation'),
+    projectionTargets: ['conversation'],
+    types: [
+      'conversation.mode_updated',
+      'conversation.channel_joined',
+      'conversation.channel_left',
+      'conversation.manager_claimed',
+      'conversation.phase_updated',
+      'conversation.floor_yielded',
+    ],
+    summary: 'Branch-local conversation mode, channel, and managed-floor state.',
+  }),
+  freezeFamilyDefinition({
+    family: 'message',
+    scope: resolveFamilyStream('message'),
+    projectionTargets: ['messages', 'history'],
+    types: ['message.sent', 'message.corrected', 'message.redacted'],
+    summary: 'Branch-local collaboration message stream and historical corrections.',
+  }),
+  freezeFamilyDefinition({
+    family: 'task',
+    scope: resolveFamilyStream('task'),
+    projectionTargets: ['tasks'],
+    types: ['task.created', 'task.updated', 'task.claimed', 'task.completed'],
+    summary: 'Branch-local task planning and status transitions.',
+  }),
+  freezeFamilyDefinition({
+    family: 'workflow',
+    scope: resolveFamilyStream('workflow'),
+    projectionTargets: ['workflows'],
+    types: [
+      'workflow.created',
+      'workflow.step_started',
+      'workflow.step_completed',
+      'workflow.step_reassigned',
+      'workflow.completed',
+      'workflow.paused',
+      'workflow.resumed',
+      'workflow.stopped',
+    ],
+    summary: 'Branch-local workflow lifecycle and step handoff state.',
+  }),
+  freezeFamilyDefinition({
+    family: 'workspace',
+    scope: resolveFamilyStream('workspace'),
+    projectionTargets: ['workspaces'],
+    types: ['workspace.written'],
+    summary: 'Branch-local per-agent workspace and memory materialization.',
+  }),
+  freezeFamilyDefinition({
+    family: 'decision',
+    scope: resolveFamilyStream('decision'),
+    projectionTargets: ['decisions'],
+    types: ['decision.logged'],
+    summary: 'Branch-local decision log entries.',
+  }),
+  freezeFamilyDefinition({
+    family: 'kb',
+    scope: resolveFamilyStream('kb'),
+    projectionTargets: ['kb'],
+    types: ['kb.written'],
+    summary: 'Branch-local shared knowledge base entries.',
+  }),
+  freezeFamilyDefinition({
+    family: 'review',
+    scope: resolveFamilyStream('review'),
+    projectionTargets: ['reviews'],
+    types: ['review.requested', 'review.submitted'],
+    summary: 'Branch-local review requests and review results.',
+  }),
+  freezeFamilyDefinition({
+    family: 'dependency',
+    scope: resolveFamilyStream('dependency'),
+    projectionTargets: ['dependencies'],
+    types: ['dependency.declared', 'dependency.resolved'],
+    summary: 'Branch-local blocked-work dependency graph changes.',
+  }),
+  freezeFamilyDefinition({
+    family: 'vote',
+    scope: resolveFamilyStream('vote'),
+    projectionTargets: ['votes'],
+    types: ['vote.called', 'vote.cast', 'vote.resolved'],
+    summary: 'Branch-local governance votes and outcomes.',
+  }),
+  freezeFamilyDefinition({
+    family: 'rule',
+    scope: resolveFamilyStream('rule'),
+    projectionTargets: ['rules'],
+    types: ['rule.added', 'rule.toggled', 'rule.removed'],
+    summary: 'Branch-local project rule lifecycle.',
+  }),
+  freezeFamilyDefinition({
+    family: 'progress',
+    scope: resolveFamilyStream('progress'),
+    projectionTargets: ['progress'],
+    types: ['progress.updated'],
+    summary: 'Branch-local feature progress reporting.',
+  }),
+  freezeFamilyDefinition({
+    family: 'evidence',
+    scope: resolveFamilyStream('evidence'),
+    projectionTargets: ['evidence'],
+    types: ['evidence.recorded'],
+    summary: 'Branch-local evidence records backing completion and advancement claims.',
+  }),
+]);
+
+const EVENT_FAMILY_REGISTRY = Object.freeze(
+  Object.fromEntries(FAMILY_DEFINITIONS.map((definition) => [definition.family, definition]))
+);
+
+const EVENT_TYPE_REGISTRY = Object.freeze(
+  Object.fromEntries(
+    FAMILY_DEFINITIONS.flatMap((definition) =>
+      definition.types.map((type) => [
+        type,
+        Object.freeze({
+          type,
+          family: definition.family,
+          scope: definition.scope,
+          projectionTargets: definition.projectionTargets,
+        }),
+      ])
+    )
+  )
+);
+
+function getEventFamily(type) {
+  if (typeof type !== 'string') return null;
+  const separatorIndex = type.indexOf('.');
+  return separatorIndex === -1 ? null : type.slice(0, separatorIndex);
+}
+
+function getEventFamilyDefinition(family) {
+  return EVENT_FAMILY_REGISTRY[family] || null;
+}
+
+function getEventTypeDefinition(type) {
+  return EVENT_TYPE_REGISTRY[type] || null;
+}
+
+function resolveTypeStream(type) {
+  const definition = getEventTypeDefinition(type);
+  if (definition) return definition.scope;
+  const family = getEventFamily(type);
+  return family ? resolveFamilyStream(family) : null;
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateMessageSentPayload(payload) {
+  const problems = [];
+  if (!isPlainObject(payload)) {
+    problems.push('message.sent events require payload to be an object.');
+    return problems;
+  }
+
+  if (!isPlainObject(payload.message)) {
+    problems.push('message.sent events require payload.message to be an object.');
+  }
+
+  return problems;
+}
+
+function validateMessageCorrectedPayload(payload) {
+  const problems = [];
+  if (!isPlainObject(payload)) {
+    problems.push('message.corrected events require payload to be an object.');
+    return problems;
+  }
+
+  if (typeof payload.message_id !== 'string' || payload.message_id.length === 0) {
+    problems.push('message.corrected events require payload.message_id to be a non-empty string.');
+  }
+  if (typeof payload.content !== 'string') {
+    problems.push('message.corrected events require payload.content to be a string.');
+  }
+  if ('edited_at' in payload && (typeof payload.edited_at !== 'string' || payload.edited_at.length === 0)) {
+    problems.push('message.corrected events require payload.edited_at to be a non-empty string when provided.');
+  }
+  if ('max_edit_history' in payload && (!Number.isInteger(payload.max_edit_history) || payload.max_edit_history <= 0)) {
+    problems.push('message.corrected events require payload.max_edit_history to be a positive integer when provided.');
+  }
+
+  return problems;
+}
+
+function validateMessageRedactedPayload(payload) {
+  const problems = [];
+  if (!isPlainObject(payload)) {
+    problems.push('message.redacted events require payload to be an object.');
+    return problems;
+  }
+
+  if (typeof payload.message_id !== 'string' || payload.message_id.length === 0) {
+    problems.push('message.redacted events require payload.message_id to be a non-empty string.');
+  }
+  if ('redacted_at' in payload && (typeof payload.redacted_at !== 'string' || payload.redacted_at.length === 0)) {
+    problems.push('message.redacted events require payload.redacted_at to be a non-empty string when provided.');
+  }
+
+  return problems;
+}
+
+function validateEventPayload(type, payload) {
+  switch (type) {
+    case 'message.sent':
+      return validateMessageSentPayload(payload);
+    case 'message.corrected':
+      return validateMessageCorrectedPayload(payload);
+    case 'message.redacted':
+      return validateMessageRedactedPayload(payload);
+    default:
+      return [];
+  }
+}
+
+/**
+ * @typedef {'runtime' | 'branch'} CanonicalEventStream
+ */
+
+/**
+ * @typedef {Object} CanonicalEvent
+ * @property {string} event_id
+ * @property {CanonicalEventStream} stream
+ * @property {string | null} branch_id
+ * @property {number} seq
+ * @property {string} type
+ * @property {string} occurred_at
+ * @property {number} schema_version
+ * @property {string} actor_agent
+ * @property {string | null} session_id
+ * @property {string | null} command_id
+ * @property {string | null} causation_id
+ * @property {string | null} correlation_id
+ * @property {*} payload
+ */
+
+function validateCanonicalEvent(event) {
+  const problems = [];
+
+  if (!event || typeof event !== 'object' || Array.isArray(event)) {
+    return {
+      ok: false,
+      problems: ['Canonical event must be an object.'],
+      definition: null,
+    };
+  }
+
+  for (const field of REQUIRED_EVENT_ENVELOPE_FIELDS) {
+    if (!(field in event)) {
+      problems.push(`Missing required envelope field: ${field}`);
+    }
+  }
+
+  if (!Object.values(EVENT_STREAMS).includes(event.stream)) {
+    problems.push(`Invalid event stream: ${String(event.stream)}`);
+  }
+
+  if (!Number.isInteger(event.seq) || event.seq < 0) {
+    problems.push('seq must be a non-negative integer.');
+  }
+
+  const definition = getEventTypeDefinition(event.type);
+  if (!definition) {
+    problems.push(`Unknown canonical event type: ${String(event.type)}`);
+  } else if (event.stream !== definition.scope) {
+    problems.push(`Event type ${event.type} belongs on the ${definition.scope} stream, received ${String(event.stream)}.`);
+  }
+
+  if (event.stream === EVENT_STREAMS.BRANCH && !event.branch_id) {
+    problems.push('Branch stream events must include branch_id.');
+  }
+
+  if (event.schema_version !== CANONICAL_EVENT_SCHEMA_VERSION) {
+    problems.push(`schema_version must equal ${CANONICAL_EVENT_SCHEMA_VERSION}.`);
+  }
+
+  problems.push(...validateEventPayload(event.type, event.payload));
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    definition,
+  };
+}
+
+module.exports = {
+  CANONICAL_EVENT_SCHEMA_VERSION,
+  DEFAULT_COLLABORATION_STREAM,
+  EVENT_FAMILY_REGISTRY,
+  EVENT_SCOPE_SPLIT,
+  EVENT_STREAMS,
+  EVENT_TYPE_REGISTRY,
+  FAMILY_DEFINITIONS,
+  REQUIRED_EVENT_ENVELOPE_FIELDS,
+  getEventFamily,
+  getEventFamilyDefinition,
+  getEventTypeDefinition,
+  resolveFamilyStream,
+  resolveTypeStream,
+  validateCanonicalEvent,
+};

package/managed-team-integration.js

@@ -0,0 +1,261 @@
+const {
+  analyzeContractFit,
+  buildRuntimeContractMetadata,
+} = require('./agent-contracts');
+
+const MANAGED_TEAM_HOOK_TOPICS = Object.freeze([
+  'conversation.mode_updated',
+  'conversation.manager_claimed',
+  'conversation.floor_yielded',
+  'conversation.phase_updated',
+  'task.created',
+  'task.claimed',
+  'task.completed',
+  'workflow.created',
+  'workflow.step_started',
+  'workflow.step_completed',
+  'workflow.step_reassigned',
+  'workflow.completed',
+  'review.requested',
+  'review.submitted',
+  'dependency.declared',
+  'dependency.resolved',
+]);
+
+function cloneJsonValue(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function normalizeBranchName(branchName) {
+  return typeof branchName === 'string' && branchName.trim() ? branchName.trim() : 'main';
+}
+
+function resolveManagedTeamContractTarget(surface, options = {}) {
+  const defaults = {
+    claim_manager: {
+      work_type: 'managed_manager',
+      title: 'Managed mode manager controls',
+      description: 'Claim manager control, coordinate the team, delegate work, manage floor control, and set phases.',
+      assigned: true,
+    },
+    manager_briefing: {
+      work_type: 'team_coordination',
+      title: 'Managed/team coordination briefing',
+      description: 'Coordinate the team, track workflow progress, review recent coordination changes, and manage shared execution state.',
+      assigned: true,
+    },
+    manager_listen: {
+      work_type: 'team_coordination',
+      title: 'Managed/team coordination updates',
+      description: 'Process managed/team coordination updates, delegate next actions, and steer the team loop.',
+      assigned: true,
+    },
+    participant_briefing: {
+      work_type: 'messages',
+      title: 'Managed/team execution briefing',
+      description: 'Process team messages, workflow coordination updates, and manager guidance.',
+      assigned: true,
+    },
+    participant_listen: {
+      work_type: 'messages',
+      title: 'Managed/team execution updates',
+      description: 'Process team messages, workflow coordination updates, and manager guidance.',
+      assigned: true,
+    },
+    team_briefing: {
+      work_type: 'team_coordination',
+      title: 'Team coordination briefing',
+      description: 'Review recent workflow coordination, team-wide state changes, and shared execution progress.',
+      assigned: true,
+    },
+    team_listen: {
+      work_type: 'messages',
+      title: 'Team coordination updates',
+      description: 'Process shared team messages and workflow coordination updates.',
+      assigned: true,
+    },
+    yield_floor: {
+      work_type: 'team_coordination',
+      title: 'Managed mode floor control',
+      description: 'Coordinate which teammate should speak next and keep the managed conversation moving.',
+      assigned: true,
+    },
+    set_phase: {
+      work_type: 'team_coordination',
+      title: 'Managed mode phase control',
+      description: 'Set the managed team phase and coordinate how the team should operate next.',
+      assigned: true,
+    },
+  };
+
+  const base = defaults[surface] || defaults.team_listen;
+  return Object.assign({}, base, options.target || {});
+}
+
+function buildContractAdvisoryMetadata(contract, advisory, surface) {
+  if (!contract || !advisory) return null;
+  const metadata = buildRuntimeContractMetadata(contract);
+  return Object.assign({
+    surface,
+    archetype: metadata.contract ? metadata.contract.archetype : null,
+    declared_archetype: metadata.archetype || null,
+    role: contract.role || '',
+    role_token: contract.role_token || null,
+    skills: metadata.skills,
+    effective_skills: metadata.contract ? metadata.contract.effective_skills : [],
+    contract_mode: metadata.contract_mode,
+  }, advisory);
+}
+
+function buildManagedTeamContractContext(contract, surface, options = {}) {
+  if (!contract) return null;
+
+  const target = resolveManagedTeamContractTarget(surface, options);
+  const advisory = analyzeContractFit(contract, target);
+  const contractAdvisory = buildContractAdvisoryMetadata(contract, advisory, surface);
+
+  const shouldHardBlock = !!(
+    surface === 'claim_manager'
+    && contract.contract_mode === 'strict'
+    && contract.has_explicit_contract
+    && advisory
+    && advisory.status === 'mismatch'
+  );
+
+  let contractViolation = null;
+  if (advisory && (advisory.status === 'mismatch' || advisory.status === 'partial' || shouldHardBlock)) {
+    contractViolation = {
+      surface,
+      status: shouldHardBlock ? 'blocked' : 'warning',
+      advisory_status: advisory.status,
+      contract_mode: contract.contract_mode,
+      message: shouldHardBlock
+        ? `Strict contract mismatch: ${advisory.summary}`
+        : advisory.summary,
+      migration_note: advisory.migration_note || null,
+    };
+  }
+
+  return {
+    target,
+    advisory,
+    contract_advisory: contractAdvisory,
+    contract_violation: contractViolation,
+  };
+}
+
+function buildHookSummary(hook) {
+  const payload = hook && hook.payload && typeof hook.payload === 'object' ? hook.payload : {};
+  const topic = hook && hook.topic ? hook.topic : 'unknown';
+  let summary = topic;
+  let details = {};
+
+  switch (topic) {
+    case 'conversation.mode_updated':
+      summary = `Conversation mode changed from ${payload.previous_mode || 'unknown'} to ${payload.mode || 'unknown'}.`;
+      details = { mode: payload.mode || null, previous_mode: payload.previous_mode || null };
+      break;
+    case 'conversation.manager_claimed':
+      summary = `${payload.manager || hook.actor_agent || 'An agent'} claimed manager controls.`;
+      details = { manager: payload.manager || null, previous_manager: payload.previous_manager || null, phase: payload.phase || null, floor: payload.floor || null };
+      break;
+    case 'conversation.floor_yielded':
+      summary = payload.floor === 'closed'
+        ? 'The manager closed the floor.'
+        : `The floor was set to ${payload.floor || 'unknown'}${payload.to ? ` for ${payload.to}` : ''}.`;
+      details = { floor: payload.floor || null, to: payload.to || null, turn_queue: Array.isArray(payload.turn_queue) ? [...payload.turn_queue] : [] };
+      break;
+    case 'conversation.phase_updated':
+      summary = `Managed phase changed from ${payload.previous_phase || 'unknown'} to ${payload.phase || 'unknown'}.`;
+      details = { phase: payload.phase || null, previous_phase: payload.previous_phase || null, floor: payload.floor || null };
+      break;
+    case 'task.created':
+      summary = `Task "${payload.title || payload.task_id || 'unknown'}" was created.`;
+      details = { task_id: payload.task_id || null, title: payload.title || null, assignee: payload.assignee || null };
+      break;
+    case 'task.claimed':
+      summary = `Task "${payload.title || payload.task_id || 'unknown'}" was claimed by ${payload.assignee || 'unknown'}.`;
+      details = { task_id: payload.task_id || null, title: payload.title || null, assignee: payload.assignee || null };
+      break;
+    case 'task.completed':
+      summary = `Task "${payload.title || payload.task_id || 'unknown'}" was completed.`;
+      details = { task_id: payload.task_id || null, title: payload.title || null, evidence_ref: cloneJsonValue(payload.evidence_ref || null) };
+      break;
+    case 'workflow.created':
+      summary = `Workflow "${payload.workflow_name || payload.workflow_id || 'unknown'}" was created.`;
+      details = { workflow_id: payload.workflow_id || null, workflow_name: payload.workflow_name || null, started_step_ids: Array.isArray(payload.started_step_ids) ? [...payload.started_step_ids] : [] };
+      break;
+    case 'workflow.step_started':
+      summary = `Workflow "${payload.workflow_name || payload.workflow_id || 'unknown'}" step ${payload.step_id || '?'} started.`;
+      details = { workflow_id: payload.workflow_id || null, workflow_name: payload.workflow_name || null, step_id: payload.step_id || null, assignee: payload.assignee || null };
+      break;
+    case 'workflow.step_completed':
+      summary = `Workflow "${payload.workflow_name || payload.workflow_id || 'unknown'}" step ${payload.step_id || '?'} completed.`;
+      details = { workflow_id: payload.workflow_id || null, workflow_name: payload.workflow_name || null, step_id: payload.step_id || null, evidence_ref: cloneJsonValue(payload.evidence_ref || null), next_step_ids: Array.isArray(payload.next_step_ids) ? [...payload.next_step_ids] : [] };
+      break;
+    case 'workflow.step_reassigned':
+      summary = `Workflow "${payload.workflow_name || payload.workflow_id || 'unknown'}" step ${payload.step_id || '?'} was reassigned to ${payload.new_assignee || 'unknown'}.`;
+      details = { workflow_id: payload.workflow_id || null, workflow_name: payload.workflow_name || null, step_id: payload.step_id || null, old_assignee: payload.old_assignee || null, new_assignee: payload.new_assignee || null };
+      break;
+    case 'workflow.completed':
+      summary = `Workflow "${payload.workflow_name || payload.workflow_id || 'unknown'}" completed.`;
+      details = { workflow_id: payload.workflow_id || null, workflow_name: payload.workflow_name || null, evidence_ref: cloneJsonValue(payload.evidence_ref || null) };
+      break;
+    case 'review.requested':
+      summary = `Review requested for "${payload.file || payload.review_id || 'unknown'}".`;
+      details = { review_id: payload.review_id || null, file: payload.file || null, requested_by: payload.requested_by || null, status: payload.status || null };
+      break;
+    case 'review.submitted':
+      summary = `Review ${payload.status || 'submitted'} for "${payload.file || payload.review_id || 'unknown'}".`;
+      details = { review_id: payload.review_id || null, file: payload.file || null, reviewer: payload.reviewer || null, status: payload.status || null };
+      break;
+    case 'dependency.declared':
+      summary = `Dependency declared for task ${payload.task_id || 'unknown'}.`;
+      details = { dependency_id: payload.dependency_id || null, task_id: payload.task_id || null, depends_on: payload.depends_on || null, resolved: !!payload.resolved };
+      break;
+    case 'dependency.resolved':
+      summary = `Dependency ${payload.dependency_id || 'unknown'} was resolved.`;
+      details = { dependency_id: payload.dependency_id || null, task_id: payload.task_id || null, depends_on: payload.depends_on || null, resolved_by_task_id: payload.resolved_by_task_id || null, reason: payload.reason || null };
+      break;
+    default:
+      details = cloneJsonValue(payload);
+      break;
+  }
+
+  return {
+    hook_id: hook.hook_id,
+    topic,
+    event_id: hook.event_id,
+    event_seq: hook.event_seq,
+    actor_agent: hook.actor_agent || null,
+    published_at: hook.published_at || hook.occurred_at || null,
+    summary,
+    details,
+  };
+}
+
+function readManagedTeamHookDigest(readBranchHooks, branchName, options = {}) {
+  if (typeof readBranchHooks !== 'function') return null;
+
+  const branch = normalizeBranchName(branchName);
+  const topics = Array.isArray(options.topics) && options.topics.length > 0
+    ? options.topics
+    : MANAGED_TEAM_HOOK_TOPICS;
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 5;
+  const hooks = readBranchHooks(branch, { topics, limit });
+  if (!Array.isArray(hooks) || hooks.length === 0) return null;
+
+  return {
+    source: 'derived_post_commit_hooks',
+    branch,
+    topics: [...new Set(hooks.map((hook) => hook.topic))],
+    recent: hooks.map(buildHookSummary),
+  };
+}
+
+module.exports = {
+  MANAGED_TEAM_HOOK_TOPICS,
+  buildManagedTeamContractContext,
+  readManagedTeamHookDigest,
+  resolveManagedTeamContractTarget,
+};