@cassiomc1/forgeloop 1.2.1 → 1.2.3

package/src/cli.js

@@ -21,10 +21,17 @@ import { formatCompleteResult, runComplete } from "./commands/complete.js";
 import { formatAuditResult, runAudit } from "./commands/audit.js";
 import { formatReportResult, runReport } from "./commands/report.js";
 import { formatPolicyResult, runPolicy } from "./commands/policy.js";
+import { formatPolicyDiscoverResult, runPolicyDiscover } from "./commands/policy-discover.js";
+import { formatPolicyStatusResult, runPolicyStatus } from "./commands/policy-status.js";
+import { formatPolicyDiffResult, runPolicyDiff } from "./commands/policy-diff.js";
+import { formatRuleVerifyResult, runRuleVerify } from "./commands/rule-verify.js";
+import { formatBaselineResult, runBaseline } from "./commands/baseline.js";
+import { formatProfileInterviewResult, runProfileInterview } from "./commands/profile-interview.js";
 import { formatBundleResult, runBundle } from "./commands/bundle.js";
 import { formatPrepareCompletionResult, runPrepareCompletion } from "./commands/prepare-completion.js";
 import { formatRecordCheckResult, runRecordCheck } from "./commands/record-check.js";
 import { formatRunCheckResult, runCheck } from "./commands/run-check.js";
+import { formatReconcileClosureResult, reconcileClosure } from "./commands/reconcile-closure.js";
 import { formatRecordTerminalResult, runRecordTerminalResult } from "./commands/record-terminal-result.js";
 import { formatRecordDiagnosisResult, runRecordDiagnosis } from "./commands/record-diagnosis.js";
 import { formatProgressResult, runProgress } from "./commands/progress.js";
@@ -339,6 +346,18 @@ export function validateCliSemantics({ command, options } = {}) {
       throw new Error("run-check requires -- followed by an exact command argv");
     }
   }
+  if (command === "reconcile-closure" && !options.help) {
+    if (!options.task) throw new Error("reconcile-closure requires --task");
+    if (!options.checkId) throw new Error("reconcile-closure requires --id");
+    if (!options.checkRequirement) throw new Error("reconcile-closure requires --requirement");
+    if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
+      || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
+      throw new Error("reconcile-closure accepts only --id, --requirement, --details, and -- <argv>");
+    }
+    if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) {
+      throw new Error("reconcile-closure requires -- followed by an exact command argv");
+    }
+  }
 }
 
 export function parseArgs(argv) {
@@ -553,6 +572,42 @@ export const COMMAND_HANDLERS = Object.freeze({
     console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyResult(result));
     return 0;
   },
+  "policy-discover": async ({ target, packageRoot, options }) => {
+    const result = await runPolicyDiscover({ target, packageRoot, write: options.write });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyDiscoverResult(result));
+    return 0;
+  },
+  "policy-status": async ({ target, packageRoot, options }) => {
+    const result = await runPolicyStatus({ target, packageRoot, taskId: options.task });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyStatusResult(result));
+    return result.status === "VALID" ? 0 : 1;
+  },
+  "policy-diff": async ({ target, packageRoot, options }) => {
+    const result = await runPolicyDiff({ target, packageRoot, taskId: options.task, before: options.before, after: options.after });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyDiffResult(result));
+    return 0;
+  },
+  "rule-verify": async ({ target, packageRoot, options }) => {
+    const result = await runRuleVerify({ target, packageRoot, rule: options.rule });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatRuleVerifyResult(result));
+    return result.status === "VALID" ? 0 : 1;
+  },
+  baseline: async ({ target, packageRoot, options }) => {
+    const result = await runBaseline({
+      target,
+      packageRoot,
+      record: options.record,
+      update: options.update,
+      policyResetAuthorized: options.policyResetAuthorized,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatBaselineResult(result));
+    return 0;
+  },
+  "profile-interview": async ({ target, packageRoot, options }) => {
+    const result = await runProfileInterview({ target, packageRoot, dryRun: options.dryRun });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatProfileInterviewResult(result));
+    return 0;
+  },
   bundle: async ({ target, packageRoot, options }) => {
     const result = await runBundle({ target, packageRoot, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatBundleResult(result));
@@ -564,7 +619,7 @@ export const COMMAND_HANDLERS = Object.freeze({
     return result.ok ? 0 : 1;
   },
   "validate-receipt": async ({ target, packageRoot, options }) => {
-    const result = await runValidateReceipt({ target, packageRoot, file: options.file });
+    const result = await runValidateReceipt({ target, packageRoot, file: options.file, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : "valid: execution receipt");
     return 0;
   },
@@ -640,6 +695,19 @@ export const COMMAND_HANDLERS = Object.freeze({
     console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskUnlockResult(result));
     return 0;
   },
+  "reconcile-closure": async ({ target, packageRoot, options }) => {
+    const result = await reconcileClosure({
+      target,
+      packageRoot,
+      taskId: options.task,
+      checkId: options.checkId,
+      checkRequirement: options.checkRequirement,
+      checkDetails: options.checkDetails,
+      commandArgv: options.commandArgv,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatReconcileClosureResult(result));
+    return 0;
+  },
   update: async ({ target, packageRoot, packageVersion, options }) => {
     const result = await runUpdate({ target, dryRun: options.dryRun, packageRoot, packageVersion });
     printActions(result.actions);

package/src/commands/baseline.js

@@ -0,0 +1,120 @@
+import {
+  computePolicyLockData,
+  evaluateTargetPolicy,
+  loadEffectiveRules,
+  writePolicyLock,
+  readTaskPolicySnapshot,
+} from "../core/policy-engine.js";
+import {
+  createBaselineFromViolations,
+  readBaseline,
+  writeBaseline,
+} from "../core/policy-baseline.js";
+import { discoverTasks } from "../core/task-discovery.js";
+
+function baselineError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+export async function runBaseline({
+  target = process.cwd(),
+  packageRoot,
+  record = false,
+  update = false,
+  policyResetAuthorized = false,
+} = {}) {
+  const policyEval = await evaluateTargetPolicy({ target, packageRoot });
+  let baseline = await readBaseline(target, packageRoot);
+
+  const tasks = await discoverTasks(target, packageRoot);
+  let hasActivePolicyTask = false;
+  for (const t of tasks) {
+    if (t.healthy && t.phase && t.phase !== "COMPLETE" && t.phase !== "BLOCKED") {
+      const snap = await readTaskPolicySnapshot(target, t.taskId, packageRoot);
+      if (snap) {
+        hasActivePolicyTask = true;
+        break;
+      }
+    }
+  }
+
+  if (record) {
+    if (hasActivePolicyTask && !policyResetAuthorized) {
+      throw baselineError(
+        "E_BASELINE_RECORD_DURING_ACTIVE_TASK",
+        "Cannot re-record baseline during an active task with policy snapshot. Resolve new violations or use monotonic baseline --update.",
+      );
+    }
+
+    const allViolations = [];
+    for (const r of policyEval.rules) {
+      if (r.violations) allViolations.push(...r.violations);
+    }
+    baseline = createBaselineFromViolations(allViolations);
+    await writeBaseline(target, baseline, packageRoot);
+
+    const rules = await loadEffectiveRules(target, packageRoot);
+    const lock = computePolicyLockData(rules, baseline);
+    await writePolicyLock(target, lock, packageRoot);
+
+    return {
+      status: "RECORDED",
+      baseline,
+      violationCount: allViolations.length,
+      lock: lock.digest,
+    };
+  }
+
+  if (update && policyEval.ratchetedBaseline) {
+    // Monotonic check: new baseline cannot contain any fingerprint not in old baseline
+    const oldBaselineMap = new Map((baseline?.entries ?? []).map((e) => [e.ruleId, new Set(e.fingerprints ?? [])]));
+    for (const entry of policyEval.ratchetedBaseline.entries) {
+      const oldFps = oldBaselineMap.get(entry.ruleId) ?? new Set();
+      const hasExpansion = entry.fingerprints.some((fp) => !oldFps.has(fp));
+      if (hasExpansion) {
+        throw baselineError(
+          "E_BASELINE_EXPANSION",
+          `Cannot expand baseline debt for rule ${entry.ruleId}. Monotonic ratchet down allows removing debt only.`,
+        );
+      }
+    }
+
+    baseline = policyEval.ratchetedBaseline;
+    await writeBaseline(target, baseline, packageRoot);
+
+    const rules = await loadEffectiveRules(target, packageRoot);
+    const lock = computePolicyLockData(rules, baseline);
+    await writePolicyLock(target, lock, packageRoot);
+
+    return {
+      status: "UPDATED",
+      baseline,
+      resolvedCount: policyEval.resolvedViolations?.length ?? 0,
+      remainingCount: baseline.entries.reduce((sum, e) => sum + e.fingerprints.length, 0),
+      lock: lock.digest,
+    };
+  }
+
+  return {
+    status: baseline ? "VALID" : "NOT_PRESENT",
+    baseline,
+    baselinedViolations: policyEval.baselineViolations,
+    newViolations: policyEval.newViolations?.length ?? 0,
+    resolvedViolations: policyEval.resolvedViolations?.length ?? 0,
+  };
+}
+
+export function formatBaselineResult(result) {
+  const lines = [
+    `FORGELOOP POLICY BASELINE: ${result.status}`,
+    `Baselined Debt: ${result.baselinedViolations ?? (result.baseline?.entries?.reduce((sum, e) => sum + e.fingerprints.length, 0) ?? 0)}`,
+    `New Violations: ${result.newViolations ?? 0}`,
+    `Resolved Debt: ${result.resolvedViolations ?? result.resolvedCount ?? 0}`,
+  ];
+  if (result.lock) {
+    lines.push(`Lock: ${result.lock}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/init.js

@@ -6,8 +6,153 @@ import {
   writeManifest,
 } from "../core/manifest.js";
 import { readTemplateEntries } from "../core/templates.js";
+import { PROJECT_ARTIFACT_PATHS } from "../core/task-paths.js";
+import { isKitPath } from "../core/target-layout.js";
+import { E_INIT_KIT_CONFLICT, E_POLICY_INITIALIZATION_FAILED } from "../core/error-codes.js";
 
-export async function runInit({ target, dryRun, packageRoot, packageVersion }) {
+// Compatibility re-exports: the canonical semantic definitions live in
+// src/core/error-codes.js; this keeps existing import paths working while
+// ensuring there is exactly one literal source for each constant.
+export { E_INIT_KIT_CONFLICT, E_POLICY_INITIALIZATION_FAILED };
+
+/**
+ * Executable-policy artifacts initialized by `forgeloop init`. The manifest is
+ * the initialization commit marker and must never be written before these have
+ * been produced and verified.
+ */
+export const POLICY_INIT_ARTIFACTS = Object.freeze([
+  PROJECT_ARTIFACT_PATHS.policyDiscovery,
+  PROJECT_ARTIFACT_PATHS.policyBaseline,
+  PROJECT_ARTIFACT_PATHS.policyLock,
+]);
+
+function policyInitializationError(cause) {
+  const error = new Error(`Executable policy initialization failed: ${cause.message}`);
+  error.code = E_POLICY_INITIALIZATION_FAILED;
+  error.cause = cause;
+  error.artifacts = [...POLICY_INIT_ARTIFACTS];
+  return error;
+}
+
+function baselineSemanticallyEqual(a, b) {
+  return a?.schemaVersion === b?.schemaVersion
+    && JSON.stringify(a?.entries ?? []) === JSON.stringify(b?.entries ?? []);
+}
+
+function lockSemanticallyEqual(a, b) {
+  return a?.algorithm === b?.algorithm
+    && a?.digest === b?.digest
+    && a?.rulesDigest === b?.rulesDigest
+    && a?.baselineDigest === b?.baselineDigest;
+}
+
+/**
+ * Reconciles an existing policy artifact against the freshly computed
+ * canonical initialized state.
+ *
+ *   - missing             -> write it
+ *   - valid + equal       -> reuse (resumable output of a failed init)
+ *   - valid + different   -> not provably ForgeLoop-owned: preserve and fail
+ *                            with a deterministic conflict
+ *   - invalid/corrupt     -> fail closed; never overwrite unknown content
+ */
+async function reconcilePolicyArtifact(target, packageRoot, readExisting, expected, { semanticEqual, label }) {
+  let existing = null;
+  try {
+    existing = await readExisting(target, packageRoot);
+  } catch (cause) {
+    throw policyInitializationError(
+      new Error(`${label} exists but is invalid and cannot be safely reconciled: ${cause.message}`),
+    );
+  }
+  if (existing === null) return { action: "write" };
+  if (semanticEqual(existing, expected)) return { action: "reuse" };
+  throw policyInitializationError(
+    new Error(`${label} does not match the canonical initialized state and is not provably ForgeLoop-owned; preserve it or remove it before re-running init`),
+  );
+}
+
+/**
+ * Classifies an existing template destination against the shipped template.
+ * Shared by the pre-mutation conflict scan and the mutation loop so the two
+ * phases cannot drift apart:
+ *
+ *   - MATCH            existing bytes equal the shipped template (resumable)
+ *   - PRESERVE_PROFILE custom PROJECT_PROFILE.md (intentionally preservable)
+ *   - KIT_CONFLICT     canonical hidden kit content differs (fail closed)
+ *   - PRESERVE_UNOWNED pre-existing root/brownfield file (preserve, unowned)
+ */
+export function classifyExistingInitTemplate({ entry, existingBytes }) {
+  const existingHash = sha256(existingBytes);
+  const templateHash = sha256(entry.bytes);
+
+  if (existingHash === templateHash) {
+    return { kind: "MATCH", existingHash, templateHash };
+  }
+  if (entry.sourcePath === "PROJECT_PROFILE.md") {
+    return { kind: "PRESERVE_PROFILE", existingHash, templateHash };
+  }
+  if (isKitPath(entry.relativePath)) {
+    return { kind: "KIT_CONFLICT", existingHash, templateHash };
+  }
+  return { kind: "PRESERVE_UNOWNED", existingHash, templateHash };
+}
+
+function kitConflictError(relativePath) {
+  const error = new Error(
+    `Canonical ForgeLoop kit file conflicts with shipped template: ${relativePath}`,
+  );
+  error.code = E_INIT_KIT_CONFLICT;
+  error.artifacts = [relativePath];
+  return error;
+}
+
+/**
+ * Initializes a target project with the ForgeLoop kit and executable-policy
+ * bootstrap, committing manifest authority LAST.
+ *
+ * Execution order:
+ *   PHASE 1 — READ / PLAN (no writes):
+ *     1. validate all destination paths
+ *     2. read template entries
+ *     3. inspect the manifest
+ *     4. classify every existing template destination; a canonical kit
+ *        conflict throws E_INIT_KIT_CONFLICT before ANY write
+ *     5. compute policy discovery, baseline, effective rules, and policy.lock
+ *        in memory
+ *     6. pre-reconcile existing policy artifacts (read-only) so a policy
+ *        conflict also fails before any write
+ *   PHASE 2 — MUTATE:
+ *     7. write/reuse allowed kit files per the precomputed plan
+ *     8. write/reuse policy artifacts per the precomputed decisions
+ *     9. verify executable-policy capability and policy.lock
+ *    10. write manifest atomically
+ *    11. return success
+ *
+ * Any policy-bootstrap failure raises E_POLICY_INITIALIZATION_FAILED and
+ * leaves no committed manifest, so a retry reconciles already-correct files
+ * without manual cleanup.
+ *
+ * `init --dry-run` performs the same deterministic initialization planning and
+ * conflict detection as real init (existing manifest, unsafe paths, canonical
+ * kit conflicts, invalid or conflicting policy artifacts, and the computable
+ * policy state), but performs NO mutation: it does not simulate filesystem
+ * failures that only occur during a real write, power loss, post-write races,
+ * or verification of bytes that were never written.
+ *
+ * `hooks` is a deterministic failure-injection seam used only by tests:
+ *   afterPolicyDiscovery(discovery, { target, packageRoot })
+ *   beforeBaselineWrite({ target, packageRoot, baseline })
+ *   beforePolicyLockWrite({ target, packageRoot, lock })
+ *   beforeManifestWrite({ target, packageRoot, manifest, actions })
+ */
+export async function runInit({
+  target,
+  dryRun,
+  packageRoot,
+  packageVersion,
+  hooks = {},
+} = {}) {
   const entries = await readTemplateEntries(packageRoot);
   const existingManifest = await readManifest(target);
   if (existingManifest) {
@@ -16,20 +161,112 @@ export async function runInit({ target, dryRun, packageRoot, packageVersion }) {
   const manifest = createManifest(packageVersion);
   const actions = [];
 
-  // Validate every destination before any write so a symlinked kit cannot
+  // 1. Validate every destination before any write so a symlinked kit cannot
   // leave a partially initialized target behind.
   for (const entry of entries) await assertSafePath(target, entry.relativePath);
+  for (const relativePath of POLICY_INIT_ARTIFACTS) await assertSafePath(target, relativePath);
 
+  // 4. Pre-scan every existing template destination during planning. A
+  // deterministic canonical kit conflict must fail before ANY initialization
+  // write: no adapter, no kit file, no policy artifact, no manifest.
+  const initPlan = new Map();
   for (const entry of entries) {
     const destination = ensureWithin(target, entry.relativePath);
-    if (await fileExists(destination)) {
-      actions.push({ action: "skip", path: entry.relativePath, reason: "exists" });
-      if (entry.sourcePath === "PROJECT_PROFILE.md") {
+    if (!(await fileExists(destination))) continue;
+    const existingBytes = await readBytes(destination);
+    const classification = classifyExistingInitTemplate({ entry, existingBytes });
+    if (classification.kind === "KIT_CONFLICT") {
+      throw kitConflictError(entry.relativePath);
+    }
+    initPlan.set(entry.relativePath, { ...classification, existingBytes });
+  }
+
+  // 5. Compute the full executable-policy bootstrap in memory first. Unknown
+  // or low-confidence discovery is legitimate autonomy and succeeds; only
+  // genuine discovery/serialization/computation failures fail closed.
+  const { discoverPolicy } = await import("../core/policy-discovery.js");
+  const {
+    loadEffectiveRules,
+    computePolicyLockData,
+    writeDiscoveryReport,
+    writePolicyLock,
+    detectPolicyCapability,
+    verifyPolicyLock,
+    readDiscoveryReport,
+    readPolicyLock,
+    readBaseline,
+    writeBaseline,
+  } = await import("../core/policy-engine.js");
+  const { createBaselineFromViolations } = await import("../core/policy-baseline.js");
+
+  let discovery;
+  let baseline;
+  let effectiveRules;
+  let lock;
+  try {
+    discovery = await discoverPolicy({ target });
+    if (hooks.afterPolicyDiscovery) {
+      discovery = await hooks.afterPolicyDiscovery(discovery, { target, packageRoot });
+    }
+    baseline = createBaselineFromViolations([]);
+    effectiveRules = await loadEffectiveRules(target, packageRoot);
+    lock = computePolicyLockData(effectiveRules, baseline);
+  } catch (cause) {
+    throw policyInitializationError(cause);
+  }
+
+  // 6. Pre-reconcile existing policy artifacts during planning (read-only) for
+  // BOTH real init and dry-run, so a deterministic policy conflict is detected
+  // with identical semantics and before any mutation. dry-run stays zero-write
+  // and only reports the resulting plan.
+  const discoveryReconcile = await reconcilePolicyArtifact(
+    target,
+    packageRoot,
+    readDiscoveryReport,
+    discovery,
+    { semanticEqual: (a, b) => JSON.stringify(a) === JSON.stringify(b), label: `${PROJECT_ARTIFACT_PATHS.policyDiscovery}` },
+  );
+  const baselineReconcile = await reconcilePolicyArtifact(
+    target,
+    packageRoot,
+    readBaseline,
+    baseline,
+    { semanticEqual: baselineSemanticallyEqual, label: `${PROJECT_ARTIFACT_PATHS.policyBaseline}` },
+  );
+  const lockReconcile = await reconcilePolicyArtifact(
+    target,
+    packageRoot,
+    readPolicyLock,
+    lock,
+    { semanticEqual: lockSemanticallyEqual, label: `${PROJECT_ARTIFACT_PATHS.policyLock}` },
+  );
+
+  // 7. Mutate: write kit files per the precomputed plan. Existing files that
+  // match the shipped template are resumable init output; PROJECT_PROFILE.md
+  // is preserved by contract; canonical hidden kit conflicts were already
+  // rejected in planning; other pre-existing (brownfield) files are preserved
+  // as unowned.
+  for (const entry of entries) {
+    const destination = ensureWithin(target, entry.relativePath);
+    const planned = initPlan.get(entry.relativePath);
+    if (planned) {
+      if (planned.kind === "MATCH") {
+        actions.push({ action: "reuse", path: entry.relativePath, reason: "matches template" });
+      } else if (planned.kind === "PRESERVE_PROFILE") {
+        actions.push({ action: "skip", path: entry.relativePath, reason: "preserved" });
         manifest.files[entry.relativePath] = {
-          sha256: sha256(await readBytes(destination)),
+          sha256: planned.existingHash,
           preserve: true,
         };
+        continue;
+      } else {
+        actions.push({ action: "skip", path: entry.relativePath, reason: "pre-existing" });
+        continue;
       }
+      manifest.files[entry.relativePath] = {
+        sha256: planned.templateHash,
+        preserve: entry.sourcePath === "PROJECT_PROFILE.md",
+      };
       continue;
     }
 
@@ -44,6 +281,67 @@ export async function runInit({ target, dryRun, packageRoot, packageVersion }) {
     };
   }
 
+  // 8-9. Write/reuse policy artifacts and verify before committing authority.
+  // dry-run performs no mutation but reports the accurate plan (reuse vs
+  // would-write) computed by the read-only reconciliation above.
+  if (dryRun) {
+    actions.push(
+      { action: discoveryReconcile.action === "reuse" ? "reuse" : "would-write", path: PROJECT_ARTIFACT_PATHS.policyDiscovery, reason: discoveryReconcile.action === "reuse" ? "matches canonical state" : "dry-run" },
+      { action: baselineReconcile.action === "reuse" ? "reuse" : "would-write", path: PROJECT_ARTIFACT_PATHS.policyBaseline, reason: baselineReconcile.action === "reuse" ? "matches canonical state" : "dry-run" },
+      { action: lockReconcile.action === "reuse" ? "reuse" : "would-write", path: PROJECT_ARTIFACT_PATHS.policyLock, reason: lockReconcile.action === "reuse" ? "matches canonical state" : "dry-run" },
+    );
+  } else {
+    actions.push(
+      { action: discoveryReconcile.action === "reuse" ? "reuse" : "created", path: PROJECT_ARTIFACT_PATHS.policyDiscovery, reason: discoveryReconcile.action === "reuse" ? "matches canonical state" : "initialized" },
+      { action: baselineReconcile.action === "reuse" ? "reuse" : "created", path: PROJECT_ARTIFACT_PATHS.policyBaseline, reason: baselineReconcile.action === "reuse" ? "matches canonical state" : "initialized" },
+      { action: lockReconcile.action === "reuse" ? "reuse" : "created", path: PROJECT_ARTIFACT_PATHS.policyLock, reason: lockReconcile.action === "reuse" ? "matches canonical state" : "initialized" },
+    );
+
+    try {
+      if (discoveryReconcile.action === "write") {
+        await writeDiscoveryReport(target, discovery, packageRoot);
+      }
+      if (hooks.beforeBaselineWrite) {
+        await hooks.beforeBaselineWrite({ target, packageRoot, baseline });
+      }
+      if (baselineReconcile.action === "write") {
+        await writeBaseline(target, baseline, packageRoot);
+      }
+      if (hooks.beforePolicyLockWrite) {
+        await hooks.beforePolicyLockWrite({ target, packageRoot, lock });
+      }
+      if (lockReconcile.action === "write") {
+        await writePolicyLock(target, lock, packageRoot);
+      }
+    } catch (cause) {
+      throw policyInitializationError(cause);
+    }
+
+    // 9. Verify canonical policy state before committing authority.
+    try {
+      const capability = await detectPolicyCapability(target, packageRoot);
+      if (capability !== "AVAILABLE") {
+        throw new Error(`Executable policy capability is ${capability} after bootstrap`);
+      }
+      const lockVerification = await verifyPolicyLock(target, packageRoot);
+      if (lockVerification.status !== "VALID") {
+        throw new Error(`Executable policy lock verification failed: ${lockVerification.status}`);
+      }
+    } catch (cause) {
+      throw policyInitializationError(cause);
+    }
+  }
+
+  // 10. Commit manifest authority LAST: successful initialization is only
+  // real once the manifest exists.
+  if (hooks.beforeManifestWrite) {
+    try {
+      await hooks.beforeManifestWrite({ target, packageRoot, manifest, actions });
+    } catch (cause) {
+      throw policyInitializationError(cause);
+    }
+  }
   await writeManifest(target, manifest, { dryRun });
+
   return { actions, manifest };
 }

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`;
+}