@cassiomc1/forgeloop 1.9.0 → 1.10.1

package/src/core/protocol-info.js

@@ -160,11 +160,27 @@ export function protocolInfo({ packageVersion = null } = {}) {
         rebinding: "EXPLICIT_ONLY",
       },
       canonicalHandoffs: {
-        version: 1,
+        version: 2,
         supported: true,
         immutable: true,
-        actorControlledIntent: true,
         lifecycleAuthority: false,
+        evidenceAuthority: false,
+        exactlyOnceAcceptance: true,
+        acceptanceLedgerBacked: true,
+        acceptanceCommand: "handoff-accept",
+        acceptanceStatuses: ["OPEN", "ACCEPTED", "UNBOUND", "INCONSISTENT"],
+      },
+      advisoryContextProviders: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        integrationApiOnly: true,
+        lazy: true,
+        optIn: true,
+        persistedByForgeLoop: false,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        executable: false,
       },
       responsibilityConstraints: {
         version: 1,

package/src/core/runtime-context.js

@@ -4,6 +4,8 @@ import {
   normalizeVerificationExecutionPolicy,
 } from "./verification-execution.js";
 import { STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN } from "./structural-quality/constants.js";
+import { E_ADVISORY_CONTEXT_PROVIDER_INVALID } from "./error-codes.js";
+import { assertAdvisoryContextProviderIdentity } from "./advisory-context/provider.js";
 
 export const AUTHORITY_TRUST_MODES = Object.freeze(["NONE", "HOST_ATTESTED"]);
 
@@ -132,5 +134,34 @@ export function createForgeLoopContext(options = {}) {
     }
     context.structuralQualityProviders = Object.freeze(providers);
   }
+  if (options?.advisoryContextProviders !== undefined) {
+    const configured = options.advisoryContextProviders instanceof Map
+      ? Object.fromEntries(options.advisoryContextProviders.entries())
+      : options.advisoryContextProviders;
+    if (!configured || typeof configured !== "object" || Array.isArray(configured)) {
+      const error = new Error("advisoryContextProviders must be an object or Map");
+      error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+      throw error;
+    }
+    const providers = {};
+    for (const [id, provider] of Object.entries(configured)) {
+      if (!/^[a-z0-9][a-z0-9_-]*$/.test(id)) {
+        const error = new Error(`Invalid advisory-context provider ID: ${id}`);
+        error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+        throw error;
+      }
+      if (typeof provider !== "function"
+        && (!provider || typeof provider !== "object" || Array.isArray(provider))) {
+        const error = new Error(`Advisory-context provider ${id} must be an object or factory`);
+        error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+        throw error;
+      }
+      if (typeof provider !== "function") {
+        assertAdvisoryContextProviderIdentity(provider, id);
+      }
+      providers[id] = provider;
+    }
+    context.advisoryContextProviders = Object.freeze(providers);
+  }
   return Object.freeze(context);
 }

package/src/core/task-recovery.js

@@ -5,7 +5,7 @@ import {
   E_TASK_RECOVERY_AUTHORITY_INVALID,
 } from "./error-codes.js";
 import { taskArtifactPath } from "./task-paths.js";
-import { getActiveTaskTransaction } from "./transaction.js";
+import { getTaskTransaction } from "./transaction.js";
 import { classifyRecoveryHistory } from "./recovery-history.js";
 
 export const TASK_RECOVERY_SCHEMA_VERSION = 1;
@@ -86,7 +86,7 @@ export function writeTaskRecovery(target, recovery, packageRoot) {
 }
 
 export async function clearTaskRecovery(target, { taskId } = {}) {
-  const transaction = getActiveTaskTransaction();
+  const transaction = (await getTaskTransaction(target));
   if (!transaction) {
     throw new Error("clearTaskRecovery requires an active task transaction");
   }

package/src/core/transaction-maintenance.js

@@ -0,0 +1,70 @@
+import { lstat, readdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { assertSafePath, ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
+import { withTaskLock } from "./task-lock.js";
+
+const ROOT = ".forgeloop/.txn";
+const TERMINAL = new Set(["COMMITTED", "ROLLED_BACK", "ABORTED"]);
+const DAY_MS = 86_400_000;
+
+async function payloadBytes(directory) {
+  let bytes = 0;
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const child = path.join(directory, entry.name);
+    const metadata = await lstat(child);
+    if (metadata.isSymbolicLink()) throw new Error("Transaction payload contains a symlink");
+    if (metadata.isDirectory()) bytes += await payloadBytes(child);
+    else if (metadata.isFile()) bytes += metadata.size;
+    else throw new Error("Transaction payload contains a special file");
+  }
+  return bytes;
+}
+
+/** Compact terminal payloads only; preserve manifests and all event ledgers. */
+export async function compactTransactions({ target, retainDays = 7, apply = false, now = Date.now() } = {}) {
+  if (!Number.isFinite(retainDays) || retainDays < 1) throw new Error("retainDays must be at least one day");
+  await assertSafePath(target, ROOT);
+  const root = ensureWithin(target, ROOT);
+  const report = { apply, scanned: 0, eligible: 0, bytes: 0, compacted: 0, skipped: [] };
+  if (!await fileExists(root)) return report;
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    report.scanned += 1;
+    const relative = `${ROOT}/${entry.name}`;
+    const manifestPath = `${relative}/manifest.json`;
+    try {
+      await assertSafePath(target, manifestPath);
+      const original = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
+      const lockTaskId = original.lockTaskId ?? original.taskId;
+      if (typeof lockTaskId !== "string" || !lockTaskId) throw new Error("Missing lock identity");
+      await withTaskLock(target, lockTaskId, "compact-transactions", async () => {
+        const manifest = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
+        if ((manifest.lockTaskId ?? manifest.taskId) !== lockTaskId || manifest.transactionId !== entry.name) throw new Error("Changed transaction identity");
+        const timestamp = Date.parse(manifest.committedAt ?? manifest.recoveredAt ?? manifest.failedAt ?? manifest.startedAt);
+        if (!TERMINAL.has(manifest.status) || !Number.isFinite(timestamp) || now - timestamp < retainDays * DAY_MS) return;
+        const payloads = [];
+        let bytes = 0;
+        for (const name of ["stage", "backup"]) {
+          const payload = `${relative}/${name}`;
+          await assertSafePath(target, payload);
+          const fullPath = ensureWithin(target, payload);
+          if (await fileExists(fullPath)) {
+            bytes += await payloadBytes(fullPath);
+            payloads.push(fullPath);
+          }
+        }
+        if (!payloads.length) return;
+        report.eligible += 1;
+        report.bytes += bytes;
+        if (!apply) return;
+        for (const payload of payloads) await rm(payload, { recursive: true, force: true, maxRetries: 3 });
+        manifest.compactedAt = new Date(now).toISOString();
+        await writeFileAtomic(ensureWithin(target, manifestPath), `${JSON.stringify(manifest, null, 2)}\n`);
+        report.compacted += 1;
+      });
+    } catch (error) {
+      report.skipped.push({ transactionId: entry.name, reason: error.message });
+    }
+  }
+  return report;
+}

package/src/core/transaction.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { mkdir, open, readdir, readFile, rename, stat, truncate, unlink } from "node:fs/promises";
+import { mkdir, open, readdir, readFile, realpath, rename, stat, truncate, unlink } from "node:fs/promises";
 import { setTimeout as delay } from "node:timers/promises";
 import path from "node:path";
 
@@ -16,6 +16,18 @@ export function getActiveTaskTransaction() {
   return transactionContext.getStore() ?? null;
 }
 
+export async function getTaskTransaction(target) {
+  const transaction = getActiveTaskTransaction();
+  if (transaction && transaction.target !== await realpath(target)) {
+    const error = new Error("Cannot reuse a task transaction for a different project");
+    error.code = "E_TASK_CONTEXT_MISMATCH";
+    throw error;
+  }
+  return transaction;
+}
+
+const TERMINAL_STATUSES = new Set(["COMMITTED", "ROLLED_BACK", "ABORTED"]);
+
 function transactionPath(transactionId) {
   return `${TRANSACTION_ROOT}/${transactionId}`;
 }
@@ -33,7 +45,7 @@ export async function findIncompleteTransactions(target) {
     if (!entry.isDirectory()) continue;
     try {
       const manifest = JSON.parse(await readFile(path.join(root, entry.name, "manifest.json"), "utf8"));
-      if (manifest.status !== "COMMITTED") found.push(manifest);
+      if (!TERMINAL_STATUSES.has(manifest.status)) found.push(manifest);
     } catch {
       found.push({ transactionId: entry.name, status: "ABANDONED", malformed: true });
     }
@@ -50,6 +62,7 @@ async function rollbackPublishedWrites(target, root, manifest) {
   for (const entry of writes) {
     if (!entry || typeof entry !== "object") continue;
     const relativePath = writePath(entry);
+    await assertSafePath(target, relativePath);
     if (entry.kind === "APPEND") {
       if (!entry.appendStarted) continue;
       const destination = ensureWithin(target, relativePath);
@@ -82,11 +95,15 @@ export async function recoverIncompleteTransactions(target) {
     try {
       const manifest = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
       if (manifest.status !== "COMMITTING") continue;
-      await rollbackPublishedWrites(target, root, manifest);
-      manifest.status = "ROLLED_BACK";
-      manifest.recoveredAt = new Date().toISOString();
-      await writeManifest(target, manifestPath, manifest);
-      recovered.push({ transactionId: manifest.transactionId, status: manifest.status });
+      await withTaskLock(target, manifest.lockTaskId ?? manifest.taskId ?? "transaction-recovery", "recover-transaction", async () => {
+        const current = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
+        if (current.status !== "COMMITTING") return;
+        await rollbackPublishedWrites(target, root, current);
+        current.status = "ROLLED_BACK";
+        current.recoveredAt = new Date().toISOString();
+        await writeManifest(target, manifestPath, current);
+        recovered.push({ transactionId: current.transactionId, status: current.status });
+      });
     } catch (error) {
       recovered.push({ transactionId: entry.name, status: "RECOVERY_FAILED", error: error.message });
     }
@@ -103,7 +120,8 @@ export async function withTaskTransaction({
   recordCommitEvent = false,
 } = {}, callback) {
   if (!target || !taskId) throw new Error("target and taskId are required for a task transaction");
-  const activeTransaction = getActiveTaskTransaction();
+  target = await realpath(target);
+  const activeTransaction = await getTaskTransaction(target);
   if (activeTransaction) {
     if (activeTransaction.taskId !== taskId) {
       throw new Error(`cannot nest task transaction for ${taskId} inside ${activeTransaction.taskId}`);
@@ -118,9 +136,10 @@ export async function withTaskTransaction({
     const manifestPath = `${root}/manifest.json`;
     await assertSafePath(target, manifestPath);
     await mkdir(ensureWithin(target, stageRoot), { recursive: true });
-    const manifest = { schemaVersion: 1, transactionId, taskId, operation, lockId: lock.lockId, startedAt: new Date().toISOString(), status: "STAGING", writes: [] };
+    const manifest = { schemaVersion: 1, transactionId, taskId, lockTaskId, operation, lockId: lock.lockId, startedAt: new Date().toISOString(), status: "STAGING", writes: [] };
     await writeManifest(target, manifestPath, manifest);
     const tx = {
+      target,
       transactionId,
       taskId,
       lock,
@@ -274,7 +293,9 @@ export async function withTaskTransaction({
           manifest.rollbackError = { message: rollbackError.message };
         }
       } else {
-        manifest.status = "ABANDONED";
+        // Staging has not published any writes; retain the diagnostic record
+        // without requiring recovery of a project that was never modified.
+        manifest.status = "ABORTED";
       }
       manifest.failedAt = new Date().toISOString();
       manifest.error = { message: error.message };

package/src/core/work-state.js

@@ -19,7 +19,7 @@ import { assertJsonBytes } from "./json-safety.js";
 import { assertCoverageList } from "./coverage.js";
 import { canonicalFingerprint } from "./artifacts.js";
 import { taskArtifactPath } from "./task-paths.js";
-import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 export const WORK_STATE_PATH = ".forgeloop/work-state.json";
 
@@ -245,7 +245,7 @@ export async function readWorkState(target, options = {}) {
   const statePath = ensureWithin(target, relPath);
   let state;
   try {
-    const transaction = getActiveTaskTransaction();
+    const transaction = (await getTaskTransaction(target));
     const staged = transaction ? await transaction.readText(relPath) : null;
     if (staged === null) {
       if (!(await fileExists(statePath))) return null;
@@ -290,7 +290,7 @@ export async function writeWorkState(target, state, options = {}) {
   await validateStoredState(state, packageRoot);
   await assertSafePath(target, relPath);
   const serialized = `${JSON.stringify(state, null, 2)}\n`;
-  const transaction = getActiveTaskTransaction();
+  const transaction = (await getTaskTransaction(target));
   if (!dryRun && transaction) {
     await transaction.stageText(relPath, serialized);
   } else {
@@ -306,7 +306,7 @@ export async function mutateWorkState(target, { expectedRevision, packageRoot =
     error.code = "E_STATE_REVISION_CONFLICT";
     throw error;
   }
-  if (!getActiveTaskTransaction()) {
+  if (!(await getTaskTransaction(target))) {
     return withTaskTransaction({
       target,
       taskId: taskId ?? "legacy-work-state",
@@ -331,7 +331,7 @@ export async function mutateWorkState(target, { expectedRevision, packageRoot =
 }
 
 export async function initializeWorkState(target, state, { packageRoot = getPackageRoot(), taskId, statePath } = {}) {
-  if (getActiveTaskTransaction()) {
+  if ((await getTaskTransaction(target))) {
     const current = await readWorkState(target, { packageRoot, taskId, statePath });
     if (current) return current;
     await writeWorkState(target, state, { packageRoot, taskId, statePath });

package/src/integration.d.ts

@@ -61,6 +61,65 @@ export interface ForgeLoopContext {
   verificationExecutionPolicy?: { requiredIsolation: string };
   usageProvider?: ForgeLoopUsageProvider;
   structuralQualityProviders?: Readonly<Record<string, ForgeLoopStructuralQualityProvider | ForgeLoopStructuralQualityProviderFactory>>;
+  advisoryContextProviders?: Readonly<Record<string, ForgeLoopAdvisoryContextProvider | ForgeLoopAdvisoryContextProviderFactory>>;
+}
+
+export interface ForgeLoopAdvisoryContextItem {
+  title?: string;
+  summary: string;
+  sourceRef?: string;
+  observedAt?: string;
+  confidence?: number;
+  itemFingerprint?: string;
+}
+
+export interface ForgeLoopAdvisoryContextRecallInput {
+  projectPath: string;
+  taskId: string;
+  query: string;
+  limit?: number;
+  maxItemChars?: number;
+  maxTotalChars?: number;
+  timeoutMs?: number;
+}
+
+export interface ForgeLoopAdvisoryContextRecallOutput {
+  items: Array<{
+    title?: string;
+    summary: string;
+    sourceRef?: string;
+    observedAt?: string;
+    confidence?: number;
+  }>;
+}
+
+export interface ForgeLoopAdvisoryRecallOptions {
+  limit: number;
+  maxItemChars: number;
+  maxTotalChars: number;
+  timeoutMs: number;
+}
+
+export interface ForgeLoopAdvisoryContextProvider {
+  id: string;
+  version?: string;
+  recall(input: ForgeLoopAdvisoryContextRecallInput): Promise<ForgeLoopAdvisoryContextRecallOutput> | ForgeLoopAdvisoryContextRecallOutput;
+}
+
+export type ForgeLoopAdvisoryContextProviderFactory = () => ForgeLoopAdvisoryContextProvider | Promise<ForgeLoopAdvisoryContextProvider>;
+
+export interface ForgeLoopNormalizedAdvisoryContextResult {
+  provider: {
+    id: string;
+    version?: string;
+  };
+  taskId: string | null;
+  authority: "ADVISORY";
+  evidenceAuthority: "NONE";
+  actionability: "NON_EXECUTABLE";
+  trustRole: "NON_EVIDENCE_ADVISORY_CONTEXT";
+  persisted: false;
+  items: readonly ForgeLoopAdvisoryContextItem[];
 }
 
 export interface ForgeLoopStructuralQualityProviderInput {
@@ -70,11 +129,12 @@ export interface ForgeLoopStructuralQualityProviderInput {
   maxOutputBytes: number;
 }
 
-export interface ForgeLoopStructuralQualityProvider {
-  id: string;
+export type ForgeLoopStructuralQualityProvider = { id: string } & ({
+  observe(input: ForgeLoopStructuralQualityProviderInput): Promise<Record<string, unknown>> | Record<string, unknown>;
+} | {
   detect(input: ForgeLoopStructuralQualityProviderInput): Promise<Record<string, unknown>> | Record<string, unknown>;
   scan(input: ForgeLoopStructuralQualityProviderInput): Promise<Record<string, unknown>> | Record<string, unknown>;
-}
+});
 
 export type ForgeLoopStructuralQualityProviderFactory = (input: ForgeLoopStructuralQualityProviderInput) => ForgeLoopStructuralQualityProvider | Promise<ForgeLoopStructuralQualityProvider>;
 
@@ -198,3 +258,75 @@ export declare function classifyForgeLoopInvocation(command: string, input?: For
 export declare function readForgeLoopIntegrationResource(uri: string, input?: Record<string, unknown>): Promise<Record<string, unknown>>;
 export declare function resolveForgeLoopProjectRoot(projectPath?: string, input?: { cwd?: string }): Promise<string>;
 export declare function createForgeLoopContext(input?: Record<string, unknown>): ForgeLoopContext;
+export declare function recallAdvisoryContext(input: {
+  target: string;
+  taskId: string;
+  providerName: string;
+  query: string;
+  limit?: number;
+  maxItemChars?: number;
+  maxTotalChars?: number;
+  timeoutMs?: number;
+  runtimeContext?: ForgeLoopContext | Record<string, unknown>;
+}): Promise<ForgeLoopNormalizedAdvisoryContextResult>;
+export declare const ADVISORY_CONTEXT_LIMITS: Readonly<Record<string, number>>;
+export declare const ADVISORY_CONTEXT_TRUST: Readonly<Record<string, unknown>>;
+export declare function normalizeAdvisoryRecallOptions(input?: Partial<ForgeLoopAdvisoryRecallOptions>): ForgeLoopAdvisoryRecallOptions;
+export declare function assertAdvisoryContextProvider(provider: unknown): ForgeLoopAdvisoryContextProvider;
+export declare function assertAdvisoryContextProviderIdentity(provider: unknown, expectedId: string): ForgeLoopAdvisoryContextProvider;
+export declare function createAdvisoryContextProviderRegistry(options?: { providers?: Record<string, unknown> }): {
+  get(id: string): unknown;
+  has(id: string): boolean;
+  list(): string[];
+};
+export declare function resolveAdvisoryContextProvider(options: {
+  providers?: Record<string, unknown> | Map<string, unknown> | { get(id: string): unknown; has(id: string): boolean };
+  providerName: string;
+}): Promise<ForgeLoopAdvisoryContextProvider | null>;
+export declare function normalizeAdvisoryContextResult(raw: unknown, options?: Record<string, unknown>): ForgeLoopNormalizedAdvisoryContextResult;
+export declare function normalizePortableText(value: unknown, options?: { label?: string; maxLength?: number; optional?: boolean }): string | null;
+export declare function assertPortableContextSafe<T = unknown>(value: T, options?: { label?: string }): T;
+export declare class PortableContextError extends Error {
+  code: string;
+}
+export declare function acceptCanonicalHandoff(target: string, options: {
+  taskId: string;
+  handoffId: string;
+  consumerId: string;
+  harness?: string | null;
+  packageRoot?: string;
+}): Promise<{
+  accepted: boolean;
+  idempotent: boolean;
+  handoffId: string;
+  consumerId: string;
+  harness: string | null;
+  acceptedAt: string;
+}>;
+export declare function resolveHandoffAcceptance(input: {
+  events?: readonly unknown[];
+  handoff: unknown;
+  ledgerValid?: boolean;
+  ledgerErrors?: readonly ({ code?: string } | string)[];
+}): {
+  status: "OPEN" | "ACCEPTED" | "INCONSISTENT" | "UNBOUND";
+  consumerId?: string;
+  harness?: string;
+  acceptedAt?: string;
+  reasonCodes?: readonly string[];
+};
+
+export declare const E_VERIFICATION_EXECUTION_INVALID: "E_VERIFICATION_EXECUTION_INVALID";
+export declare const E_VERIFICATION_ISOLATION_UNAVAILABLE: "E_VERIFICATION_ISOLATION_UNAVAILABLE";
+export declare function createStructuralQualityProviderRegistry(options?: {
+  providers?: Readonly<Record<string, ForgeLoopStructuralQualityProvider | ForgeLoopStructuralQualityProviderFactory>>;
+  builtIns?: Readonly<Record<string, ForgeLoopStructuralQualityProvider | ForgeLoopStructuralQualityProviderFactory>>;
+}): { resolve(name: string, input: ForgeLoopStructuralQualityProviderInput): Promise<ForgeLoopStructuralQualityProvider> };
+export declare function resolveStructuralQualityProvider(options: {
+  providerName?: string;
+  target: string;
+  taskId: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  runtimeContext?: ForgeLoopContext;
+}): Promise<ForgeLoopStructuralQualityProvider>;

package/src/integration.js

@@ -31,6 +31,7 @@ export function getForgeLoopPackageVersion() {
 }
 
 export {
+  FORGELOOP_INTEGRATION_RUNTIME_VERSION,
   executeForgeLoopCommand,
   validateForgeLoopCommandInput,
   defaultCommandInputValues,
@@ -79,5 +80,27 @@ export {
   VERIFICATION_EXECUTION_POLICY_MODES,
   VERIFICATION_ISOLATION_MODES,
 } from "./core/verification-execution.js";
+export { recallAdvisoryContext } from "./core/advisory-context/service.js";
+export {
+  ADVISORY_CONTEXT_LIMITS,
+  ADVISORY_CONTEXT_TRUST,
+  normalizeAdvisoryRecallOptions,
+} from "./core/advisory-context/constants.js";
+export {
+  assertAdvisoryContextProvider,
+  assertAdvisoryContextProviderIdentity,
+  createAdvisoryContextProviderRegistry,
+  normalizeAdvisoryContextResult,
+  resolveAdvisoryContextProvider,
+} from "./core/advisory-context/provider.js";
+export {
+  normalizePortableText,
+  assertPortableContextSafe,
+  PortableContextError,
+} from "./core/portable-context.js";
+export {
+  acceptCanonicalHandoff,
+  resolveHandoffAcceptance,
+} from "./core/handoff-acceptance.js";
 
 export const FORGELOOP_INTEGRATION_API_VERSION = FORGELOOP_INTEGRATION_RUNTIME_VERSION;

package/src/core/cli-metadata.js

@@ -1,23 +0,0 @@
-import { CLI_COMMAND_DEFINITIONS } from "./cli-command-definitions.js";
-
-/**
- * Canonical metadata for all 43 ForgeLoop CLI commands derived directly
- * from CLI_COMMAND_DEFINITIONS to guarantee zero divergence.
- */
-export const CLI_COMMAND_METADATA = Object.freeze(
-  Object.fromEntries(
-    Object.entries(CLI_COMMAND_DEFINITIONS).map(([name, def]) => [
-      name,
-      Object.freeze({
-        name: def.name,
-        category: def.category,
-        mutation: def.mutation,
-        options: Object.keys(def.options),
-        writes: def.writes,
-        removes: def.removes,
-        mayExecuteExternalProcess: def.mayExecuteExternalProcess,
-        description: def.description,
-      }),
-    ]),
-  ),
-);

package/src/core/decision-classification.js

@@ -1,55 +0,0 @@
-export const BLOCKING_REASON_CODES = Object.freeze([
-  "REAL_BUSINESS_FACT_REQUIRED",
-  "SENSITIVE_VALUE_REQUIRED",
-  "EXTERNAL_AUTHORITY_REQUIRED",
-  "IRREVERSIBLE_DECISION_REQUIRED",
-  "REGULATED_CLAIM_REQUIRED",
-  "DESTRUCTIVE_ACTION_REQUIRED",
-]);
-
-const BLOCKING_RULES = Object.freeze([
-  ["realBusinessFact", "REAL_BUSINESS_FACT_REQUIRED"],
-  ["sensitive", "SENSITIVE_VALUE_REQUIRED"],
-  ["authoritative", "EXTERNAL_AUTHORITY_REQUIRED"],
-  ["external", "EXTERNAL_AUTHORITY_REQUIRED"],
-  ["irreversible", "IRREVERSIBLE_DECISION_REQUIRED"],
-  ["regulatedClaim", "REGULATED_CLAIM_REQUIRED"],
-  ["destructive", "DESTRUCTIVE_ACTION_REQUIRED"],
-]);
-
-function blockingDecision(reasonCode) {
-  return {
-    classification: "BLOCKING",
-    reasonCode,
-    blockingReason: reasonCode,
-  };
-}
-
-export function classifyDecision(flags = {}) {
-  if (!flags || typeof flags !== "object" || Array.isArray(flags)) {
-    return { classification: "NON_BLOCKING", reasonCode: "SAFE_REVERSIBLE_LOCAL_DEFAULT", blockingReason: null };
-  }
-
-  for (const [flag, reasonCode] of BLOCKING_RULES) {
-    if (flags[flag] === true) return blockingDecision(reasonCode);
-  }
-  if (flags.reversible === false || flags.local === false) {
-    return blockingDecision(
-      flags.reversible === false
-        ? "IRREVERSIBLE_DECISION_REQUIRED"
-        : "REAL_BUSINESS_FACT_REQUIRED",
-    );
-  }
-
-  return {
-    classification: "NON_BLOCKING",
-    reasonCode: "SAFE_REVERSIBLE_LOCAL_DEFAULT",
-    blockingReason: null,
-  };
-}
-
-export function canAskUser(decision) {
-  return decision?.classification === "BLOCKING"
-    && BLOCKING_REASON_CODES.includes(decision.reasonCode)
-    && decision.blockingReason === decision.reasonCode;
-}

package/src/core/gates.js

@@ -1,57 +0,0 @@
-import { PROTOCOL_VERSION } from "./protocol.js";
-import path from "node:path";
-
-export const GATE_SCHEMA_VERSION = 1;
-export const GATE_STATUSES = Object.freeze(["satisfied", "unverified", "blocked"]);
-
-function stringArray(value, label) {
-  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
-    throw new Error(`${label} must be an array of non-empty strings`);
-  }
-  return [...value];
-}
-
-function artifactList(value) {
-  if (!Array.isArray(value)) throw new Error("Gate artifacts must be an array");
-  return value.map((artifact) => {
-    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
-      throw new Error("Gate artifact entries must be objects");
-    }
-    if (typeof artifact.path !== "string" || !artifact.path) throw new Error("Gate artifact path is required");
-    const portable = artifact.path.replaceAll("\\", "/");
-    const normalized = path.posix.normalize(portable);
-    if (portable.startsWith("/") || /^[A-Za-z]:\//.test(portable) || normalized === ".." || normalized.startsWith("../")) {
-      throw new Error(`Gate artifact path escapes the target: ${artifact.path}`);
-    }
-    if (typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(artifact.sha256)) {
-      throw new Error(`Gate artifact hash is invalid: ${artifact.path}`);
-    }
-    return { path: normalized.replace(/^\.\//, ""), sha256: artifact.sha256 };
-  });
-}
-
-export function createGate(input = {}) {
-  if (typeof input.taskId !== "string" || !input.taskId) throw new Error("Gate taskId is required");
-  if (typeof input.gate !== "string" || !input.gate) throw new Error("Gate name is required");
-  if (!GATE_STATUSES.includes(input.status)) throw new Error(`Unknown gate status: ${input.status}`);
-  const artifacts = artifactList(input.artifacts ?? []);
-  return {
-    schemaVersion: GATE_SCHEMA_VERSION,
-    protocolVersion: PROTOCOL_VERSION,
-    taskId: input.taskId,
-    gate: input.gate,
-    status: input.status,
-    requiredBy: stringArray(input.requiredBy ?? [], "Gate requiredBy"),
-    artifacts,
-    decisions: stringArray(input.decisions ?? [], "Gate decisions"),
-    unknowns: stringArray(input.unknowns ?? [], "Gate unknowns"),
-    approvedAssumptions: stringArray(input.approvedAssumptions ?? [], "Gate approvedAssumptions"),
-    evidence: Array.isArray(input.evidence) ? input.evidence.map((item) => ({ ...item })) : [],
-  };
-}
-
-import { taskGatePath } from "./task-paths.js";
-
-export function requiredGatePaths(gates, { taskId } = {}) {
-  return [...new Set(gates)].sort().map((gate) => (taskId ? taskGatePath(taskId, gate) : `.forgeloop/gates/${gate}.json`));
-}