@cassiomc1/forgeloop 1.5.0 → 1.6.0

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

@@ -14,6 +14,8 @@ export const INTEGRATION_RISK_CLASSES = Object.freeze({
   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",
@@ -25,6 +27,7 @@ const READ_ONLY_COMMANDS = Object.freeze(new Set([
   "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([
@@ -32,6 +35,7 @@ const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
   "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({
@@ -39,7 +43,18 @@ const STATIC_RISK_CLASSES = Object.freeze({
   ...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,
@@ -63,6 +78,15 @@ 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);
 }
@@ -99,6 +123,16 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
         explicitResume: true,
         validatedClaimProjection: true,
       },
+      durableActions: {
+        version: 1,
+        readOnlyResources: true,
+        externalExecutionOverMcp: false,
+      },
+      trajectoryEvaluation: {
+        version: 1,
+        readOnlyMetrics: true,
+        projectLocalReference: true,
+      },
     },
     commands,
     resources: [
@@ -108,6 +142,12 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
       { 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" },
     ],
   };
 }
@@ -128,6 +168,10 @@ export function classifyForgeLoopInvocation(command, input = {}) {
     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:
@@ -148,6 +192,8 @@ export function classifyForgeLoopInvocation(command, input = {}) {
       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,
@@ -160,6 +206,7 @@ export function classifyForgeLoopInvocation(command, input = {}) {
       "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,

package/src/core/integration-resources.js

@@ -1,9 +1,17 @@
+import path from "node:path";
 import { runProtocolInfo } from "../commands/protocol-info.js";
 import { readContract } from "./contract.js";
 import { discoverTasks } from "./task-discovery.js";
 import { resolveTaskClaimState } from "./task-claim-state.js";
 import { runStatus } from "../commands/status.js";
 import { runContinuity } from "../commands/continuity.js";
+import { listActions, readAction } from "./actions.js";
+import { listApprovals } from "./approvals.js";
+import { buildTrajectoryMetrics } from "./trajectory-metrics.js";
+import { loadCapabilityPolicy } from "./capability-policy.js";
+import { readdir } from "node:fs/promises";
+import { readJsonArtifact } from "./artifacts.js";
+import { taskDirectory } from "./task-paths.js";
 
 /**
  * Canonical integration resource allowlist.
@@ -43,6 +51,12 @@ export const INTEGRATION_RESOURCE_DEFINITIONS = Object.freeze({
     scope: "TASK",
     description: "Cross-harness continuity state for one task.",
   }),
+  "task/actions": Object.freeze({ scope: "TASK", description: "Canonical durable action summaries for one task." }),
+  "task/action": Object.freeze({ scope: "TASK", description: "One canonical durable action artifact." }),
+  "task/approvals": Object.freeze({ scope: "TASK", description: "Durable approval artifacts for one task." }),
+  "task/metrics": Object.freeze({ scope: "TASK", description: "Read-only trajectory metrics for one task." }),
+  "task/evaluations": Object.freeze({ scope: "TASK", description: "Persisted trajectory evaluations for one task." }),
+  "project/capability-policy": Object.freeze({ scope: "PROJECT", description: "Project capability policy, never host authority." }),
 });
 
 function ownershipProjection(projection) {
@@ -64,6 +78,7 @@ export async function readForgeLoopIntegrationResource(uri, {
   packageRoot = undefined,
   packageVersion = null,
   taskId = null,
+  actionId = null,
 } = {}) {
   const resource = INTEGRATION_RESOURCE_DEFINITIONS[uri];
   if (!resource) {
@@ -102,12 +117,48 @@ export async function readForgeLoopIntegrationResource(uri, {
       }
       break;
     }
+    case "task/actions":
+    case "task/action":
+    case "task/approvals":
+    case "task/metrics":
+    case "task/evaluations": {
+      if (typeof taskId !== "string" || !taskId) {
+        const error = new Error(`Resource ${uri} requires a taskId`); error.code = "E_TASK_REQUIRED"; throw error;
+      }
+      break;
+    }
   }
 
   if (uri === "task/ownership") {
     const projection = await resolveTaskClaimState(projectPath, { taskId, packageRoot });
     return { uri, taskId, data: ownershipProjection(projection) };
   }
+  if (uri === "task/actions") {
+    const actions = await listActions(projectPath, { packageRoot, taskId });
+    return { uri, taskId, data: { actions } };
+  }
+  if (uri === "task/action") {
+    if (!actionId) { const error = new Error("Resource task/action requires actionId"); error.code = "E_ACTION_INVALID"; throw error; }
+    return { uri, taskId, data: await readAction(projectPath, { packageRoot, taskId, actionId }) };
+  }
+  if (uri === "task/approvals") {
+    return { uri, taskId, data: { approvals: await listApprovals(projectPath, { packageRoot, taskId }) } };
+  }
+  if (uri === "task/metrics") {
+    return { uri, taskId, data: await buildTrajectoryMetrics({ target: projectPath, packageRoot, taskId }) };
+  }
+  if (uri === "task/evaluations") {
+    const dir = path.join(projectPath, taskDirectory(taskId), "evaluations");
+    let names = []; try { names = await readdir(dir); } catch { /* absent is an empty projection */ }
+    const evaluations = [];
+    for (const name of names.filter((entry) => /^eval-[A-Za-z0-9_-]+\.json$/.test(entry)).sort()) {
+      evaluations.push((await readJsonArtifact(projectPath, `${taskDirectory(taskId)}/evaluations/${name}`, "trajectory-evaluation", packageRoot)).value);
+    }
+    return { uri, taskId, data: { evaluations } };
+  }
+  if (uri === "project/capability-policy") {
+    return { uri, data: await loadCapabilityPolicy(projectPath, packageRoot) };
+  }
   if (uri === "task/status") {
     const result = await runStatus({ target: projectPath, packageRoot, taskId });
     return { uri, taskId, data: result };

package/src/core/next-action-model.js

@@ -16,6 +16,9 @@ export const NEXT_ACTIONS = Object.freeze({
   RECORD_DIAGNOSIS: "RECORD_DIAGNOSIS",
   CORRECT: "CORRECT",
   CHANGE_STRATEGY: "CHANGE_STRATEGY",
+  REQUIRE_NEW_DIAGNOSTIC_INFORMATION: "REQUIRE_NEW_DIAGNOSTIC_INFORMATION",
+  INTRODUCE_NEW_OBSERVATION: "INTRODUCE_NEW_OBSERVATION",
+  RECORD_INTERVENTION: "RECORD_INTERVENTION",
   ENTER_REVIEWING: "ENTER_REVIEWING",
   RECORD_TERMINAL_RESULT: "RECORD_TERMINAL_RESULT",
   PREPARE_COMPLETION: "PREPARE_COMPLETION",
@@ -32,13 +35,18 @@ export const NEXT_ACTIONS = Object.freeze({
   RESTORE_BASELINE: "RESTORE_BASELINE",
   CONTINUE_WITH_EXISTING_BASELINE: "CONTINUE_WITH_EXISTING_BASELINE",
   RECONCILE_CLOSURE: "RECONCILE_CLOSURE",
+  RECONCILE_ACTION: "RECONCILE_ACTION",
+  AUTHORIZE_ACTION: "AUTHORIZE_ACTION",
+  REQUEST_ACTION_APPROVAL: "REQUEST_ACTION_APPROVAL",
+  RESOLVE_ACTION_APPROVAL: "RESOLVE_ACTION_APPROVAL",
+  VERIFY_EXTERNAL_ACTION: "VERIFY_EXTERNAL_ACTION",
   RECOVER_TASK: "RECOVER_TASK",
   RESUME_RECOVERED_TASK: "RESUME_RECOVERED_TASK",
   RESOLVE_RECOVERY_INCONSISTENCY: "RESOLVE_RECOVERY_INCONSISTENCY",
   NONE: "NONE",
 });
 
-function directCommandSpec(commandId, taskId, requiredInputs = []) {
+export function directCommandSpec(commandId, taskId, requiredInputs = []) {
   return {
     commandId,
     executable: "forgeloop",
@@ -104,6 +112,12 @@ export function result({
   requiredArtifacts = [],
   missingArtifacts = [],
   progress = undefined,
+  diagnosticGuidance = undefined,
+  authorityRequired = undefined,
+  hostActionRequired = undefined,
+  approvalRequired = undefined,
+  capabilityDecision = undefined,
+  reconciliationAuthorityRequired = undefined,
 }) {
   const normalizedReasons = reasons
     .map((reason) => {
@@ -136,6 +150,14 @@ export function result({
     requiredArtifacts: uniqueSorted(requiredArtifacts),
     missingArtifacts: uniqueSorted(missingArtifacts),
     ...(progress ? { progress: structuredClone(progress) } : {}),
+    ...(diagnosticGuidance ? { diagnosticGuidance: structuredClone(diagnosticGuidance) } : {}),
+    ...(authorityRequired ? { authorityRequired: structuredClone(authorityRequired) } : {}),
+    ...(hostActionRequired ? { hostActionRequired: structuredClone(hostActionRequired) } : {}),
+    ...(approvalRequired ? { approvalRequired: structuredClone(approvalRequired) } : {}),
+    ...(capabilityDecision ? { capabilityDecision: structuredClone(capabilityDecision) } : {}),
+    ...(reconciliationAuthorityRequired
+      ? { reconciliationAuthorityRequired: structuredClone(reconciliationAuthorityRequired) }
+      : {}),
   };
 }
 
@@ -186,6 +208,18 @@ export function recordDiagnosisCommandSpec() {
   };
 }
 
+export function recordInterventionCommandSpec(taskId = null) {
+  return {
+    commandId: "record-intervention",
+    executable: "forgeloop",
+    subcommand: "record-intervention",
+    argv: ["record-intervention", ...(taskId ? [`--task=${taskId}`] : [])],
+    requiredInputs: [
+      { name: "file", option: "--file=<intervention-json-path>" },
+    ],
+  };
+}
+
 export function recordTerminalResultCommandSpec(requirement) {
   const reqId = requirement.id ?? requirement;
   const type = requirement.type ?? "PUBLICATION";