@echopath-labs/forgerail 0.1.0-alpha.1

package/scripts/lib/composition.mjs

@@ -0,0 +1,96 @@
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { validateContract } from "./contracts.mjs";
+
+function canonicalValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalValue(value[key])]));
+  return value;
+}
+
+function equalValue(left, right) {
+  return JSON.stringify(canonicalValue(left)) === JSON.stringify(canonicalValue(right));
+}
+
+export function resolveProfile(input, packManifests = []) {
+  const conflicts = [];
+  const selected = new Map();
+  for (const rule of input.rules ?? []) {
+    const prior = selected.get(rule.id);
+    if (!prior || rule.precedence < prior.precedence) selected.set(rule.id, rule);
+    else if (rule.precedence === prior.precedence && !equalValue(rule.value, prior.value)) {
+      conflicts.push(`${rule.id}: equal-precedence sources disagree (${prior.source} vs ${rule.source})`);
+    }
+  }
+
+  const manifests = new Map(packManifests.map((pack) => [pack.id, pack]));
+  const states = new Map((input.packs ?? []).map((pack) => [pack.id, pack]));
+  const active = new Set([...states.values()].filter((pack) => ["enabled", "required"].includes(pack.state)).map((pack) => pack.id));
+  for (const id of active) {
+    const manifest = manifests.get(id);
+    if (!manifest) {
+      conflicts.push(`${id}: enabled pack manifest is unavailable`);
+      continue;
+    }
+    for (const dependency of manifest.dependencies) if (!active.has(dependency)) conflicts.push(`${id}: missing active dependency ${dependency}`);
+    for (const conflict of manifest.conflicts) if (active.has(conflict)) conflicts.push(`${id}: conflicts with active pack ${conflict}`);
+  }
+  if (active.has("agent-workflow-governance") && active.has("forgerail-core")) conflicts.push("duplicate core workflow owners: agent-workflow-governance and forgerail-core");
+
+  const profile = {
+    schemaVersion: "1.0",
+    workspace: input.workspace,
+    computed: true,
+    rules: [...selected.values()].sort((left, right) => left.id.localeCompare(right.id)),
+    packs: (input.packs ?? []).map((pack) => ({ id: pack.id, state: pack.state, reason: pack.reason })),
+    conflicts: [...new Set(conflicts)].sort(),
+  };
+  const contract = validateContract("profile", profile);
+  return { profile, activePacks: [...active].sort(), valid: contract.valid && profile.conflicts.length === 0, errors: [...contract.errors, ...profile.conflicts] };
+}
+
+export function createLaunchContract(profile, envelope, hostAgent) {
+  const profileResult = validateContract("profile", profile);
+  const envelopeResult = validateContract("envelope", envelope);
+  const errors = [...profileResult.errors, ...envelopeResult.errors];
+  if (profile.conflicts?.length > 0) errors.push(...profile.conflicts.map((conflict) => `unresolved profile conflict: ${conflict}`));
+  const activePacks = new Set((profile.packs ?? []).filter((pack) => ["enabled", "required"].includes(pack.state)).map((pack) => pack.id));
+  for (const pack of envelope.packs ?? []) if (!activePacks.has(pack)) errors.push(`task requests inactive pack: ${pack}`);
+  const launch = {
+    schemaVersion: "1.0",
+    envelope,
+    effectiveRuleSources: [...new Set(["ForgeRail Core", ...(profile.rules ?? []).map((rule) => rule.source)])],
+    hostAgent,
+    executionOwner: "host-agent",
+  };
+  const launchResult = validateContract("launch", launch);
+  errors.push(...launchResult.errors);
+  return { launch, valid: errors.length === 0, errors };
+}
+
+function git(workspace, ...args) {
+  const result = spawnSync("git", args, { cwd: workspace, encoding: "utf8" });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+export function verifyReceipt(receipt, workspace) {
+  const errors = [...validateContract("receipt", receipt).errors];
+  const observations = {};
+  const root = resolve(workspace);
+  const inside = git(root, "rev-parse", "--is-inside-work-tree") === "true";
+  observations.git = inside;
+  if (inside) {
+    observations.branch = git(root, "branch", "--show-current");
+    observations.commit = git(root, "rev-parse", "HEAD");
+    observations.worktree = git(root, "status", "--porcelain=v1") === "" ? "clean" : "dirty";
+    if (receipt.branch !== null && receipt.branch !== observations.branch) errors.push(`receipt branch mismatch: ${receipt.branch} != ${observations.branch}`);
+    if (receipt.commit !== null && receipt.commit !== observations.commit) errors.push(`receipt commit mismatch: ${receipt.commit} != ${observations.commit}`);
+    if (receipt.confirmedNonMutations.includes("clean worktree") && observations.worktree !== "clean") errors.push("receipt claims clean worktree but observable Git state is dirty");
+  } else if (receipt.branch !== null || receipt.commit !== null) errors.push("receipt declares Git identity for a non-Git workspace");
+  return {
+    valid: errors.length === 0,
+    closeout: errors.length === 0 ? receipt.closeout : "incomplete",
+    observations,
+    errors,
+  };
+}

package/scripts/lib/contracts.mjs

@@ -0,0 +1,316 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export const contractTypes = ["pack", "profile", "profile-candidate", "envelope", "launch", "receipt", "host-adapter", "adoption-plan", "binding-receipt"];
+
+const packStates = ["available", "recommended", "enabled", "required", "blocked", "disabled"];
+const idPattern = /^[a-z][a-z0-9-]+$/;
+const ruleIdPattern = /^[a-z][a-z0-9.-]+$/;
+const taskIdPattern = /^[a-zA-Z0-9._:-]+$/;
+const commitPattern = /^[0-9a-f]{40}$/;
+const digestPattern = /^[0-9a-f]{64}$/;
+
+function object(value) {
+  return value && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactKeys(value, required, optional, label, errors) {
+  if (!object(value)) {
+    errors.push(`${label} must be an object`);
+    return false;
+  }
+  for (const key of required) if (!Object.hasOwn(value, key)) errors.push(`${label}.${key} is required`);
+  const allowed = new Set([...required, ...optional]);
+  for (const key of Object.keys(value)) if (!allowed.has(key)) errors.push(`${label}.${key} is unsupported`);
+  return true;
+}
+
+function string(value, label, errors, pattern) {
+  if (typeof value !== "string" || value.length === 0) errors.push(`${label} must be a non-empty string`);
+  else if (pattern && !pattern.test(value)) errors.push(`${label} has an invalid format`);
+}
+
+function nullableString(value, label, errors, pattern) {
+  if (value === null) return;
+  string(value, label, errors, pattern);
+}
+
+function strings(value, label, errors, { min = 0, pattern, unique = false } = {}) {
+  if (!Array.isArray(value)) {
+    errors.push(`${label} must be an array`);
+    return;
+  }
+  if (value.length < min) errors.push(`${label} must contain at least ${min} item(s)`);
+  value.forEach((item, index) => string(item, `${label}[${index}]`, errors, pattern));
+  if (unique && new Set(value).size !== value.length) errors.push(`${label} must not contain duplicates`);
+}
+
+function schemaVersion(value, label, errors) {
+  if (value !== "1.0") errors.push(`${label}.schemaVersion must equal 1.0`);
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function validatePack(value, errors) {
+  const keys = ["schemaVersion", "id", "purpose", "entry", "risk", "states", "triggers", "inputs", "dependencies", "conflicts", "approvals", "validation", "receiptExtensions"];
+  if (!exactKeys(value, keys, [], "pack", errors)) return;
+  schemaVersion(value.schemaVersion, "pack", errors);
+  string(value.id, "pack.id", errors, idPattern);
+  string(value.purpose, "pack.purpose", errors);
+  if (typeof value.purpose === "string" && value.purpose.length < 12) errors.push("pack.purpose is too short");
+  string(value.entry, "pack.entry", errors, /^skills\/[a-z][a-z0-9-]+\/SKILL\.md$/);
+  if (!["low", "medium", "high"].includes(value.risk)) errors.push("pack.risk is invalid");
+  if (JSON.stringify(value.states) !== JSON.stringify(packStates)) errors.push("pack.states must use the canonical ordered state set");
+  strings(value.triggers, "pack.triggers", errors, { unique: true });
+  strings(value.inputs, "pack.inputs", errors, { unique: true });
+  strings(value.dependencies, "pack.dependencies", errors, { pattern: idPattern, unique: true });
+  strings(value.conflicts, "pack.conflicts", errors, { pattern: idPattern, unique: true });
+  strings(value.approvals, "pack.approvals", errors, { pattern: idPattern, unique: true });
+  strings(value.validation, "pack.validation", errors, { unique: true });
+  strings(value.receiptExtensions, "pack.receiptExtensions", errors, { pattern: /^[a-z][A-Za-z0-9]*$/, unique: true });
+}
+
+function validateProfile(value, errors) {
+  if (!exactKeys(value, ["schemaVersion", "workspace", "computed", "rules", "packs", "conflicts"], [], "profile", errors)) return;
+  schemaVersion(value.schemaVersion, "profile", errors);
+  string(value.workspace, "profile.workspace", errors);
+  if (value.computed !== true) errors.push("profile.computed must equal true");
+  if (!Array.isArray(value.rules)) errors.push("profile.rules must be an array");
+  else value.rules.forEach((rule, index) => {
+    const label = `profile.rules[${index}]`;
+    if (!exactKeys(rule, ["id", "value", "source", "precedence", "status"], [], label, errors)) return;
+    string(rule.id, `${label}.id`, errors, ruleIdPattern);
+    string(rule.source, `${label}.source`, errors);
+    if (!Number.isInteger(rule.precedence) || rule.precedence < 1 || rule.precedence > 6) errors.push(`${label}.precedence must be 1-6`);
+    if (!["observed", "inferred", "confirmed", "default"].includes(rule.status)) errors.push(`${label}.status is invalid`);
+  });
+  if (!Array.isArray(value.packs)) errors.push("profile.packs must be an array");
+  else value.packs.forEach((pack, index) => {
+    const label = `profile.packs[${index}]`;
+    if (!exactKeys(pack, ["id", "state", "reason"], [], label, errors)) return;
+    string(pack.id, `${label}.id`, errors, idPattern);
+    if (!packStates.includes(pack.state)) errors.push(`${label}.state is invalid`);
+    string(pack.reason, `${label}.reason`, errors);
+  });
+  strings(value.conflicts, "profile.conflicts", errors);
+  const ids = value.rules?.map((rule) => rule.id) ?? [];
+  if (new Set(ids).size !== ids.length) errors.push("profile.rules contains duplicate ids");
+  const enabled = new Set((value.packs ?? []).filter((item) => ["enabled", "required"].includes(item.state)).map((item) => item.id));
+  for (const pack of value.packs ?? []) {
+    if (!["enabled", "required"].includes(pack.state)) continue;
+    if (pack.id === "agent-workflow-governance" && enabled.has("forgerail-core")) errors.push("profile has duplicate core workflow owners");
+  }
+}
+
+function validateEnvelope(value, errors, label = "envelope") {
+  const keys = ["schemaVersion", "taskId", "intent", "nonGoals", "ownerWorkspace", "allowedOperations", "prohibitedOperations", "packs", "approvalGates", "validation", "returnContract"];
+  if (!exactKeys(value, keys, [], label, errors)) return;
+  schemaVersion(value.schemaVersion, label, errors);
+  string(value.taskId, `${label}.taskId`, errors, taskIdPattern);
+  string(value.intent, `${label}.intent`, errors);
+  strings(value.nonGoals, `${label}.nonGoals`, errors);
+  string(value.ownerWorkspace, `${label}.ownerWorkspace`, errors);
+  strings(value.allowedOperations, `${label}.allowedOperations`, errors, { unique: true });
+  strings(value.prohibitedOperations, `${label}.prohibitedOperations`, errors, { unique: true });
+  strings(value.packs, `${label}.packs`, errors, { pattern: idPattern, unique: true });
+  strings(value.approvalGates, `${label}.approvalGates`, errors, { pattern: idPattern, unique: true });
+  strings(value.validation, `${label}.validation`, errors);
+  if (value.returnContract !== "forgerail-return-receipt-v1") errors.push(`${label}.returnContract is invalid`);
+  const overlap = (value.allowedOperations ?? []).filter((item) => (value.prohibitedOperations ?? []).includes(item));
+  if (overlap.length > 0) errors.push(`${label} allows and prohibits the same operations: ${overlap.join(", ")}`);
+}
+
+function validateProfileCandidate(value, errors) {
+  const keys = ["schemaVersion", "candidateId", "workspace", "ruleId", "proposedValue", "evidence", "targetOwner", "targetSource", "reason", "requiresConfirmation", "status"];
+  if (!exactKeys(value, keys, [], "profileCandidate", errors)) return;
+  schemaVersion(value.schemaVersion, "profileCandidate", errors);
+  string(value.candidateId, "profileCandidate.candidateId", errors, taskIdPattern);
+  string(value.workspace, "profileCandidate.workspace", errors);
+  string(value.ruleId, "profileCandidate.ruleId", errors, ruleIdPattern);
+  strings(value.evidence, "profileCandidate.evidence", errors, { min: 1, unique: true });
+  string(value.targetOwner, "profileCandidate.targetOwner", errors);
+  string(value.targetSource, "profileCandidate.targetSource", errors);
+  string(value.reason, "profileCandidate.reason", errors);
+  if (value.requiresConfirmation !== true) errors.push("profileCandidate.requiresConfirmation must equal true");
+  if (value.status !== "candidate") errors.push("profileCandidate.status must equal candidate");
+}
+
+function validateLaunch(value, errors) {
+  if (!exactKeys(value, ["schemaVersion", "envelope", "effectiveRuleSources", "hostAgent", "executionOwner"], [], "launch", errors)) return;
+  schemaVersion(value.schemaVersion, "launch", errors);
+  validateEnvelope(value.envelope, errors, "launch.envelope");
+  strings(value.effectiveRuleSources, "launch.effectiveRuleSources", errors, { min: 1, unique: true });
+  string(value.hostAgent, "launch.hostAgent", errors);
+  if (value.executionOwner !== "host-agent") errors.push("launch.executionOwner must equal host-agent");
+}
+
+function validateReceipt(value, errors) {
+  const keys = ["schemaVersion", "taskId", "ownerWorkspace", "branch", "commit", "changedScope", "validationEvidence", "externalSideEffects", "confirmedNonMutations", "residualRisks", "rollbackOrRecovery", "deviations", "closeout"];
+  if (!exactKeys(value, keys, [], "receipt", errors)) return;
+  schemaVersion(value.schemaVersion, "receipt", errors);
+  string(value.taskId, "receipt.taskId", errors, taskIdPattern);
+  string(value.ownerWorkspace, "receipt.ownerWorkspace", errors);
+  nullableString(value.branch, "receipt.branch", errors);
+  nullableString(value.commit, "receipt.commit", errors, commitPattern);
+  strings(value.changedScope, "receipt.changedScope", errors);
+  strings(value.validationEvidence, "receipt.validationEvidence", errors, { min: 1 });
+  strings(value.externalSideEffects, "receipt.externalSideEffects", errors);
+  strings(value.confirmedNonMutations, "receipt.confirmedNonMutations", errors);
+  strings(value.residualRisks, "receipt.residualRisks", errors);
+  string(value.rollbackOrRecovery, "receipt.rollbackOrRecovery", errors);
+  strings(value.deviations, "receipt.deviations", errors);
+  if (!["complete", "incomplete", "blocked"].includes(value.closeout)) errors.push("receipt.closeout is invalid");
+  if (value.closeout === "complete" && value.deviations?.length > 0) errors.push("receipt with deviations cannot be complete");
+}
+
+function validateHostAdapter(value, errors) {
+  const keys = ["schemaVersion", "id", "displayName", "status", "instructionDiscovery", "skillDiscovery", "bindingTarget", "bindingModes", "managedMarker", "activationBoundary", "verification", "limitations"];
+  if (!exactKeys(value, keys, [], "hostAdapter", errors)) return;
+  schemaVersion(value.schemaVersion, "hostAdapter", errors);
+  string(value.id, "hostAdapter.id", errors, idPattern);
+  string(value.displayName, "hostAdapter.displayName", errors);
+  if (!["supported", "profile-only"].includes(value.status)) errors.push("hostAdapter.status is invalid");
+  if (!["task-start", "rules", "explicit-only", "unknown"].includes(value.instructionDiscovery)) errors.push("hostAdapter.instructionDiscovery is invalid");
+  if (!["agent-plugin-skills", "agent-skills", "explicit-only", "unknown"].includes(value.skillDiscovery)) errors.push("hostAdapter.skillDiscovery is invalid");
+  string(value.bindingTarget, "hostAdapter.bindingTarget", errors, /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$)).+$/);
+  strings(value.bindingModes, "hostAdapter.bindingModes", errors, { min: 1, unique: true });
+  for (const mode of value.bindingModes ?? []) if (!["managed-block", "thin-reference"].includes(mode)) errors.push(`hostAdapter.bindingModes contains invalid mode: ${mode}`);
+  string(value.managedMarker, "hostAdapter.managedMarker", errors, /^forgerail:binding:[a-z][a-z0-9-]+:v1$/);
+  if (value.managedMarker !== `forgerail:binding:${value.id}:v1`) errors.push("hostAdapter.managedMarker must match hostAdapter.id");
+  if (!["new-task-required", "host-specific-verification-required"].includes(value.activationBoundary)) errors.push("hostAdapter.activationBoundary is invalid");
+  if (exactKeys(value.verification, ["mode", "expectedSkills"], [], "hostAdapter.verification", errors)) {
+    if (!["new-task-discovery", "profile-only"].includes(value.verification.mode)) errors.push("hostAdapter.verification.mode is invalid");
+    strings(value.verification.expectedSkills, "hostAdapter.verification.expectedSkills", errors, { pattern: idPattern, unique: true });
+  }
+  strings(value.limitations, "hostAdapter.limitations", errors, { unique: true });
+  if (value.status === "supported") {
+    if (value.verification?.mode !== "new-task-discovery") errors.push("supported hostAdapter must use new-task-discovery verification");
+    if ((value.verification?.expectedSkills?.length ?? 0) === 0) errors.push("supported hostAdapter must declare expected Skills");
+    if (value.activationBoundary !== "new-task-required") errors.push("supported hostAdapter must require a new task");
+  }
+  if (value.status === "profile-only") {
+    if (value.verification?.mode !== "profile-only") errors.push("profile-only hostAdapter must use profile-only verification");
+    if ((value.verification?.expectedSkills?.length ?? 0) !== 0) errors.push("profile-only hostAdapter cannot claim discovered Skills");
+    if (value.activationBoundary !== "host-specific-verification-required") errors.push("profile-only hostAdapter must require host-specific verification");
+  }
+}
+
+function validateAdoptionPlan(value, errors) {
+  const keys = ["schemaVersion", "planId", "workspace", "currentLevel", "proposedLevel", "strategy", "evidence", "hosts", "proposedWrites", "requiredConfirmation", "verification", "confirmedNonMutations", "mutations", "status"];
+  if (!exactKeys(value, keys, [], "adoptionPlan", errors)) return;
+  schemaVersion(value.schemaVersion, "adoptionPlan", errors);
+  string(value.planId, "adoptionPlan.planId", errors, taskIdPattern);
+  string(value.workspace, "adoptionPlan.workspace", errors);
+  const levels = ["plugin-only", "lightweight-adoption", "persisted-governance"];
+  if (!levels.includes(value.currentLevel)) errors.push("adoptionPlan.currentLevel is invalid");
+  if (!levels.includes(value.proposedLevel)) errors.push("adoptionPlan.proposedLevel is invalid");
+  if (!["no-change", "single-host-managed-block", "shared-contract-with-thin-bindings"].includes(value.strategy)) errors.push("adoptionPlan.strategy is invalid");
+  strings(value.evidence, "adoptionPlan.evidence", errors, { min: 1, unique: true });
+  if (!Array.isArray(value.hosts) || value.hosts.length === 0) errors.push("adoptionPlan.hosts must contain at least one host");
+  else value.hosts.forEach((host, index) => {
+    const label = `adoptionPlan.hosts[${index}]`;
+    if (!exactKeys(host, ["adapterId", "status", "bindingTarget", "verificationMode"], [], label, errors)) return;
+    string(host.adapterId, `${label}.adapterId`, errors, idPattern);
+    if (!["supported", "profile-only"].includes(host.status)) errors.push(`${label}.status is invalid`);
+    string(host.bindingTarget, `${label}.bindingTarget`, errors, /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$)).+$/);
+    if (!["new-task-discovery", "profile-only"].includes(host.verificationMode)) errors.push(`${label}.verificationMode is invalid`);
+    if (host.status === "supported" && host.verificationMode !== "new-task-discovery") errors.push(`${label} supported host must use new-task-discovery`);
+    if (host.status === "profile-only" && host.verificationMode !== "profile-only") errors.push(`${label} profile-only host must not claim verified discovery`);
+  });
+  const hostIds = value.hosts?.map((host) => host.adapterId) ?? [];
+  if (new Set(hostIds).size !== hostIds.length) errors.push("adoptionPlan.hosts contains duplicate adapter ids");
+  if (!Array.isArray(value.proposedWrites)) errors.push("adoptionPlan.proposedWrites must be an array");
+  else value.proposedWrites.forEach((write, index) => {
+    const label = `adoptionPlan.proposedWrites[${index}]`;
+    if (!exactKeys(write, ["path", "operation", "baseSha256", "contentSha256", "content", "managedMarker"], [], label, errors)) return;
+    string(write.path, `${label}.path`, errors, /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$)).+$/);
+    if (!["create", "append-managed-block", "replace-managed-block"].includes(write.operation)) errors.push(`${label}.operation is invalid`);
+    nullableString(write.baseSha256, `${label}.baseSha256`, errors, digestPattern);
+    string(write.contentSha256, `${label}.contentSha256`, errors, digestPattern);
+    string(write.content, `${label}.content`, errors);
+    string(write.managedMarker, `${label}.managedMarker`, errors, /^forgerail:(?:binding:[a-z][a-z0-9-]+|adoption-contract):v1$/);
+    if (typeof write.content === "string" && write.contentSha256 !== sha256(write.content)) errors.push(`${label}.contentSha256 does not match content`);
+    if (typeof write.content === "string" && (!write.content.includes(`<!-- ${write.managedMarker}:start -->`) || !write.content.includes(`<!-- ${write.managedMarker}:end -->`))) errors.push(`${label}.content must contain its complete managed marker`);
+    if (write.operation === "create" && write.baseSha256 !== null) errors.push(`${label}.baseSha256 must be null for create`);
+    if (write.operation !== "create" && !digestPattern.test(write.baseSha256 ?? "")) errors.push(`${label}.baseSha256 is required for managed-block updates`);
+    if (write.path === ".forgerail" || write.path.startsWith(".forgerail/")) errors.push(`${label} cannot target deferred .forgerail state`);
+  });
+  const writePaths = value.proposedWrites?.map((write) => write.path) ?? [];
+  if (new Set(writePaths).size !== writePaths.length) errors.push("adoptionPlan.proposedWrites contains duplicate paths");
+  if (value.requiredConfirmation !== true) errors.push("adoptionPlan.requiredConfirmation must equal true");
+  strings(value.verification, "adoptionPlan.verification", errors, { min: 1, unique: true });
+  strings(value.confirmedNonMutations, "adoptionPlan.confirmedNonMutations", errors, { min: 1, unique: true });
+  if (!Array.isArray(value.mutations) || value.mutations.length !== 0) errors.push("adoptionPlan.mutations must be empty");
+  if (value.status !== "candidate") errors.push("adoptionPlan.status must equal candidate");
+  if (value.strategy === "no-change" && (value.proposedWrites?.length ?? 0) !== 0) errors.push("no-change adoptionPlan cannot propose writes");
+  if (value.strategy === "single-host-managed-block") {
+    if (value.hosts?.length !== 1) errors.push("single-host-managed-block requires exactly one host");
+    if (value.proposedWrites?.length !== 1) errors.push("single-host-managed-block requires exactly one proposed write");
+    if (value.proposedWrites?.[0]?.path !== value.hosts?.[0]?.bindingTarget) errors.push("single-host managed write must target its Host Adapter entry");
+    if (value.proposedWrites?.[0]?.managedMarker !== `forgerail:binding:${value.hosts?.[0]?.adapterId}:v1`) errors.push("single-host managed write marker must match its Host Adapter");
+  }
+  if (value.strategy === "shared-contract-with-thin-bindings") {
+    if ((value.hosts?.length ?? 0) < 2) errors.push("shared-contract-with-thin-bindings requires at least two hosts");
+    if (value.proposedWrites?.length !== (value.hosts?.length ?? 0) + 1) errors.push("shared-contract-with-thin-bindings requires one contract and one write per host");
+    const contract = value.proposedWrites?.find((write) => write.path === "FORGERAIL.md");
+    if (!contract) errors.push("shared-contract-with-thin-bindings must propose FORGERAIL.md");
+    else if (contract.managedMarker !== "forgerail:adoption-contract:v1") errors.push("FORGERAIL.md must use the portable Adoption Contract marker");
+    for (const host of value.hosts ?? []) {
+      const binding = value.proposedWrites?.find((write) => write.path === host.bindingTarget);
+      if (!binding) errors.push(`shared-contract plan is missing host binding: ${host.adapterId}`);
+      else if (binding.managedMarker !== `forgerail:binding:${host.adapterId}:v1`) errors.push(`shared-contract binding marker is invalid: ${host.adapterId}`);
+    }
+  }
+  if (value.proposedLevel === "persisted-governance") errors.push("persisted-governance plan generation is deferred in ForgeRail alpha.1");
+}
+
+function validateBindingReceipt(value, errors) {
+  const keys = ["schemaVersion", "planId", "workspace", "adoptionLevel", "contractPath", "hosts", "changedFiles", "validationEvidence", "discoveredSkills", "activationVerification", "confirmedNonMutations", "deviations", "closeout"];
+  if (!exactKeys(value, keys, [], "bindingReceipt", errors)) return;
+  schemaVersion(value.schemaVersion, "bindingReceipt", errors);
+  string(value.planId, "bindingReceipt.planId", errors, taskIdPattern);
+  string(value.workspace, "bindingReceipt.workspace", errors);
+  if (!["plugin-only", "lightweight-adoption", "persisted-governance"].includes(value.adoptionLevel)) errors.push("bindingReceipt.adoptionLevel is invalid");
+  nullableString(value.contractPath, "bindingReceipt.contractPath", errors);
+  if (!Array.isArray(value.hosts) || value.hosts.length === 0) errors.push("bindingReceipt.hosts must contain at least one host");
+  else value.hosts.forEach((host, index) => {
+    const label = `bindingReceipt.hosts[${index}]`;
+    if (!exactKeys(host, ["adapterId", "target", "baseSha256", "appliedSha256", "status", "verification"], [], label, errors)) return;
+    string(host.adapterId, `${label}.adapterId`, errors, idPattern);
+    string(host.target, `${label}.target`, errors);
+    nullableString(host.baseSha256, `${label}.baseSha256`, errors, digestPattern);
+    string(host.appliedSha256, `${label}.appliedSha256`, errors, digestPattern);
+    if (!["verified", "unverified", "failed"].includes(host.status)) errors.push(`${label}.status is invalid`);
+    strings(host.verification, `${label}.verification`, errors, { min: 1, unique: true });
+  });
+  strings(value.changedFiles, "bindingReceipt.changedFiles", errors, { unique: true });
+  strings(value.validationEvidence, "bindingReceipt.validationEvidence", errors, { min: 1, unique: true });
+  strings(value.discoveredSkills, "bindingReceipt.discoveredSkills", errors, { pattern: idPattern, unique: true });
+  if (exactKeys(value.activationVerification, ["mode", "verified"], [], "bindingReceipt.activationVerification", errors)) {
+    if (!["new-task", "equivalent-supported-discovery", "host-specific"].includes(value.activationVerification.mode)) errors.push("bindingReceipt.activationVerification.mode is invalid");
+    if (typeof value.activationVerification.verified !== "boolean") errors.push("bindingReceipt.activationVerification.verified must be a boolean");
+  }
+  strings(value.confirmedNonMutations, "bindingReceipt.confirmedNonMutations", errors, { min: 1, unique: true });
+  strings(value.deviations, "bindingReceipt.deviations", errors, { unique: true });
+  if (!["complete", "incomplete", "blocked"].includes(value.closeout)) errors.push("bindingReceipt.closeout is invalid");
+  if (value.closeout === "complete") {
+    if (value.activationVerification?.verified !== true) errors.push("complete bindingReceipt requires verified activation discovery");
+    if ((value.hosts ?? []).some((host) => host.status !== "verified")) errors.push("complete bindingReceipt requires every host binding to be verified");
+    if ((value.deviations?.length ?? 0) > 0) errors.push("bindingReceipt with deviations cannot be complete");
+    for (const host of value.hosts ?? []) if (!value.changedFiles?.includes(host.target)) errors.push(`complete bindingReceipt.changedFiles is missing host target: ${host.target}`);
+    if (value.contractPath !== null && !value.changedFiles?.includes(value.contractPath)) errors.push("complete bindingReceipt.changedFiles is missing contractPath");
+  }
+}
+
+export function validateContract(type, payload) {
+  const errors = [];
+  if (!contractTypes.includes(type)) return { valid: false, errors: [`unknown contract type: ${type}`] };
+  ({ pack: validatePack, profile: validateProfile, "profile-candidate": validateProfileCandidate, envelope: validateEnvelope, launch: validateLaunch, receipt: validateReceipt, "host-adapter": validateHostAdapter, "adoption-plan": validateAdoptionPlan, "binding-receipt": validateBindingReceipt })[type](payload, errors);
+  return { valid: errors.length === 0, errors };
+}
+
+export function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}

package/scripts/lib/diagnosis.mjs

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+
+function observed(id, source, value) {
+  return { id, kind: "observed_fact", source, value };
+}
+
+function safeJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+function hasMarkdown(directory) {
+  if (!existsSync(directory) || !statSync(directory).isDirectory()) return false;
+  return readdirSync(directory, { withFileTypes: true }).some((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"));
+}
+
+export function diagnoseWorkspace(workspace) {
+  const root = resolve(workspace);
+  if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error("workspace must be an existing directory");
+  const evidence = [];
+  const recommendations = [];
+  const confirmationRequired = [];
+
+  for (const entry of ["AGENTS.md", "CLAUDE.md", ".cursor/rules/forgerail.mdc", ".github/copilot-instructions.md", "README.md"]) {
+    if (existsSync(resolve(root, entry))) evidence.push(observed(`instructions:${entry}`, entry, "available"));
+  }
+
+  const hostAdapters = [
+    { id: "codex", status: "supported", target: "AGENTS.md", observed: existsSync(resolve(root, "AGENTS.md")) },
+    { id: "claude-code", status: "profile-only", target: "CLAUDE.md", observed: existsSync(resolve(root, "CLAUDE.md")) },
+    { id: "cursor", status: "profile-only", target: ".cursor/rules/forgerail.mdc", observed: existsSync(resolve(root, ".cursor/rules/forgerail.mdc")) },
+  ];
+  const managedBindingObserved = hostAdapters.some((adapter) => {
+    if (!adapter.observed) return false;
+    try { return readFileSync(resolve(root, adapter.target), "utf8").includes(`forgerail:binding:${adapter.id}:v1:start`); } catch { return false; }
+  });
+  const adoptionLevel = existsSync(resolve(root, ".forgerail"))
+    ? "persisted-governance"
+    : existsSync(resolve(root, "FORGERAIL.md")) || managedBindingObserved
+      ? "lightweight-adoption"
+      : "plugin-only";
+  evidence.push(observed("host-adapters", "bounded host instruction paths", hostAdapters));
+  evidence.push(observed("forgerail-adoption-level", "bounded ForgeRail markers", adoptionLevel));
+
+  const recordSystems = [];
+  if (existsSync(resolve(root, "openspec"))) recordSystems.push({ type: "openspec", source: "openspec/" });
+  if (existsSync(resolve(root, ".specify")) || existsSync(resolve(root, "specs"))) recordSystems.push({ type: "spec-kit-or-spec-directory", source: existsSync(resolve(root, ".specify")) ? ".specify/" : "specs/" });
+  for (const directory of ["docs/adr", "docs/adrs", "adr", "adrs", "decisions"]) {
+    if (hasMarkdown(resolve(root, directory))) recordSystems.push({ type: "markdown-adr", source: `${directory}/` });
+  }
+  if (hasMarkdown(resolve(root, "docs")) && recordSystems.length === 0) recordSystems.push({ type: "markdown-docs", source: "docs/" });
+  evidence.push(observed("record-systems", "bounded well-known paths", recordSystems));
+
+  const packageJsonPath = resolve(root, "package.json");
+  const packageJson = existsSync(packageJsonPath) ? safeJson(packageJsonPath) : null;
+  if (packageJson) evidence.push(observed("package-scripts", "package.json", Object.keys(packageJson.scripts ?? {}).sort()));
+
+  if (existsSync(resolve(root, ".git"))) evidence.push(observed("git-root", ".git/", "available"));
+  const skillRoots = [".codex/skills", ".agents/skills"].filter((path) => existsSync(resolve(root, path)));
+  evidence.push(observed("skill-roots", "bounded well-known paths", skillRoots));
+
+  if (recordSystems.length === 0) {
+    recommendations.push({
+      kind: "recommendation",
+      priority: "P1",
+      reason: "No bounded durable record practice was observed for non-trivial engineering work.",
+      options: ["continue with an existing custom documented practice", "use concise Markdown/ADR", "adopt OpenSpec or Spec Kit when structured change tracking is needed"],
+    });
+    confirmationRequired.push("Confirm the durable record target before creating files or installing a record system.");
+  }
+
+  return {
+    schemaVersion: "1.0",
+    mode: "read-only",
+    workspace: basename(root),
+    workspacePath: root,
+    evidence,
+    inheritedHabits: recordSystems,
+    gaps: recordSystems.length === 0 ? ["durable-record-practice-not-observed"] : [],
+    recommendations,
+    confirmationRequired,
+    mutations: [],
+    adoption: {
+      currentLevel: adoptionLevel,
+      recommendedLevel: adoptionLevel,
+      changeRecommended: false,
+      reason: "ForgeRail keeps the minimum observed adoption level unless the user requests durable adoption or concrete evidence justifies escalation.",
+      planCommandAvailable: "forgerail adoption-plan --workspace . --host codex",
+      persistedGovernanceGeneration: "deferred",
+    },
+    fullHealthReviewRecommended: evidence.filter((item) => item.id.startsWith("instructions:")).length > 2,
+  };
+}

package/scripts/shadow-comparison.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const core = readFileSync(resolve(root, "skills/forgerail/SKILL.md"), "utf8");
+const diagnosis = readFileSync(resolve(root, "skills/forgerail-workspace-diagnosis/SKILL.md"), "utf8");
+const health = readFileSync(resolve(root, "skills/workspace-health-review/SKILL.md"), "utf8");
+const frozen = JSON.parse(readFileSync(resolve(root, "docs/agw-frozen-baseline.json"), "utf8"));
+
+function externalSkill(plugin, skill = plugin) {
+  const candidates = [
+    resolve(root, `../${plugin}/skills/${skill}/SKILL.md`),
+    resolve(root, `plugins/${plugin}/skills/${skill}/SKILL.md`),
+  ];
+  const path = candidates.find((candidate) => existsSync(candidate));
+  if (!path) throw new Error(`external Capability Pack entry is missing: ${plugin}`);
+  return readFileSync(path, "utf8");
+}
+
+const rulesets = externalSkill("forgerail-github-rulesets");
+const releaseSafety = externalSkill("forgerail-release-safety");
+const threadClosure = externalSkill("forgerail-thread-closure");
+const agwEvidence = frozen.behaviorAssertions;
+
+const scenarios = [
+  {
+    id: "feature-branch-records",
+    agwEvidence: agwEvidence.featureBranchRecords,
+    forgerailEvidence: ["smallest owner workspace", "Task Envelope", "existing habits"],
+    source: `${agwEvidence.featureBranchRecords.join("\n")}\n${core}\n${diagnosis}`,
+    status: "covered",
+  },
+  {
+    id: "dirty-worktree-preservation",
+    agwEvidence: agwEvidence.dirtyWorktreePreservation,
+    forgerailEvidence: ["preserve unrelated user changes", "dirty-worktree state"],
+    source: `${agwEvidence.dirtyWorktreePreservation.join("\n")}\n${core}`,
+    status: "covered",
+  },
+  {
+    id: "markdown-existing-habit",
+    agwEvidence: agwEvidence.existingRecordHabit,
+    forgerailEvidence: ["existing habits", "OpenSpec may be a preferred example"],
+    source: `${agwEvidence.existingRecordHabit.join("\n")}\n${diagnosis}`,
+    status: "covered",
+  },
+  {
+    id: "workspace-health",
+    agwEvidence: agwEvidence.workspaceHealth,
+    forgerailEvidence: ["first built-in ForgeRail Capability Pack", "Analyze First"],
+    source: `${agwEvidence.workspaceHealth.join("\n")}\n${health}`,
+    status: "covered-with-follow-up",
+  },
+  {
+    id: "github-rulesets-read-first",
+    agwEvidence: agwEvidence.githubRulesets,
+    forgerailEvidence: ["read-only diagnosis", "Stop until the user explicitly approves"],
+    source: `${agwEvidence.githubRulesets.join("\n")}\n${rulesets}`,
+    status: "covered",
+  },
+  {
+    id: "release-safety-project-runbook",
+    agwEvidence: agwEvidence.releaseSafety,
+    forgerailEvidence: ["project-owned release runbook", "does not contain publish, deploy"],
+    source: `${agwEvidence.releaseSafety.join("\n")}\n${releaseSafety}`,
+    status: "covered",
+  },
+  {
+    id: "evidence-first-thread-closure",
+    agwEvidence: agwEvidence.threadClosure,
+    forgerailEvidence: ["Keep closeout incomplete", "Do not implement follow-up work"],
+    source: `${agwEvidence.threadClosure.join("\n")}\n${core}\n${threadClosure}`,
+    status: "covered",
+  },
+];
+
+for (const scenario of scenarios) {
+  scenario.missingAgw = scenario.agwEvidence.filter((phrase) => !scenario.source.toLocaleLowerCase("en-US").includes(phrase.toLocaleLowerCase("en-US")));
+  scenario.missingForgeRail = scenario.forgerailEvidence.filter((phrase) => !scenario.source.toLocaleLowerCase("en-US").includes(phrase.toLocaleLowerCase("en-US")));
+  scenario.passed = scenario.missingAgw.length === 0 && scenario.missingForgeRail.length === 0 && scenario.status !== "unresolved";
+  delete scenario.source;
+}
+
+const result = {
+  schemaVersion: "1.0",
+  agwBaseline: "plugins/agent-workflow-governance@0.2.0-canonical",
+  forgeRailCandidate: "plugins/forgerail@0.1.0-alpha.1-canonical",
+  scenarios,
+  covered: scenarios.filter((item) => item.passed).length,
+  unresolved: scenarios.filter((item) => !item.passed).map((item) => item.id),
+  behaviorCoverageReady: scenarios.every((item) => item.passed),
+  migrationReady: false,
+  migrationBlockers: ["usable ForgeRail prerelease is not published", "real compatibility-period canaries are incomplete", "AGW lifecycle change is not approved"],
+};
+console.log(JSON.stringify(result, null, 2));

package/scripts/validate-external-packs.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pluginParentCandidates = [resolve(root, ".."), resolve(root, "plugins")];
+const pluginParent = pluginParentCandidates.find((candidate) => existsSync(resolve(candidate, "forgerail-github-rulesets/scripts/validate.mjs")));
+if (!pluginParent) {
+  console.error(JSON.stringify({ schemaVersion: "1.0", status: "failed", blocker: "external-capability-pack-layout-not-found" }, null, 2));
+  process.exit(1);
+}
+const entries = [
+  "forgerail-cross-workspace-orchestration/scripts/validate.mjs",
+  "forgerail-github-rulesets/scripts/validate.mjs",
+  "forgerail-release-safety/scripts/validate.mjs",
+  "forgerail-thread-closure/scripts/validate.mjs",
+];
+const results = [];
+for (const entry of entries) {
+  const result = spawnSync(process.execPath, [resolve(pluginParent, entry)], { cwd: root, encoding: "utf8" });
+  results.push({ entry, status: result.status === 0 ? "passed" : "failed", exitCode: result.status, output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim() });
+}
+const report = { schemaVersion: "1.0", status: results.every(({ status }) => status === "passed") ? "passed" : "failed", results };
+console.log(JSON.stringify(report, null, 2));
+if (report.status !== "passed") process.exitCode = 1;