@cassiomc1/forgeloop 0.1.10 → 0.1.12

package/src/core/evidence-readiness.js

@@ -0,0 +1,333 @@
+import { sha256 } from "./manifest.js";
+
+export const REQUIREMENT_TYPES = Object.freeze([
+  "PRODUCT",
+  "VERIFICATION",
+  "LIFECYCLE",
+  "PUBLICATION",
+  "PRODUCTION_READINESS",
+]);
+
+export const TERMINAL_OWNED_TYPES = Object.freeze([
+  "LIFECYCLE",
+  "PUBLICATION",
+  "PRODUCTION_READINESS",
+]);
+
+const LIFECYCLE_TERMS = /\b(?:lifecycle reaches|forgeloop reaches|complete returns|validator-backed complete|completion validated|review is approved)\b/i;
+const PUBLICATION_TERMS = /\b(?:publication succeeds|release (?:is )?published|package (?:is )?published|published to|published package)\b/i;
+const PRODUCTION_TERMS = /\b(?:deployment succeeds|production deployment|production readiness|production validation|production smoke|deployed to)\b/i;
+const NON_TERMINAL_TERMS = /\b(?:tests?|lint|build|typecheck|types?|coverage|keyboard|zoom|contrast|motion|checks?|unit|e2e|integration|suite|regression|browser|responsive|html|css|js|component|api)\b/i;
+const CONJUNCTION_TERMS = /\b(?:and|with|then|plus|also|after)\b/i;
+
+export function isMixedTerminalRequirement(text) {
+  if (typeof text !== "string") return false;
+  const hasTerminal = LIFECYCLE_TERMS.test(text) || PUBLICATION_TERMS.test(text) || PRODUCTION_TERMS.test(text);
+  if (!hasTerminal) return false;
+  return NON_TERMINAL_TERMS.test(text) || CONJUNCTION_TERMS.test(text);
+}
+
+function stableId(text) {
+  return `REQ_${sha256(Buffer.from(text.trim().replace(/\s+/g, " ").toLowerCase())).slice(0, 16).toUpperCase()}`;
+}
+
+export function isPublicationStatusSatisfied(actual, required) {
+  if (required === "committed") {
+    return ["committed", "pushed", "published"].includes(actual);
+  }
+  if (required === "pushed") {
+    return ["pushed", "published"].includes(actual);
+  }
+  if (required === "published") {
+    return actual === "published";
+  }
+  if (required === "deployed") {
+    return actual === "deployed";
+  }
+  return actual === required;
+}
+
+export function classifyRequirement(input) {
+  if (typeof input === "string") {
+    const text = input.trim();
+    const isMixed = isMixedTerminalRequirement(text);
+    const type = isMixed
+      ? "VERIFICATION"
+      : LIFECYCLE_TERMS.test(text)
+        ? "LIFECYCLE"
+        : PUBLICATION_TERMS.test(text)
+          ? "PUBLICATION"
+          : PRODUCTION_TERMS.test(text)
+            ? "PRODUCTION_READINESS"
+            : "VERIFICATION";
+    let requiredPublicationStatus = undefined;
+    if (type === "PUBLICATION") {
+      if (/\b(?:publish|published|release published|published package)\b/i.test(text)) {
+        requiredPublicationStatus = "published";
+      } else if (/\b(?:deploy|deployed)\b/i.test(text)) {
+        requiredPublicationStatus = "deployed";
+      } else if (/\b(?:push|pushed)\b/i.test(text)) {
+        requiredPublicationStatus = "pushed";
+      } else if (/\b(?:commit|committed)\b/i.test(text)) {
+        requiredPublicationStatus = "committed";
+      } else {
+        requiredPublicationStatus = "published";
+      }
+    }
+    return {
+      id: stableId(text),
+      text,
+      type,
+      operator: "SINGLE",
+      lifecycleOwned: type === "LIFECYCLE",
+      terminalOwned: TERMINAL_OWNED_TYPES.includes(type),
+      mixedTerminal: isMixed,
+      requiredEvidenceKind: "OBSERVED",
+      requiredPublicationStatus,
+      requirements: [],
+    };
+  }
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("Requirement must be a string or object");
+  }
+  const text = input.text ?? input.id;
+  const classified = classifyRequirement(text);
+  const type = input.type ?? classified.type;
+  const isMixed = input.mixedTerminal ?? (typeof text === "string" && isMixedTerminalRequirement(text));
+  return {
+    ...classified,
+    ...structuredClone(input),
+    id: input.id ?? classified.id,
+    text,
+    type,
+    operator: input.operator ?? (input.requirements?.length ? "ALL" : "SINGLE"),
+    lifecycleOwned: input.lifecycleOwned ?? type === "LIFECYCLE",
+    terminalOwned: input.terminalOwned ?? TERMINAL_OWNED_TYPES.includes(type),
+    mixedTerminal: isMixed,
+    requiredEvidenceKind: input.requiredEvidenceKind ?? "OBSERVED",
+    requiredPublicationStatus: input.requiredPublicationStatus ?? classified.requiredPublicationStatus,
+    requirements: (input.requirements ?? []).map(classifyRequirement),
+  };
+}
+
+export function normalizeRequirements(requirements = []) {
+  const byId = new Map();
+  for (const raw of requirements) {
+    const requirement = classifyRequirement(raw);
+    if (!byId.has(requirement.id)) byId.set(requirement.id, requirement);
+  }
+  return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function ordinaryRequirements(requirements = []) {
+  return normalizeRequirements(requirements).filter((requirement) => !requirement.terminalOwned);
+}
+
+export function ordinaryLeafRequirements(requirements = []) {
+  const result = [];
+  function visit(requirement) {
+    if (requirement.terminalOwned) return;
+    if (requirement.operator === "ALL" && Array.isArray(requirement.requirements) && requirement.requirements.length > 0) {
+      for (const child of requirement.requirements) {
+        visit(child);
+      }
+      return;
+    }
+    result.push(requirement);
+  }
+  for (const req of normalizeRequirements(requirements)) {
+    visit(req);
+  }
+  return result;
+}
+
+export function terminalRequirements(requirements = []) {
+  return normalizeRequirements(requirements).filter((requirement) => requirement.terminalOwned);
+}
+
+export function lifecycleRequirements(requirements = []) {
+  return normalizeRequirements(requirements).filter((requirement) => requirement.type === "LIFECYCLE");
+}
+
+export function publicationRequirements(requirements = []) {
+  return normalizeRequirements(requirements).filter((requirement) => requirement.type === "PUBLICATION");
+}
+
+export function productionReadinessRequirements(requirements = []) {
+  return normalizeRequirements(requirements).filter((requirement) => requirement.type === "PRODUCTION_READINESS");
+}
+
+export function evaluateTerminalRequirements({ requirements = [], receipt = null } = {}) {
+  const normalized = normalizeRequirements(requirements);
+  const terminal = terminalRequirements(normalized);
+  const result = {
+    covered: [],
+    pending: [],
+    invalid: [],
+    errors: [],
+  };
+  const pubStatus = receipt ? (receipt.publicationStatus ?? "not-published") : "not-published";
+  const prodStatus = receipt ? (receipt.productionReadiness ?? "not-verified") : "not-verified";
+  const receiptEvidence = Array.isArray(receipt?.evidence) ? receipt.evidence : [];
+
+  for (const req of terminal) {
+    if (req.type === "LIFECYCLE") {
+      result.covered.push(req);
+    } else if (req.type === "PUBLICATION") {
+      const requiredLevel = req.requiredPublicationStatus ?? "published";
+      const matchingEvidence = receiptEvidence
+        .filter((item) => item.kind === "OBSERVED")
+        .filter((item) => item.details?.requirementId === req.id)
+        .filter((item) => item.details?.terminalType === "PUBLICATION");
+      const latestEvidence = latestAuthoritativeCheck(matchingEvidence);
+      const evidenceStatus = latestEvidence?.details?.terminalStatus;
+      const evidenceSatisfied = isPublicationStatusSatisfied(evidenceStatus, requiredLevel);
+      const globalSatisfied = isPublicationStatusSatisfied(pubStatus, requiredLevel);
+
+      if (globalSatisfied && evidenceSatisfied) {
+        result.covered.push(req);
+      } else {
+        result.pending.push(req);
+        result.errors.push({
+          code: "E_PUBLICATION_REQUIREMENT_PENDING",
+          message: `The contract explicitly requires publication status '${requiredLevel}', but publication evidence/status is insufficient for requirement: ${req.text}`,
+          requirementId: req.id,
+        });
+      }
+    } else if (req.type === "PRODUCTION_READINESS") {
+      const matchingEvidence = receiptEvidence
+        .filter((item) => item.kind === "OBSERVED")
+        .filter((item) => item.details?.requirementId === req.id)
+        .filter((item) => item.details?.terminalType === "PRODUCTION_READINESS");
+      const latestEvidence = latestAuthoritativeCheck(matchingEvidence);
+      const evidenceStatus = latestEvidence?.details?.terminalStatus;
+      const evidenceSatisfied = evidenceStatus === "ready" || evidenceStatus === "verified";
+      const globalSatisfied = prodStatus === "ready" || prodStatus === "verified";
+
+      if (globalSatisfied && evidenceSatisfied) {
+        result.covered.push(req);
+      } else {
+        result.pending.push(req);
+        result.errors.push({
+          code: "E_PRODUCTION_REQUIREMENT_PENDING",
+          message: `The contract explicitly requires production readiness, but production readiness evidence/status is insufficient for requirement: ${req.text}`,
+          requirementId: req.id,
+        });
+      }
+    }
+  }
+  return result;
+}
+
+export function matchesRequirement(check, requirement) {
+  return check?.requirement === requirement.id || check?.requirement === requirement.text;
+}
+
+export function latestAuthoritativeCheck(candidates) {
+  if (!candidates || candidates.length === 0) return null;
+  return [...candidates].sort((a, b) => {
+    const cycleA = a.details?.verificationCycle ?? a.verificationCycle ?? 1;
+    const cycleB = b.details?.verificationCycle ?? b.verificationCycle ?? 1;
+    if (cycleA !== cycleB) return cycleA - cycleB;
+    const timeA = typeof a.timestamp === "string" ? a.timestamp : "";
+    const timeB = typeof b.timestamp === "string" ? b.timestamp : "";
+    if (timeA !== timeB) return timeA.localeCompare(timeB);
+    return 0;
+  }).at(-1);
+}
+
+export function authoritativeChecksForRequirements({ requirements = [], checks = [] } = {}) {
+  return normalizeRequirements(requirements).map((requirement) => {
+    const candidates = checks.filter((check) => matchesRequirement(check, requirement));
+    return {
+      requirement,
+      check: latestAuthoritativeCheck(candidates),
+    };
+  });
+}
+
+function componentStatus(check, requirement, allChecks = []) {
+  if (requirement.operator !== "ALL" || !requirement.requirements?.length) return null;
+  const components = check?.details?.components;
+  const statuses = requirement.requirements.map((child) => {
+    if (Array.isArray(components)) {
+      const matchingComp = components.filter((item) => (
+        item?.requirementId === child.id || item?.requirement === child.text
+      )).at(-1);
+      if (matchingComp) return matchingComp;
+    }
+    const childCandidates = allChecks.filter((candidate) => matchesRequirement(candidate, child));
+    return latestAuthoritativeCheck(childCandidates);
+  });
+  if (statuses.some((item) => !item)) return "MISSING";
+  if (statuses.some((item) => item.status === "failed")) return "INVALID";
+  if (statuses.some((item) => item.status !== "passed" || item.evidenceKind !== "OBSERVED")) return "PARTIAL";
+  return "COVERED";
+}
+
+export function evaluateRequiredEvidence({ requirements = [], checks = [] } = {}) {
+  const normalized = normalizeRequirements(requirements);
+  const result = {
+    ready: true,
+    required: normalized,
+    covered: [],
+    missing: [],
+    partial: [],
+    invalid: [],
+    lifecyclePending: [],
+    reasonCodes: [],
+  };
+  for (const requirement of normalized) {
+    if (requirement.mixedTerminal) {
+      result.invalid.push({
+        ...requirement,
+        reasonCode: "E_CIRCULAR_COMPLETION_REQUIREMENT",
+      });
+      continue;
+    }
+    if (requirement.terminalOwned || requirement.lifecycleOwned) {
+      result.lifecyclePending.push(requirement);
+      continue;
+    }
+    const candidates = checks.filter((check) => matchesRequirement(check, requirement));
+    const check = latestAuthoritativeCheck(candidates);
+    const compound = componentStatus(check, requirement, checks);
+    if (compound === "INVALID" || check?.status === "failed") {
+      result.invalid.push(requirement);
+    } else if (compound === "PARTIAL") {
+      result.partial.push(requirement);
+    } else if (compound === "MISSING") {
+      result.missing.push(requirement);
+    } else if (
+      (check?.status === "passed" || compound === "COVERED")
+      && (requirement.requiredEvidenceKind !== "OBSERVED" || check?.evidenceKind === "OBSERVED" || compound === "COVERED")
+      && (compound === null || compound === "COVERED")
+    ) {
+      result.covered.push(requirement);
+    } else if (check?.status === "passed" && check.evidenceKind !== "OBSERVED") {
+      result.invalid.push({ ...requirement, reasonCode: "E_EVIDENCE_KIND_INVALID" });
+    } else if (check) {
+      result.partial.push(requirement);
+    } else {
+      result.missing.push(requirement);
+    }
+  }
+  result.ready = result.missing.length === 0 && result.partial.length === 0 && result.invalid.length === 0;
+  if (result.invalid.length) {
+    const specificCodes = result.invalid
+      .map((item) => item.reasonCode)
+      .filter(Boolean);
+    if (specificCodes.length > 0) {
+      result.reasonCodes.push(...new Set(specificCodes));
+    } else {
+      result.reasonCodes.push("E_EVIDENCE_INVALID");
+    }
+  }
+  if (result.missing.length) result.reasonCodes.push("E_EVIDENCE_REQUIRED");
+  if (result.partial.length) result.reasonCodes.push("E_EVIDENCE_PARTIAL");
+  const leaves = ordinaryLeafRequirements(normalized);
+  const authoritativeLeaves = authoritativeChecksForRequirements({ requirements: leaves, checks });
+  result.authoritativeFailures = authoritativeLeaves.filter(({ check }) => check?.status === "failed");
+  result.authoritativeBlocked = authoritativeLeaves.filter(({ check }) => check?.status === "blocked");
+  return result;
+}

package/src/core/evidence.js

@@ -19,10 +19,22 @@ function assertNonEmptyString(value, label) {
   }
 }
 
-export function createEvidence(input, source, result, details) {
+export function createEvidence(input, source, result, details, cycle) {
   const value = typeof input === "string"
-    ? { kind: input, source, result, ...(details === undefined ? {} : { details }) }
-    : input;
+    ? {
+        kind: input,
+        source,
+        result,
+        ...(cycle !== undefined ? { verificationCycle: cycle } : {}),
+        details: {
+          ...(details === undefined ? {} : details),
+          ...(cycle !== undefined ? { verificationCycle: cycle } : {}),
+        },
+      }
+    : structuredClone(input);
+  if (value.details && typeof value.details === "object" && value.verificationCycle !== undefined) {
+    value.details.verificationCycle = value.verificationCycle;
+  }
   assertEvidence(value);
   return value;
 }
@@ -36,6 +48,9 @@ export function assertEvidence(value, label = "evidence") {
   }
   assertNonEmptyString(value.source, `${label}.source`);
   assertNonEmptyString(value.result, `${label}.result`);
+  if (value.verificationCycle !== undefined && (!Number.isInteger(value.verificationCycle) || value.verificationCycle < 1)) {
+    throw new EvidenceError(`${label}.verificationCycle must be a positive integer`);
+  }
   return value;
 }
 
@@ -50,7 +65,10 @@ export function evidenceMatches(evidence, terms) {
     .filter((term) => typeof term === "string" && term.length > 0)
     .map((term) => term.toLowerCase());
   return (evidence ?? []).some((item) => {
-    const haystack = `${item.source} ${item.result}`.toLowerCase();
+    const detailsText = item.details
+      ? `${item.details.requirementText ?? ""} ${String(item.details.terminalType ?? "").replace(/_/g, " ")}`
+      : "";
+    const haystack = `${item.source} ${item.result} ${detailsText}`.toLowerCase();
     return normalizedTerms.some((term) => haystack.includes(term));
   });
 }

package/src/core/execution-prerequisites.js

@@ -1,6 +1,6 @@
 import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
-import { validateEventLedger } from "./events.js";
+import { validateEventLedger, validateStateLedgerCoherence } from "./events.js";
 import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { stateIdentityErrors } from "./completion-relationships.js";
@@ -195,6 +195,11 @@ export async function evaluateStartExecutionPrerequisites({ target, state, packa
 
   const ledger = await validateEventLedger(target, packageRoot);
   errors.push(...prerequisiteLedgerErrors(ledger, contract.value.taskId, preflight, route));
+  errors.push(...validateStateLedgerCoherence(state, ledger.events).map((error) => issue(
+    error.code,
+    error.message,
+    [ARTIFACT_PATHS.state, ARTIFACT_PATHS.events],
+  )));
   errors.push(...persistedPreflightErrors);
   return { errors, requiredArtifacts, contract, route, preflight, persistedPreflight, ledger };
 }

package/src/core/inspect.js

@@ -1,5 +1,5 @@
 import { fileExists, ensureWithin, readBytes } from "./filesystem.js";
-import { AGENT_SUPPORT } from "./agent-support.js";
+import { DISCOVERY_SURFACES } from "./discovery-surfaces.js";
 import { readManifest } from "./manifest.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { inspectSchemaHealth } from "./schema-validation.js";
@@ -42,15 +42,14 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
     ? `${FORGELOOP_KIT_DIR}/schemas`
     : "schemas";
   const doctor = await runDoctor({ target, packageRoot });
-  const agents = await Promise.all(AGENT_SUPPORT.map(async (record) => ({
-    id: record.id,
-    name: record.name,
-    support: record.support,
-    instructionFiles: record.instructionFiles,
-    available: (await Promise.all(
-      record.instructionFiles.map(async (relativePath) => fileExists(ensureWithin(target, relativePath))),
-    )).some(Boolean),
+  const surfaces = await Promise.all(DISCOVERY_SURFACES.map(async (surface) => ({
+    id: surface.id,
+    path: surface.path,
+    kind: surface.kind,
+    available: await fileExists(ensureWithin(target, surface.path)),
   })));
+  const availableSurfaces = surfaces.filter((surface) => surface.available);
+  const protocolActivated = availableSurfaces.length > 0;
 
   const findings = [...doctor.findings];
   for (const schema of schemaHealth.schemas) {
@@ -100,9 +99,20 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
       error: manifestError,
     },
     profile,
+    integration: {
+      protocolActivated,
+      protocolMarker: "FORGELOOP_PROJECT_PROTOCOL=REQUIRED",
+      discovery: {
+        status: protocolActivated ? "INSTRUCTION_DISCOVERED" : "INSTRUCTION_ABSENT",
+        surfaces,
+      },
+      capability: {
+        status: "NOT_VERIFIED",
+      },
+    },
     adapters: {
-      detected: agents.filter((agent) => agent.available).map((agent) => agent.id),
-      agents,
+      detected: availableSurfaces.map((s) => s.path),
+      surfaces,
     },
     protocol: {
       version: PROTOCOL_VERSION,
@@ -112,7 +122,8 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
     },
     state: { ...state, path: WORK_STATE_PATH, present: statePresent },
     compatibility: {
-      agents: AGENT_SUPPORT.map((record) => record.id),
+      deprecated: true,
+      agents: [],
     },
     findings,
     evidence,

package/src/core/native-adapters.js

@@ -15,13 +15,40 @@ export function nativeShimReferences(relativePath) {
   const prefix = nativeShimPrefix(relativePath);
   return [
     `${prefix}/LOOP_ENGINEERING.md`,
-    `${prefix}/AGENT_COMPATIBILITY.md`,
+    `${prefix}/PROTOCOL_INTEGRATION.md`,
   ];
 }
 
 export function nativeShim(relativePath) {
   const kitPrefix = nativeShimPrefix(relativePath);
-  return `# ForgeLoop native adapter\n\nRead and follow the canonical ForgeLoop protocol in ${kitPrefix}/LOOP_ENGINEERING.md and ${kitPrefix}/AGENT_COMPATIBILITY.md.\nThe canonical guides and schemas are under ${kitPrefix}/; keep this adapter concise and preserve any host-specific instructions.\n`;
+  return `<!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
+# ForgeLoop Project Protocol
+
+This project is ForgeLoop-enabled.
+
+If your execution environment loaded this file, ForgeLoop applies to work
+performed in this project regardless of model, provider, product, IDE,
+agent name, runtime name, or orchestration environment.
+
+Do not treat ForgeLoop as vendor-specific, harness-specific, optional,
+advisory, or something to follow only "in spirit".
+
+Read and follow:
+- ${kitPrefix}/LOOP_ENGINEERING.md
+- ${kitPrefix}/PROTOCOL_INTEGRATION.md
+
+Before changing product or executable files, establish the ForgeLoop contract,
+route, required gates, and READY preflight.
+
+Use the project-local ForgeLoop CLI for lifecycle-owned protocol state.
+Never manually synthesize lifecycle chronology or assign ForgeLoop COMPLETE.
+
+Before claiming ForgeLoop-verified completion, require
+\`forgeloop complete\` to return \`VALID\`.
+
+If a required capability is unavailable, report that ForgeLoop dimension as
+not verified rather than simulating it.
+`;
 }
 
 export function resolveNativeReference(relativePath, reference) {
@@ -45,6 +72,7 @@ export function inspectNativeAdapter(relativePath, bytes) {
     missingReferences,
     resolvedReferences,
     hasForgeLoopMarker: /forgeloop/i.test(text),
+    hasProtocolMarker: text.includes("FORGELOOP_PROJECT_PROTOCOL=REQUIRED"),
   };
 }