@cassiomc1/forgeloop 1.1.1 → 1.2.2

package/src/commands/next.js

@@ -14,7 +14,21 @@ export function formatNextActionResult(result) {
   ];
   if (result.reasons.length > 0) {
     lines.push("REASONS:");
-    lines.push(...result.reasons.map((reason) => `- ${reason.code}: ${reason.message}`));
+    for (const reason of result.reasons) {
+      lines.push(`- ${reason.code}: ${reason.message}`);
+      if (reason.resolution?.kind === "SETTLEMENT_CRITERION" && reason.resolution.settledBy) {
+        lines.push(`  SETTLED BY: ${reason.resolution.settledBy}`);
+      } else if (reason.resolution?.kind === "SETTLEMENT_CRITERIA" && Array.isArray(reason.resolution.items)) {
+        lines.push("  SETTLEMENT CRITERIA:");
+        for (const item of reason.resolution.items) {
+          lines.push(`  - ${item.decision}`);
+          lines.push(`    SETTLED BY: ${item.settledBy}`);
+        }
+      }
+    }
+  }
+  if (result.progress) {
+    lines.push(`PROGRESS: ${result.progress.status}`);
   }
   if (result.commands.length > 0) {
     lines.push("COMMANDS (SAFE SYNOPSIS ONLY):");

package/src/commands/policy-diff.js

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { diffPolicies } from "../core/policy-diff.js";
+import {
+  loadEffectiveRules,
+  readBaseline,
+  readTaskPolicySnapshot,
+} from "../core/policy-engine.js";
+
+export async function runPolicyDiff({
+  target = process.cwd(),
+  packageRoot,
+  taskId = null,
+  before = null,
+  after = null,
+} = {}) {
+  let beforePolicy;
+  let afterPolicy;
+
+  if (before) {
+    const rawBefore = await readFile(path.resolve(target, before), "utf8");
+    beforePolicy = JSON.parse(rawBefore);
+  } else if (taskId) {
+    const snapshot = await readTaskPolicySnapshot(target, taskId, packageRoot);
+    beforePolicy = snapshot ? { rules: snapshot.rules, baseline: { entries: [] } } : { rules: [], baseline: { entries: [] } };
+  } else {
+    beforePolicy = { rules: [], baseline: { entries: [] } };
+  }
+
+  if (after) {
+    const rawAfter = await readFile(path.resolve(target, after), "utf8");
+    afterPolicy = JSON.parse(rawAfter);
+  } else {
+    const rules = await loadEffectiveRules(target, packageRoot);
+    const baseline = await readBaseline(target, packageRoot);
+    afterPolicy = { rules, baseline };
+  }
+
+  return diffPolicies(beforePolicy, afterPolicy);
+}
+
+export function formatPolicyDiffResult(result) {
+  const lines = [
+    `FORGELOOP POLICY DIFF: ${result.classification}`,
+    `Changes: ${result.changes?.length ?? 0}`,
+  ];
+  for (const c of result.changes ?? []) {
+    lines.push(`  - [${c.type}] ${c.path}: ${c.description}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/policy-discover.js

@@ -0,0 +1,42 @@
+import { discoverPolicy } from "../core/policy-discovery.js";
+import {
+  computePolicyLockData,
+  loadEffectiveRules,
+  readBaseline,
+  writeDiscoveryReport,
+  writePolicyLock,
+} from "../core/policy-engine.js";
+
+export async function runPolicyDiscover({ target = process.cwd(), packageRoot, write = false } = {}) {
+  const discovery = await discoverPolicy({ target });
+  let lock = null;
+
+  if (write) {
+    await writeDiscoveryReport(target, discovery, packageRoot);
+    const baseline = await readBaseline(target, packageRoot);
+    const rules = await loadEffectiveRules(target, packageRoot);
+    lock = computePolicyLockData(rules, baseline);
+    await writePolicyLock(target, lock, packageRoot);
+  }
+
+  return {
+    ...discovery,
+    written: Boolean(write),
+    lock: lock?.digest ?? null,
+  };
+}
+
+export function formatPolicyDiscoverResult(result) {
+  const lines = [
+    "FORGELOOP POLICY DISCOVERY:",
+    `Languages: ${result.languages?.join(", ") || "none detected"}`,
+    `Testing: ${result.testing?.detected ? `detected (${result.testing.framework || result.testing.command?.join(" ")}) [${result.testing.confidence}]` : "none"}`,
+    `Linting: ${result.linting?.detected ? `detected (${result.linting.tool || result.linting.command?.join(" ")}) [${result.linting.confidence}]` : "none"}`,
+    `Architecture: ${result.architecture?.value ? `${result.architecture.value} [${result.architecture.confidence}]` : "none [UNKNOWN]"}`,
+    `Discovered Rules: ${result.discoveredRules?.length ?? 0}`,
+  ];
+  for (const rule of result.discoveredRules ?? []) {
+    lines.push(`  - ${rule.id} (${rule.severity}${rule.blocking ? ", BLOCKING" : ", ADVISORY"}): ${rule.why}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/policy-status.js

@@ -0,0 +1,33 @@
+import { evaluateTargetPolicy } from "../core/policy-engine.js";
+
+export async function runPolicyStatus({ target = process.cwd(), packageRoot, taskId = null } = {}) {
+  return evaluateTargetPolicy({ target, packageRoot, taskId });
+}
+
+export function formatPolicyStatusResult(result) {
+  const lines = [
+    `FORGELOOP POLICY STATUS: ${result.status}`,
+    `Lock: ${result.lock?.digest ?? "none"}`,
+    `Rules: ${result.rules?.length ?? 0} total (Proven: ${result.provenRules}, Inert: ${result.inertRules}, Unsupported: ${result.unsupportedRules})`,
+    `Baseline Violations: ${result.baselineViolations}`,
+    `New Violations: ${result.newViolations?.length ?? 0}`,
+    `Drift: ${result.drift?.detected ? `DETECTED (${result.drift.classification})` : "none"}`,
+  ];
+
+  if (result.errors?.length > 0) {
+    lines.push("Errors:");
+    for (const err of result.errors) {
+      lines.push(`  - ${err.code}: ${err.why || err.message || err.ruleId}`);
+      if (err.fix) lines.push(`    Fix: ${err.fix}`);
+    }
+  }
+
+  if (result.warnings?.length > 0) {
+    lines.push("Warnings:");
+    for (const warn of result.warnings) {
+      lines.push(`  - ${warn.code}: ${warn.message || warn.why}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/profile-interview.js

@@ -0,0 +1,50 @@
+import { discoverPolicy } from "../core/policy-discovery.js";
+
+export async function runProfileInterview({
+  target = process.cwd(),
+  packageRoot,
+  dryRun = false,
+} = {}) {
+  const discovery = await discoverPolicy({ target });
+  return {
+    status: "COMPLETE",
+    mode: "OPTIONAL_INTERVIEW",
+    dryRun,
+    questions: [
+      {
+        topic: "languages",
+        detected: discovery.languages,
+        recommendation: discovery.languages.join(", ") || "none",
+      },
+      {
+        topic: "testing",
+        detected: discovery.testing.detected,
+        framework: discovery.testing.framework,
+        confidence: discovery.testing.confidence,
+      },
+      {
+        topic: "linting",
+        detected: discovery.linting.detected,
+        tool: discovery.linting.tool,
+        confidence: discovery.linting.confidence,
+      },
+      {
+        topic: "architecture",
+        detected: discovery.architecture.value,
+        confidence: discovery.architecture.confidence,
+      },
+    ],
+    discovery,
+  };
+}
+
+export function formatProfileInterviewResult(result) {
+  const lines = [
+    "FORGELOOP PROFILE INTERVIEW (OPTIONAL):",
+    `Languages: ${result.discovery?.languages?.join(", ") || "none detected"}`,
+    `Testing: ${result.discovery?.testing?.detected ? `${result.discovery.testing.framework} [${result.discovery.testing.confidence}]` : "none"}`,
+    `Linting: ${result.discovery?.linting?.detected ? `${result.discovery.linting.tool} [${result.discovery.linting.confidence}]` : "none"}`,
+    `Architecture: ${result.discovery?.architecture?.value ? `${result.discovery.architecture.value} [${result.discovery.architecture.confidence}]` : "unknown"}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/progress.js

@@ -0,0 +1,51 @@
+import { evaluateProgress, PROGRESS_STATUS } from "../core/progress.js";
+import { readEvents } from "../core/events.js";
+import { readWorkState } from "../core/work-state.js";
+import { resolveTaskContext } from "../core/task-context.js";
+
+export { evaluateProgress };
+
+export async function runProgress({ target, packageRoot, taskId, task }) {
+  const resolved = await resolveTaskContext(target, { packageRoot, explicitTaskId: taskId ?? task });
+  const activeTaskId = resolved.taskId;
+
+  const state = await readWorkState(target, { packageRoot, taskId: activeTaskId });
+  const events = await readEvents(target, packageRoot, { taskId: activeTaskId });
+
+  const progress = evaluateProgress({ state, events });
+  return {
+    taskId: activeTaskId ?? state?.taskId ?? "unknown",
+    phase: state?.phase ?? "UNKNOWN",
+    verificationCycle: state?.verificationCycle ?? 1,
+    ...progress,
+  };
+}
+
+export function formatProgressResult(result) {
+  const lines = [
+    `FORGELOOP PROGRESS: ${result.status}`,
+    `PHASE: ${result.phase}`,
+    `CYCLE: ${result.verificationCycle}`,
+  ];
+
+  if (result.signals && result.signals.length > 0) {
+    lines.push("SIGNALS:");
+    for (const signal of result.signals) {
+      lines.push(`- ${signal.code}: ${signal.message}`);
+    }
+  } else {
+    lines.push("SIGNALS: none");
+  }
+
+  let recommended = "NONE";
+  if (result.status === PROGRESS_STATUS.STALLED) {
+    recommended = "CHANGE_STRATEGY";
+  } else if (result.status === PROGRESS_STATUS.WATCH) {
+    recommended = "REVIEW_CHECKS";
+  } else {
+    recommended = "ADVANCE";
+  }
+  lines.push(`RECOMMENDED: ${recommended}`);
+
+  return lines.join("\n") + "\n";
+}

package/src/commands/reconcile-closure.js

@@ -0,0 +1,49 @@
+import { runReconcileClosure } from "../core/reconcile-closure.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export async function reconcileClosure({
+  target,
+  packageRoot,
+  taskId,
+  task,
+  checkId,
+  checkRequirement,
+  checkDetails,
+  commandArgv,
+  authorityContext,
+  runtimeContext,
+}) {
+  return withTaskMutation(
+    target,
+    { taskId: taskId ?? task, packageRoot },
+    "reconcile-closure",
+    async (ctx) => {
+      return runReconcileClosure({
+        target,
+        packageRoot,
+        taskId: ctx?.taskId ?? null,
+        checkId,
+        requirement: checkRequirement,
+        argv: commandArgv,
+        details: checkDetails,
+        authorityContext,
+        runtimeContext,
+      });
+    },
+    { explicitRequired: true },
+  );
+}
+
+export function formatReconcileClosureResult(result) {
+  const previous = result.previousRepositoryFingerprint;
+  return [
+    "FORGELOOP CHECKPOINT RECONCILED",
+    `task: ${result.taskId}`,
+    `check: ${result.checkId} (passed)`,
+    `execution: ${result.executionId}`,
+    `previous: ${previous?.branch ?? "unknown"} @ ${previous?.head ?? "unknown"}`,
+    `current: ${result.repositoryFingerprint?.branch ?? "unknown"} @ ${result.repositoryFingerprint?.head ?? "unknown"}`,
+    `event: ${result.event}`,
+    "",
+  ].join("\n");
+}

package/src/commands/record-decision-criterion.js

@@ -0,0 +1,34 @@
+import { recordDecisionCriterion } from "../core/settlement.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export { recordDecisionCriterion };
+
+export async function runRecordDecisionCriterion({
+  target,
+  packageRoot,
+  decision,
+  settledBy,
+  taskId,
+  task,
+}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-decision-criterion", async (ctx) => {
+    return recordDecisionCriterion({
+      target,
+      packageRoot,
+      decision,
+      settledBy,
+      taskId: ctx?.taskId ?? null,
+    });
+  });
+}
+
+export function formatRecordDecisionCriterionResult(result) {
+  const c = result.criterion ?? result.event?.details ?? {};
+  return [
+    `FORGELOOP DECISION CRITERION RECORDED`,
+    `DECISION: ${c.decision}`,
+    `DECISION ID: ${c.decisionId}`,
+    `SETTLED BY: ${c.settledBy}`,
+    `CONTRACT FINGERPRINT: ${c.contractFingerprint}`,
+  ].join("\n") + "\n";
+}

package/src/commands/record-diagnosis.js

@@ -0,0 +1,49 @@
+import { recordDiagnosis } from "../core/diagnosis.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export { recordDiagnosis };
+
+export async function runRecordDiagnosis({
+  target,
+  packageRoot,
+  hypothesis,
+  failureClass,
+  evidenceRefs = [],
+  evidenceRef = null,
+  settledBy,
+  nextSafeAction,
+  taskId,
+  task,
+}) {
+  const refs = Array.isArray(evidenceRefs) && evidenceRefs.length > 0
+    ? evidenceRefs
+    : (evidenceRef ? [evidenceRef] : []);
+
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "record-diagnosis", async (ctx) => {
+    return recordDiagnosis({
+      target,
+      packageRoot,
+      hypothesis,
+      failureClass,
+      evidenceRefs: refs,
+      settledBy,
+      nextSafeAction,
+      taskId: ctx?.taskId ?? null,
+    });
+  });
+}
+
+export function formatRecordDiagnosisResult(result) {
+  const d = result.diagnosis ?? result.event?.details ?? {};
+  return [
+    `FORGELOOP DIAGNOSIS RECORDED`,
+    `CYCLE: ${d.verificationCycle}`,
+    `FAILURE CLASS: ${d.failureClass}`,
+    `HYPOTHESIS: ${d.hypothesis}`,
+    `INFORMATION GAIN: ${d.informationGain}`,
+    `EVIDENCE: ${(d.evidenceRefs ?? []).join(", ")}`,
+    `SETTLED BY: ${d.settledBy}`,
+    `NEXT SAFE ACTION: ${d.nextSafeAction}`,
+    `FINGERPRINT: ${d.diagnosisFingerprint}`,
+  ].join("\n") + "\n";
+}

package/src/commands/rule-verify.js

@@ -0,0 +1,36 @@
+import { loadEffectiveRules } from "../core/policy-engine.js";
+import { verifyRuleMutation } from "../core/policy-mutation.js";
+
+export async function runRuleVerify({
+  target = process.cwd(),
+  packageRoot,
+  rule = null,
+} = {}) {
+  const rules = await loadEffectiveRules(target, packageRoot);
+  const targetRules = rule ? rules.filter((r) => r.id === rule) : rules;
+
+  const verifications = [];
+  for (const r of targetRules) {
+    const res = await verifyRuleMutation({ target, rule: r });
+    verifications.push(res);
+  }
+
+  const allProven = verifications.every((v) => v.status === "PROVEN" || v.status === "UNSUPPORTED");
+
+  return {
+    status: allProven ? "VALID" : "UNPROVEN",
+    verifications,
+  };
+}
+
+export function formatRuleVerifyResult(result) {
+  const lines = [
+    `FORGELOOP RULE VERIFICATION: ${result.status}`,
+  ];
+  for (const v of result.verifications ?? []) {
+    lines.push(`  - ${v.ruleId}: ${v.status} (Mutation: ${v.mutation ?? "none"}, Expected: ${v.expected ?? "n/a"}, Observed: ${v.observed ?? "n/a"})`);
+    if (v.why) lines.push(`    Why: ${v.why}`);
+    if (v.fix && v.status !== "PROVEN") lines.push(`    Fix: ${v.fix}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/validate-receipt.js

@@ -2,9 +2,10 @@ import { assertSafePath, ensureWithin, readBytes } from "../core/filesystem.js";
 import { validateReceipt } from "../core/receipt.js";
 import { assertJsonBytes, assertJsonLimits } from "../core/json-safety.js";
 import { ARTIFACT_PATHS } from "../core/artifacts.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import { withResolvedTask } from "../core/task-command.js";
 
-export async function runValidateReceipt({ target, packageRoot, file }) {
-  const relativeFile = file ?? ARTIFACT_PATHS.receipt;
+async function validateReceiptFile(target, packageRoot, relativeFile) {
   await assertSafePath(target, relativeFile);
   const receiptPath = ensureWithin(target, relativeFile);
   let receipt;
@@ -16,5 +17,39 @@ export async function runValidateReceipt({ target, packageRoot, file }) {
   } catch (error) {
     throw new Error(`Unable to parse receipt ${relativeFile}: ${error.message}`);
   }
-  return validateReceipt(receipt, packageRoot);
+  try {
+    return await validateReceipt(receipt, packageRoot);
+  } catch (error) {
+    throw new Error(`Invalid receipt ${relativeFile}: ${error.message}`);
+  }
+}
+
+/**
+ * Validates an execution receipt with deterministic resolution precedence:
+ *   1. explicit `--file` validates exactly that relative file;
+ *   2. explicit or context-resolved `--task` validates that task's namespaced
+ *      `.forgeloop/task-state/<taskKey>/execution-receipt.json`;
+ *   3. a single active task is resolved automatically through the shared
+ *      task-command resolver;
+ *   4. when no task descriptors exist, the legacy singleton
+ *      `.forgeloop/execution-receipt.json` compatibility path is preserved.
+ * Multiple active tasks without `--task`/`--file` fail with E_TASK_AMBIGUOUS
+ * through the shared resolver instead of silently falling back to the legacy
+ * singleton.
+ */
+export async function runValidateReceipt({
+  target,
+  packageRoot,
+  file = null,
+  taskId = null,
+} = {}) {
+  if (file) {
+    return validateReceiptFile(target, packageRoot, file);
+  }
+  return withResolvedTask(target, { taskId, packageRoot }, async (ctx) => {
+    const relativeFile = ctx
+      ? taskArtifactPath(ctx.taskId, "receipt")
+      : ARTIFACT_PATHS.receipt;
+    return validateReceiptFile(target, packageRoot, relativeFile);
+  });
 }

package/src/core/artifact-registry.js

@@ -163,4 +163,64 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     isPersisted: true,
     description: "Attested command execution provenance recording argv, cwd, resolution, status, and exit code.",
   }),
+  policyRules: Object.freeze({
+    key: "policyRules",
+    scope: "PROJECT",
+    path: PROJECT_ARTIFACT_PATHS.policyRules,
+    schema: "policy-rules",
+    owner: "OPERATOR_OR_AGENT",
+    mutability: "MUTABLE_CONFIGURATION",
+    trustRole: "POLICY_SPECIFICATION",
+    isPublic: true,
+    isPersisted: true,
+    description: "Executable policy rule definitions declaring severities, checks, why, and fix guidance.",
+  }),
+  policyDiscovery: Object.freeze({
+    key: "policyDiscovery",
+    scope: "PROJECT",
+    path: PROJECT_ARTIFACT_PATHS.policyDiscovery,
+    schema: "policy-discovery",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "MUTABLE_ON_DISCOVERY",
+    trustRole: "DISCOVERED_POLICY_SPECIFICATION",
+    isPublic: true,
+    isPersisted: true,
+    description: "Deterministic repository policy discovery report with confidence scoring.",
+  }),
+  policyBaseline: Object.freeze({
+    key: "policyBaseline",
+    scope: "PROJECT",
+    path: PROJECT_ARTIFACT_PATHS.policyBaseline,
+    schema: "policy-baseline",
+    owner: "PROTOCOL_GENERATED_OR_OPERATOR",
+    mutability: "MONOTONIC_RATCHET_DOWN",
+    trustRole: "BROWNFIELD_BASELINE",
+    isPublic: true,
+    isPersisted: true,
+    description: "Brownfield policy baseline recording existing debt with sha256 violation fingerprints.",
+  }),
+  policyLock: Object.freeze({
+    key: "policyLock",
+    scope: "PROJECT",
+    path: PROJECT_ARTIFACT_PATHS.policyLock,
+    schema: "policy-lock",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "ATOMIC_DIGEST_COMPILATION",
+    trustRole: "POLICY_INTEGRITY_LOCK",
+    isPublic: true,
+    isPersisted: true,
+    description: "Canonical policy lockfile holding cryptographic digest of effective rules and baseline.",
+  }),
+  policySnapshot: Object.freeze({
+    key: "policySnapshot",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.policySnapshot}`,
+    schema: "policy-snapshot",
+    owner: "PROTOCOL_GENERATED",
+    mutability: "MUTABLE_BEFORE_EXECUTION",
+    trustRole: "TASK_POLICY_ATTESTATION",
+    isPublic: true,
+    isPersisted: true,
+    description: "Task-scoped policy snapshot binding task activation to effective policy digest.",
+  }),
 });

package/src/core/audit.js

@@ -131,6 +131,29 @@ export async function evaluateAudit({
       : blocked
         ? "INCOMPLETE"
         : "INVALID";
+  let policyStatus = null;
+  const { detectPolicyCapability, evaluateTargetPolicy } = await import("./policy-engine.js");
+  const policyCapability = await detectPolicyCapability(target, packageRoot);
+  if (policyCapability === "AVAILABLE") {
+    try {
+      const policyEval = await evaluateTargetPolicy({ target, packageRoot, taskId });
+      policyStatus = {
+        status: policyEval.status,
+        provenRules: policyEval.provenRules,
+        inertRules: policyEval.inertRules,
+        unsupportedRules: policyEval.unsupportedRules,
+        baselineViolations: policyEval.baselineViolations,
+        drift: policyEval.drift?.detected ?? false,
+      };
+    } catch {
+      policyStatus = { status: "INVALID", provenRules: 0, inertRules: 0, unsupportedRules: 0, baselineViolations: 0, drift: false };
+    }
+  } else if (policyCapability === "INVALID") {
+    policyStatus = { status: "INVALID", provenRules: 0, inertRules: 0, unsupportedRules: 0, baselineViolations: 0, drift: false };
+  } else {
+    policyStatus = { status: "NOT_APPLICABLE", provenRules: 0, inertRules: 0, unsupportedRules: 0, baselineViolations: 0, drift: false };
+  }
+
   return {
     schemaVersion: 1,
     protocolVersion: PROTOCOL_VERSION,
@@ -142,6 +165,7 @@ export async function evaluateAudit({
       status: manifest ? "ready" : manifestError ? "invalid" : "missing",
       manifest: Boolean(manifest),
     },
+    policy: policyStatus,
     completion,
     changedPaths,
     publicationStatus: completion.publicationStatus,