@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/src/core/information-gain.js

@@ -0,0 +1,138 @@
+export const GAIN_DIMENSIONS = Object.freeze([
+  "newObservation",
+  "newContributor",
+  "newHypothesis",
+  "hypothesisDispositionChanged",
+  "failureSignatureChanged",
+  "failureSurfaceChanged",
+  "interventionChanged",
+  "strategyChanged",
+  "newEvidence",
+  "hypothesisEliminated",
+]);
+
+function statementSet(values) {
+  return new Set((values ?? []).map((value) => `${value}`.trim().toLowerCase()).filter(Boolean));
+}
+
+export function normalizeDiagnosticSnapshot(input) {
+  // Idempotent: already-normalized snapshots pass through unchanged so
+  // repeated normalization never fabricates empty semantic sets.
+  if (input
+    && input.observationStatements instanceof Set
+    && input.contributorStatements instanceof Set
+    && input.hypothesisStatements instanceof Set
+    && input.evidenceRefs instanceof Set) {
+    return input;
+  }
+  if (!input) {
+    return {
+      observationStatements: new Set(),
+      contributorStatements: new Set(),
+      hypothesisStatements: new Set(),
+      evidenceRefs: new Set(),
+    };
+  }
+  const legacyHypothesis = input.legacy
+    ? [input.hypothesis ?? ""]
+    : (input.hypotheses ?? []).map((hypothesis) => hypothesis.statement ?? "");
+  const evidenceRefs = input.legacy
+    ? (input.evidenceRefs ?? [])
+    : [
+        ...(input.hypotheses ?? []).flatMap((hypothesis) => hypothesis.evidenceRefs ?? []),
+        ...(input.observations ?? []).map((observation) => observation.evidenceRef).filter(Boolean),
+      ];
+  return {
+    observationStatements: statementSet(input.legacy ? [] : (input.observations ?? []).map((observation) => observation.statement)),
+    contributorStatements: statementSet(input.legacy ? [] : (input.contributors ?? []).map((contributor) => contributor.statement)),
+    hypothesisStatements: statementSet(legacyHypothesis),
+    evidenceRefs: statementSet(evidenceRefs),
+    hypothesisIds: new Set(input.legacy ? [] : (input.hypotheses ?? []).map((hypothesis) => hypothesis.id)),
+  };
+}
+
+function hasNewValue(previousSet, currentSet) {
+  for (const value of currentSet) {
+    if (!previousSet.has(value)) return true;
+  }
+  return false;
+}
+
+export function compareDiagnosticCycles(previousInput, currentInput, context = {}) {
+  const previous = previousInput instanceof Set || Array.isArray(previousInput)
+    ? normalizeDiagnosticSnapshot(null)
+    : normalizeDiagnosticSnapshot(previousInput);
+  const current = normalizeDiagnosticSnapshot(currentInput);
+
+  const dimensions = {
+    newObservation: hasNewValue(previous.observationStatements, current.observationStatements),
+    newContributor: hasNewValue(previous.contributorStatements, current.contributorStatements),
+    newHypothesis: hasNewValue(previous.hypothesisStatements, current.hypothesisStatements),
+    hypothesisDispositionChanged: Boolean(context.hypothesisDispositionChanged),
+    failureSignatureChanged: Boolean(context.failureSignatureChanged),
+    failureSurfaceChanged: Boolean(context.failureSurfaceChanged),
+    interventionChanged: Boolean(context.interventionChanged),
+    strategyChanged: Boolean(context.strategyChanged),
+    newEvidence: hasNewValue(previous.evidenceRefs, current.evidenceRefs),
+    // Elimination is decided semantically by the cycle analysis projection:
+    // an id disappearing while its statement survives is ID-only churn, not gain.
+    hypothesisEliminated: Boolean(context.hypothesisEliminated),
+  };
+  return dimensions;
+}
+
+const CLASSIFICATION = Object.freeze({
+  FIRST_DIAGNOSIS: "FIRST_DIAGNOSIS",
+  NEW_HYPOTHESIS: "NEW_HYPOTHESIS",
+  NEW_EVIDENCE: "NEW_EVIDENCE",
+  NEW_HYPOTHESIS_AND_EVIDENCE: "NEW_HYPOTHESIS_AND_EVIDENCE",
+  NONE: "NONE",
+});
+
+export function classifyGain(dimensions, { first = false } = {}) {
+  if (first) return CLASSIFICATION.FIRST_DIAGNOSIS;
+  const hypothesis = dimensions.newHypothesis;
+  const evidence = dimensions.newEvidence;
+  if (hypothesis && evidence) return CLASSIFICATION.NEW_HYPOTHESIS_AND_EVIDENCE;
+  if (hypothesis) return CLASSIFICATION.NEW_HYPOTHESIS;
+  if (evidence) return CLASSIFICATION.NEW_EVIDENCE;
+  return CLASSIFICATION.NONE;
+}
+
+export function isEffectiveGain(dimensions, classification) {
+  if (classification !== CLASSIFICATION.NONE) return true;
+
+  // Every meaningful semantic dimension counts as effective gain.
+  // newHypothesis and newEvidence remain covered by the compatibility
+  // classification above; the remaining dimensions are checked explicitly.
+  return Boolean(
+    dimensions.newObservation
+    || dimensions.newContributor
+    || dimensions.hypothesisDispositionChanged
+    || dimensions.failureSignatureChanged
+    || dimensions.failureSurfaceChanged
+    || dimensions.interventionChanged
+    || dimensions.strategyChanged
+    || dimensions.hypothesisEliminated
+  );
+}
+
+export function computeInformationGain(entries) {
+  const results = [];
+  let previous = null;
+  let seenFirst = false;
+  for (const entry of entries) {
+    const dimensions = compareDiagnosticCycles(previous?.snapshot ?? null, entry.snapshot, entry.context ?? {});
+    const classification = classifyGain(dimensions, { first: !seenFirst });
+    seenFirst = true;
+    results.push({
+      verificationCycle: entry.verificationCycle,
+      sequence: entry.sequence ?? null,
+      effectiveGain: isEffectiveGain(dimensions, classification),
+      classification,
+      dimensions,
+    });
+    previous = entry;
+  }
+  return results;
+}

package/src/core/inspect.js

@@ -11,6 +11,100 @@ import { FORGELOOP_KIT_DIR } from "./target-layout.js";
 import { trustedAuthorityConfiguration } from "./trusted-authority.js";
 import { reconcileContinuity } from "./continuity-reconciliation.js";
 import { continuityFinding, continuityIsHealthy } from "./continuity-observability.js";
+import { findTaskById } from "./task-discovery.js";
+import { buildTaskTrace } from "./trace.js";
+import { evaluateProgress } from "./progress.js";
+import { readEvents } from "./events.js";
+
+function reasonCodesFor({ state, trace, progress }) {
+  const codes = [];
+  codes.push(trace.integrity.valid ? "LEDGER_VALID" : "LEDGER_INCONSISTENT");
+  if (state?.status === "VALID" || state?.status === "FRESH") codes.push("REPOSITORY_FRESH");
+  if (["STALE", "REVALIDATION_REQUIRED"].includes(state?.status)) codes.push("REPOSITORY_STALE");
+  if (trace.task.phase === "COMPLETE") codes.push("COMPLETION_VALID");
+  else codes.push("COMPLETION_INCOMPLETE");
+  if (progress.status === "ADVANCING") codes.push("DIAGNOSTIC_PROGRESS_ADVANCING");
+  if (progress.status === "STALLED") codes.push("DIAGNOSTIC_PROGRESS_STALLED");
+  return codes;
+}
+
+async function buildTaskInspection({ target, packageRoot, taskId, state, classifiedStatus = null }) {
+  const trace = await buildTaskTrace({ target, packageRoot, taskId });
+  const events = await readEvents(target, packageRoot, { taskId });
+  const progress = evaluateProgress({ state, events });
+  const failedRequirements = [...new Set(
+    trace.checks
+      .filter((check) => check.currentResult === "failed" || check.currentResult === "blocked")
+      .map((check) => check.requirement ?? check.id),
+  )].sort();
+
+  const issues = [];
+  if (!trace.snapshot.consistent) {
+    issues.push({ code: "E_TRACE_SNAPSHOT_INCONSISTENT", message: "Task artifacts changed while being read; rerun inspect for a consistent view." });
+  }
+  for (const error of trace.integrity.errors) {
+    issues.push({ code: error.code ?? "E_EVENT_INVALID", message: error.message });
+  }
+  if (failedRequirements.length > 0 && trace.diagnostics.cases.length === 0 && trace.diagnostics.legacyDiagnoses.length === 0) {
+    issues.push({ code: "E_DIAGNOSIS_REQUIRED", message: "Failed requirements have no recorded diagnosis." });
+  }
+
+  const explanation = {
+    result: failedRequirements.length > 0 ? "INCOMPLETE_VERIFICATION" : (trace.task.phase === "COMPLETE" ? "COMPLETE" : "INCOMPLETE"),
+    reasons: reasonCodesFor({ state: { status: classifiedStatus }, trace, progress }),
+  };
+
+  return {
+    task: taskId,
+    snapshot: {
+      consistent: trace.snapshot.consistent,
+      stateRevision: trace.snapshot.stateRevision,
+      ledgerTailSequence: trace.snapshot.ledgerTailSequence,
+    },
+    lifecycle: {
+      phase: trace.task.phase,
+      verificationCycle: trace.task.verificationCycle,
+      transitions: trace.transitions,
+    },
+    history: {
+      eventCount: trace.events.length,
+      quality: trace.historyQuality,
+    },
+    verification: {
+      checks: trace.checks.map((check) => ({
+        id: check.id,
+        requirement: check.requirement,
+        currentResult: check.currentResult,
+        attemptCount: check.attemptCount,
+        failedAttempts: check.failedAttempts,
+      })),
+      failedRequirements,
+    },
+    diagnostics: {
+      legacyDiagnosisCount: trace.diagnostics.legacyDiagnoses.length,
+      diagnosticCaseCount: trace.diagnostics.cases.length,
+      interventionCount: trace.diagnostics.interventions.length,
+      dispositionCount: trace.diagnostics.dispositions.length,
+      latestCase: trace.diagnostics.cases.at(-1) ?? null,
+    },
+    progress,
+    failureSurfaces: trace.failureSurfaces,
+    failureSignatures: trace.failureSignatures.map((entry) => ({
+      signature: entry.signature,
+      requirements: entry.requirements,
+      cycles: entry.cycles,
+    })),
+    integrity: {
+      valid: trace.integrity.valid,
+      errors: trace.integrity.errors,
+    },
+    audit: {},
+    completion: {},
+    issues,
+    explanation,
+    next: { command: `forgeloop next --task ${taskId} --json` },
+  };
+}
 
 function profileMetadata(bytes) {
   const text = bytes.toString("utf8");
@@ -39,7 +133,9 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
   const effectiveStateRel = stateFile ?? (taskId ? taskArtifactPath(taskId, "state") : WORK_STATE_PATH);
   const statePath = ensureWithin(target, effectiveStateRel);
   const statePresent = await fileExists(statePath);
-  const state = await readAndClassifyWorkState({ target, packageRoot, contractFile, taskId, stateFile: effectiveStateRel });
+  const classifiedState = await readAndClassifyWorkState({ target, packageRoot, contractFile, taskId, stateFile: effectiveStateRel });
+  const rawState = classifiedState?.state ?? null;
+  const taskInfo = taskId ? await findTaskById(target, taskId, packageRoot) : null;
   const continuity = await reconcileContinuity({ target, packageRoot, taskId });
   const schemaRoot = manifest?.layoutVersion >= 2
     ? ensureWithin(target, FORGELOOP_KIT_DIR)
@@ -78,12 +174,27 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
   const continuityIssue = continuityFinding(continuity);
   if (continuityIssue) findings.push(continuityIssue);
 
-  if (state.status === "INVALID") {
+  if (taskInfo?.ownershipValid === false) {
+    findings.push({
+      code: "task-claim-ownership-inconsistent",
+      severity: "error",
+      path: taskArtifactPath(taskId, "recovery"),
+      message: "Task claim ownership cannot be validated from recovery state and ledger history.",
+      remediation: `Run forgeloop validate-protocol --task ${taskId} --json and repair the reported protocol-owned artifact.`,
+      evidence: createEvidence({
+        kind: "BLOCKED",
+        source: taskArtifactPath(taskId, "events"),
+        result: "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT",
+      }),
+    });
+  }
+
+  if (classifiedState.status === "INVALID") {
     findings.push({
       code: "state-invalid",
       severity: "error",
-      path: WORK_STATE_PATH,
-      message: state.error ?? "Work state is invalid.",
+      path: effectiveStateRel,
+      message: classifiedState.error ?? "Work state is invalid.",
       remediation: "Repair or clear the checkpoint after reviewing the parse error.",
       evidence: createEvidence({ kind: "BLOCKED", source: WORK_STATE_PATH, result: "invalid" }),
     });
@@ -96,9 +207,12 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
   })];
   const evidence = [
     ...(doctor.evidence ?? []),
-    ...(state.evidence ?? []),
+    ...(classifiedState.evidence ?? []),
     ...protocolEvidence,
   ];
+  const taskInspection = taskId
+    ? await buildTaskInspection({ target, packageRoot, taskId, state: rawState, classifiedStatus: classifiedState.status })
+    : null;
   return {
     target: { path: target },
     authority: trustedAuthorityConfiguration({ target, authorityContext, runtimeContext }),
@@ -131,7 +245,16 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
       schemas: schemaHealth.schemas,
       evidence: protocolEvidence,
     },
-    state: { ...state, path: WORK_STATE_PATH, present: statePresent },
+    state: { ...classifiedState, path: effectiveStateRel, present: statePresent },
+    recovery: taskInfo?.recovery ?? null,
+    claims: taskInfo ? {
+      state: taskInfo.claimState,
+      historical: taskInfo.historicalWriteClaims,
+      effective: taskInfo.effectiveWriteClaims,
+      mutationAllowed: taskInfo.mutationAllowed,
+      ownershipValid: taskInfo.ownershipValid,
+      ownershipErrors: taskInfo.ownershipErrors ?? taskInfo.errors ?? [],
+    } : null,
     continuity,
     compatibility: {
       deprecated: true,
@@ -139,10 +262,12 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
     },
     findings,
     evidence,
+    ...(taskInspection ? { taskInspection } : {}),
     ok: doctor.ok
       && !manifestError
       && schemaHealth.status === "valid"
-      && !["INVALID", "REVALIDATION_REQUIRED"].includes(state.status)
+      && taskInfo?.ownershipValid !== false
+      && !["INVALID", "REVALIDATION_REQUIRED"].includes(classifiedState.status)
       && continuityIsHealthy(continuity),
   };
 }

package/src/core/integration-invocation-policy.js

@@ -0,0 +1,217 @@
+import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
+import { COMMAND_EXECUTORS } from "./command-executors.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { FORGELOOP_INTEGRATION_RUNTIME_VERSION } from "./command-runtime.js";
+
+/**
+ * Integration risk classes. They classify the *invocation*, not only the
+ * command name: input-dependent commands (doctor --fix, task-unlock --force,
+ * policy-discover --write, baseline mutations) are refined by the sparse
+ * override table below.
+ */
+export const INTEGRATION_RISK_CLASSES = Object.freeze({
+  READ_ONLY: "READ_ONLY",
+  LOOP_MUTATION: "LOOP_MUTATION",
+  CLAIM_REACQUISITION: "CLAIM_REACQUISITION",
+  EXTERNAL_EXECUTION: "EXTERNAL_EXECUTION",
+  AUTHORITY_MUTATION: "AUTHORITY_MUTATION",
+  EXTERNAL_STATE_ATTESTATION: "EXTERNAL_STATE_ATTESTATION",
+  MAINTENANCE: "MAINTENANCE",
+  CLAIM_RELEASE_RECOVERY: "CLAIM_RELEASE_RECOVERY",
+  LEGACY_MIGRATION: "LEGACY_MIGRATION",
+  FORCE_DESTRUCTIVE: "FORCE_DESTRUCTIVE",
+});
+
+const READ_ONLY_COMMANDS = Object.freeze(new Set([
+  "protocol-info", "status", "next", "continuity", "reconcile-continuity",
+  "task-list", "task-show", "task-lock-status", "progress", "audit", "report",
+  "inspect", "validate-state", "validate-protocol", "validate-receipt",
+  "policy-status", "policy-diff", "rule-verify", "policy",
+  "history", "trace", "reflect",
+]));
+
+const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
+  "route", "preflight", "advance", "task-create", "task-scope",
+  "record-continuity", "clear-continuity", "prepare-completion",
+  "record-check", "record-diagnosis", "record-decision-criterion",
+  "record-terminal-result", "complete",
+  "record-intervention", "record-hypothesis-disposition",
+]));
+
+const STATIC_RISK_CLASSES = Object.freeze({
+  ...Object.fromEntries([...READ_ONLY_COMMANDS].map((name) => [name, INTEGRATION_RISK_CLASSES.READ_ONLY])),
+  ...Object.fromEntries([...LOOP_MUTATION_COMMANDS].map((name) => [name, INTEGRATION_RISK_CLASSES.LOOP_MUTATION])),
+  "task-resume": INTEGRATION_RISK_CLASSES.CLAIM_REACQUISITION,
+  "run-check": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+  "run-action": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+  "reconcile-closure": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+  "action-propose": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+  "action-authorize": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+  "action-record": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+  "action-verify": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+  "action-reconcile": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+  "approval-request": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+  "approval-resolve": INTEGRATION_RISK_CLASSES.AUTHORITY_MUTATION,
+  eval: INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+  "action-show": INTEGRATION_RISK_CLASSES.READ_ONLY,
+  metrics: INTEGRATION_RISK_CLASSES.READ_ONLY,
+  init: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  update: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  activate: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "task-migrate": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "migrate-protocol": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "clear-state": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  doctor: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "policy-discover": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  baseline: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "task-unlock": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  // bundle writes a bundle artifact set under the task namespace; it is not
+  // read-only despite producing no protocol-state mutations.
+  bundle: INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "profile-interview": INTEGRATION_RISK_CLASSES.MAINTENANCE,
+  "task-recover": INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY,
+  "task-repair-legacy-recovery": INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+});
+
+// Sparse input-dependent refinements over the static table.
+function refineRiskClass(command, input) {
+  if (command === "task-unlock" && input?.force === true) {
+    return INTEGRATION_RISK_CLASSES.FORCE_DESTRUCTIVE;
+  }
+  // Settling external commit state is independently gated: recording an
+  // UNKNOWN observation stays LOOP_MUTATION, while COMMITTED / NOT_COMMITTED
+  // settlements attest external state and require their own capability.
+  if (
+    command === "action-reconcile"
+    && ["COMMITTED", "NOT_COMMITTED"].includes(input?.reconciliationOutcome)
+  ) {
+    return INTEGRATION_RISK_CLASSES.EXTERNAL_STATE_ATTESTATION;
+  }
+  // Fail closed: every canonical command must be explicitly classified.
+  return baseRiskClass(command);
+}
+
+export function baseRiskClass(command) {
+  const riskClass = STATIC_RISK_CLASSES[command];
+  if (!riskClass) {
+    throw new Error(`Command ${command} has no integration risk classification`);
+  }
+  return riskClass;
+}
+
+export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
+  const commands = Object.keys(CLI_COMMAND_DEFINITIONS).sort().map((name) => {
+    const def = CLI_COMMAND_DEFINITIONS[name];
+    return {
+      name,
+      category: def.category,
+      mutation: def.mutation,
+      baseRiskClass: baseRiskClass(name),
+      mayExecuteExternalProcess: def.mayExecuteExternalProcess === true,
+      description: def.description,
+    };
+  });
+  return {
+    packageVersion,
+    protocolVersion: PROTOCOL_VERSION,
+    integrationApiVersion: FORGELOOP_INTEGRATION_RUNTIME_VERSION,
+    executorParity: Object.keys(COMMAND_EXECUTORS).length === Object.keys(CLI_COMMAND_DEFINITIONS).length,
+    features: {
+      taskClaimRecovery: {
+        version: 1,
+        durableRecoveryState: true,
+        explicitResume: true,
+        validatedClaimProjection: true,
+      },
+      durableActions: {
+        version: 1,
+        readOnlyResources: true,
+        externalExecutionOverMcp: false,
+      },
+      trajectoryEvaluation: {
+        version: 1,
+        readOnlyMetrics: true,
+        projectLocalReference: true,
+      },
+    },
+    commands,
+    resources: [
+      { name: "protocol/info", scope: "PROJECT" },
+      { name: "project/tasks", scope: "PROJECT" },
+      { name: "task/status", scope: "TASK" },
+      { name: "task/ownership", scope: "TASK" },
+      { name: "task/contract", scope: "TASK" },
+      { name: "task/continuity", scope: "TASK" },
+      { name: "task/actions", scope: "TASK" },
+      { name: "task/action", scope: "TASK" },
+      { name: "task/approvals", scope: "TASK" },
+      { name: "task/metrics", scope: "TASK" },
+      { name: "task/evaluations", scope: "TASK" },
+      { name: "project/capability-policy", scope: "PROJECT" },
+    ],
+  };
+}
+
+/**
+ * Classify a concrete command invocation (command + structured input).
+ * Tool-provided input can never elevate a launch-level capability; this
+ * classifier only describes what the invocation would do.
+ */
+export function classifyForgeLoopInvocation(command, input = {}) {
+  const definition = CLI_COMMAND_DEFINITIONS[command];
+  if (!definition) {
+    throw new Error(`Unknown ForgeLoop command: ${command}`);
+  }
+  const riskClass = refineRiskClass(command, input);
+  const readOnly = riskClass === INTEGRATION_RISK_CLASSES.READ_ONLY;
+  const requiredCapability = (() => {
+    switch (riskClass) {
+      case INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION:
+        return "allowExternalExecution";
+      case INTEGRATION_RISK_CLASSES.AUTHORITY_MUTATION:
+        return "allowApprovalResolution";
+      case INTEGRATION_RISK_CLASSES.EXTERNAL_STATE_ATTESTATION:
+        return "allowActionReconciliationSettlement";
+      case INTEGRATION_RISK_CLASSES.MAINTENANCE:
+        return "allowMaintenance";
+      case INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY:
+        return "allowRecovery";
+      case INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION:
+        return "allowLegacyRepair";
+      case INTEGRATION_RISK_CLASSES.FORCE_DESTRUCTIVE:
+        return "allowForceRecovery";
+      default:
+        return null;
+    }
+  })();
+  return Object.freeze({
+    command,
+    riskClass,
+    readOnly,
+    mutatesProtocol: !readOnly && [
+      INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
+      INTEGRATION_RISK_CLASSES.CLAIM_REACQUISITION,
+      INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+      INTEGRATION_RISK_CLASSES.AUTHORITY_MUTATION,
+      INTEGRATION_RISK_CLASSES.EXTERNAL_STATE_ATTESTATION,
+      INTEGRATION_RISK_CLASSES.MAINTENANCE,
+      INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY,
+      INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+      INTEGRATION_RISK_CLASSES.FORCE_DESTRUCTIVE,
+    ].includes(riskClass),
+    removesArtifacts: definition.removes.length > 0,
+    executesExternalProcess: definition.mayExecuteExternalProcess === true,
+    affectsClaimAuthority: [
+      "task-resume", "task-recover", "task-repair-legacy-recovery",
+      "task-create", "task-scope", "complete",
+    ].includes(command),
+    destructive: [
+      INTEGRATION_RISK_CLASSES.AUTHORITY_MUTATION,
+      INTEGRATION_RISK_CLASSES.FORCE_DESTRUCTIVE,
+      INTEGRATION_RISK_CLASSES.CLAIM_RELEASE_RECOVERY,
+      INTEGRATION_RISK_CLASSES.LEGACY_MIGRATION,
+      INTEGRATION_RISK_CLASSES.MAINTENANCE,
+    ].includes(riskClass),
+    requiredCapability,
+  });
+}

package/src/core/integration-limits.js

@@ -0,0 +1,20 @@
+/**
+ * Bounded input limits for structured integrations. These bound the
+ * transport-facing surface; canonical ForgeLoop JSON safety limits remain
+ * authoritative for persisted artifacts. Values are conservative and
+ * intentionally small for an agent-facing API.
+ */
+export const INTEGRATION_LIMITS = Object.freeze({
+  /** Maximum length of any single string input (task IDs, names, text). */
+  maxStringLength: 4096,
+  /** Maximum number of entries in a repeatable string option. */
+  maxRepeatedValues: 32,
+  /** Maximum number of exact argv items passed to external execution. */
+  maxArgvItems: 64,
+  /** Maximum length of a single argv item. */
+  maxArgvItemLength: 2048,
+  /** Maximum serialized size of a JSON-object input field. */
+  maxStructuredInputBytes: 256 * 1024,
+  /** Maximum serialized size of any tool/resource response payload. */
+  maxOutputBytes: 4 * 1024 * 1024,
+});