@echopath-labs/forgerail 0.1.0-alpha.1

package/scripts/fixtures/contracts/profile-input.external-rulesets.json

@@ -0,0 +1,11 @@
+{
+  "workspace": "fixture-workspace",
+  "rules": [],
+  "packs": [
+    {
+      "id": "github-rulesets",
+      "state": "enabled",
+      "reason": "The project explicitly enabled the separately installed Rulesets pack."
+    }
+  ]
+}

package/scripts/fixtures/contracts/profile-input.orchestration-available.json

@@ -0,0 +1,11 @@
+{
+  "workspace": "fixture-workspace",
+  "rules": [],
+  "packs": [
+    {
+      "id": "cross-workspace-orchestration",
+      "state": "available",
+      "reason": "Installed for on-demand use; current task has no authoritative enablement."
+    }
+  ]
+}

package/scripts/fixtures/contracts/return-receipt.deviation.invalid.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "1.0",
+  "taskId": "fixture-task-1",
+  "ownerWorkspace": "fixture-workspace",
+  "branch": "feat/fixture",
+  "commit": "1111111111111111111111111111111111111111",
+  "changedScope": ["README.md"],
+  "validationEvidence": ["git diff --check passed"],
+  "externalSideEffects": [],
+  "confirmedNonMutations": ["no release"],
+  "residualRisks": [],
+  "rollbackOrRecovery": "Revert the local documentation commit.",
+  "deviations": ["A prohibited operation was attempted."],
+  "closeout": "complete"
+}

package/scripts/fixtures/contracts/return-receipt.valid.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "1.0",
+  "taskId": "fixture-task-1",
+  "ownerWorkspace": "fixture-workspace",
+  "branch": "feat/fixture",
+  "commit": "1111111111111111111111111111111111111111",
+  "changedScope": ["README.md"],
+  "validationEvidence": ["git diff --check passed"],
+  "externalSideEffects": [],
+  "confirmedNonMutations": ["no push", "no merge", "no release"],
+  "residualRisks": [],
+  "rollbackOrRecovery": "Revert the local documentation commit.",
+  "deviations": [],
+  "closeout": "complete"
+}

package/scripts/fixtures/contracts/task-envelope.overlap.invalid.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": "1.0",
+  "taskId": "fixture-task-overlap",
+  "intent": "Demonstrate fail-closed operation overlap.",
+  "nonGoals": [],
+  "ownerWorkspace": "fixture-workspace",
+  "allowedOperations": ["push"],
+  "prohibitedOperations": ["push"],
+  "packs": [],
+  "approvalGates": [],
+  "validation": ["contract validation"],
+  "returnContract": "forgerail-return-receipt-v1"
+}

package/scripts/fixtures/contracts/task-envelope.valid.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": "1.0",
+  "taskId": "fixture-task-1",
+  "intent": "Update local documentation with ForgeRail guidance.",
+  "nonGoals": ["Publish a release", "Change repository settings"],
+  "ownerWorkspace": "fixture-workspace",
+  "allowedOperations": ["read files", "edit documentation", "run local validation"],
+  "prohibitedOperations": ["push", "merge", "tag", "release", "ruleset mutation"],
+  "packs": [],
+  "approvalGates": ["remote-integration-approval", "release-approval"],
+  "validation": ["documentation links resolve", "git diff --check passes"],
+  "returnContract": "forgerail-return-receipt-v1"
+}

package/scripts/fixtures/workspaces/empty-records/README.md

@@ -0,0 +1,3 @@
+# Empty record fixture
+
+This workspace intentionally has no declared durable engineering record practice.

package/scripts/fixtures/workspaces/markdown-existing/AGENTS.md

@@ -0,0 +1,3 @@
+# Fixture Instructions
+
+Use the existing Markdown ADRs for durable architecture decisions. Do not initialize another specification system.

package/scripts/fixtures/workspaces/markdown-existing/docs/adr/0001-record-strategy.md

@@ -0,0 +1,3 @@
+# ADR 0001: Markdown decisions
+
+This fixture records decisions as Markdown ADRs.

package/scripts/fixtures/workspaces/markdown-existing/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "forgerail-markdown-fixture",
+  "private": true,
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/scripts/forgerail.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadHostAdapters, planAdoption } from "./lib/adoption.mjs";
+import { buildBundle } from "./lib/bundle.mjs";
+import { createLaunchContract, resolveProfile, verifyReceipt } from "./lib/composition.mjs";
+import { contractTypes, readJson, validateContract } from "./lib/contracts.mjs";
+import { diagnoseWorkspace } from "./lib/diagnosis.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function fail(message) { console.error(`forgerail: ${message}`); process.exit(1); }
+function emit(value) { console.log(JSON.stringify(value, null, 2)); }
+function arg(name) { const index = process.argv.indexOf(name); return index >= 0 ? process.argv[index + 1] : undefined; }
+function args(name) {
+  const values = [];
+  process.argv.forEach((value, index) => { if (value === name && process.argv[index + 1]) values.push(process.argv[index + 1]); });
+  return values;
+}
+
+function workspaceSnapshot(path) {
+  return readdirSync(path, { recursive: true })
+    .sort()
+    .map((entry) => {
+      const target = resolve(path, entry);
+      const stat = statSync(target);
+      return stat.isFile() ? `${entry}:file:${createHash("sha256").update(readFileSync(target)).digest("hex")}` : `${entry}:directory`;
+    });
+}
+
+function validatePlugin() {
+  const errors = [];
+  const manifestPath = resolve(root, ".codex-plugin/plugin.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (manifest.name !== "forgerail") errors.push("Plugin name must be forgerail");
+  if (manifest.version !== "0.1.0-alpha.1") errors.push("Plugin version must be 0.1.0-alpha.1");
+  if (manifest.license !== "Apache-2.0") errors.push("Plugin license must be Apache-2.0");
+  const expectedSkills = ["forgerail", "forgerail-workspace-diagnosis", "workspace-health-review"];
+  const actualSkills = readdirSync(resolve(root, "skills"), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  if (JSON.stringify(actualSkills) !== JSON.stringify(expectedSkills)) errors.push(`Expected Skills ${expectedSkills.join(", ")}; received ${actualSkills.join(", ")}`);
+  for (const skill of expectedSkills) {
+    const skillRoot = resolve(root, "skills", skill);
+    const content = readFileSync(resolve(skillRoot, "SKILL.md"), "utf8");
+    const name = content.match(/^---\s*[\s\S]*?^name:\s*([^\n]+)$/m)?.[1]?.trim();
+    if (name !== skill) errors.push(`${skill} frontmatter name is invalid`);
+    if (!existsSync(resolve(skillRoot, "agents/openai.yaml"))) errors.push(`${skill}/agents/openai.yaml is missing`);
+    for (const match of content.matchAll(/`(references\/[a-z0-9._/-]+\.md)`/g)) {
+      if (!existsSync(resolve(skillRoot, match[1]))) errors.push(`${skill} reference is missing: ${match[1]}`);
+    }
+  }
+  for (const type of contractTypes) {
+    const name = { pack: "capability-pack", profile: "effective-profile", "profile-candidate": "profile-change-candidate", envelope: "task-envelope", launch: "launch-contract", receipt: "return-receipt", "host-adapter": "host-adapter", "adoption-plan": "adoption-plan", "binding-receipt": "host-binding-receipt" }[type];
+    JSON.parse(readFileSync(resolve(root, "contracts", `${name}.schema.json`), "utf8"));
+  }
+  const adapterRegistry = loadHostAdapters(root);
+  if (!adapterRegistry.valid) errors.push(...adapterRegistry.errors);
+  const packPath = resolve(root, "packs/workspace-health-review.json");
+  const packResult = validateContract("pack", readJson(packPath));
+  if (!packResult.valid) errors.push(...packResult.errors);
+  const coverage = readJson(resolve(root, "docs/agw-coverage-baseline.json"));
+  const allowedDispositions = new Set(coverage.allowedDispositions);
+  if (new Set(coverage.items.map((item) => item.id)).size !== coverage.items.length) errors.push("AGW coverage contains duplicate ids");
+  for (const item of coverage.items) {
+    if (!allowedDispositions.has(item.target)) errors.push(`AGW coverage target is invalid: ${item.id}`);
+    if (!["mapped", "unresolved"].includes(item.status)) errors.push(`AGW coverage status is invalid: ${item.id}`);
+    if (item.status === "unresolved" && item.target !== "unresolved") errors.push(`AGW unresolved item must target unresolved: ${item.id}`);
+  }
+  if (coverage.migrationReady && coverage.items.some((item) => item.status !== "mapped")) errors.push("AGW migration cannot be ready with unresolved coverage");
+  const contextBytes = Object.fromEntries(actualSkills.map((skill) => [skill, readFileSync(resolve(root, "skills", skill, "SKILL.md")).length]));
+  return { valid: errors.length === 0, errors, skills: actualSkills, contracts: contractTypes, contextBytes };
+}
+
+function validateFixtures() {
+  const fixtureRoot = resolve(root, "scripts/fixtures");
+  const cases = [
+    ["profile", "contracts/effective-profile.valid.json", true],
+    ["profile-candidate", "contracts/profile-change-candidate.valid.json", true],
+    ["envelope", "contracts/task-envelope.valid.json", true],
+    ["envelope", "contracts/task-envelope.overlap.invalid.json", false],
+    ["launch", "contracts/launch-contract.valid.json", true],
+    ["receipt", "contracts/return-receipt.valid.json", true],
+    ["receipt", "contracts/return-receipt.deviation.invalid.json", false],
+    ["host-adapter", "contracts/host-adapter.codex.valid.json", true],
+    ["host-adapter", "contracts/host-adapter.claude-code.profile-only.valid.json", true],
+    ["host-adapter", "contracts/host-adapter.cursor.profile-only.valid.json", true],
+    ["adoption-plan", "contracts/adoption-plan.single-host.valid.json", true],
+    ["adoption-plan", "contracts/adoption-plan.multi-host.valid.json", true],
+    ["adoption-plan", "contracts/adoption-plan.mutating.invalid.json", false],
+    ["binding-receipt", "contracts/host-binding-receipt.valid.json", true],
+    ["binding-receipt", "contracts/host-binding-receipt.unverified.invalid.json", false],
+  ];
+  const results = cases.map(([type, path, expected]) => {
+    const result = validateContract(type, readJson(resolve(fixtureRoot, path)));
+    return { type, path, expected, actual: result.valid, passed: result.valid === expected, errors: result.errors };
+  });
+  for (const workspace of ["markdown-existing", "empty-records"]) {
+    const path = resolve(fixtureRoot, "workspaces", workspace);
+    const before = JSON.stringify(workspaceSnapshot(path));
+    const diagnosis = diagnoseWorkspace(path);
+    const after = JSON.stringify(workspaceSnapshot(path));
+    results.push({ type: "diagnosis", path: relative(fixtureRoot, path), expected: true, actual: diagnosis.mutations.length === 0 && before === after, passed: diagnosis.mutations.length === 0 && before === after, errors: [] });
+  }
+  const manifests = readdirSync(resolve(root, "packs")).filter((name) => name.endsWith(".json")).map((name) => readJson(resolve(root, "packs", name)));
+  const available = resolveProfile(readJson(resolve(fixtureRoot, "contracts/profile-input.available-pack.json")), manifests);
+  results.push({ type: "composition", path: "contracts/profile-input.available-pack.json", expected: true, actual: available.valid && available.activePacks.length === 0 && available.profile.rules[0]?.value === "release", passed: available.valid && available.activePacks.length === 0 && available.profile.rules[0]?.value === "release", errors: available.errors });
+  const conflict = resolveProfile(readJson(resolve(fixtureRoot, "contracts/profile-input.conflict.json")), manifests);
+  results.push({ type: "composition", path: "contracts/profile-input.conflict.json", expected: false, actual: conflict.valid, passed: !conflict.valid && conflict.profile.conflicts.length === 1, errors: conflict.errors });
+  const orchestrationPackCandidates = [
+    resolve(root, "../forgerail-cross-workspace-orchestration/pack.json"),
+    resolve(root, "plugins/forgerail-cross-workspace-orchestration/pack.json"),
+  ];
+  const orchestrationPackPath = orchestrationPackCandidates.find((path) => existsSync(path));
+  if (orchestrationPackPath) {
+    const orchestrationPack = readJson(orchestrationPackPath);
+    const orchestrationPackValidation = validateContract("pack", orchestrationPack);
+    const orchestrationAvailable = resolveProfile(readJson(resolve(fixtureRoot, "contracts/profile-input.orchestration-available.json")), [...manifests, orchestrationPack]);
+    results.push({
+      type: "composition",
+      path: "contracts/profile-input.orchestration-available.json",
+      expected: true,
+      actual: orchestrationPackValidation.valid && orchestrationAvailable.valid && orchestrationAvailable.activePacks.length === 0,
+      passed: orchestrationPackValidation.valid && orchestrationAvailable.valid && orchestrationAvailable.activePacks.length === 0,
+      errors: [...orchestrationPackValidation.errors, ...orchestrationAvailable.errors],
+    });
+  } else results.push({ type: "composition", path: "cross-workspace-orchestration-manifest", expected: true, actual: false, passed: false, errors: ["external orchestration Pack manifest is unavailable"] });
+  const inactiveLaunch = createLaunchContract(available.profile, { ...readJson(resolve(fixtureRoot, "contracts/task-envelope.valid.json")), packs: ["workspace-health-review"] }, "Codex");
+  results.push({ type: "launch", path: "inactive-pack", expected: false, actual: inactiveLaunch.valid, passed: !inactiveLaunch.valid && inactiveLaunch.errors.some((error) => error.includes("inactive pack")), errors: inactiveLaunch.errors });
+  const receipt = readJson(resolve(fixtureRoot, "contracts/return-receipt.valid.json"));
+  const mismatch = verifyReceipt({ ...receipt, branch: "not-the-current-branch", commit: null }, resolve(root, "../.."));
+  results.push({ type: "receipt-observation", path: "observable-git-mismatch", expected: false, actual: mismatch.valid, passed: !mismatch.valid && mismatch.closeout === "incomplete", errors: mismatch.errors });
+  const adoption = validateAdoption();
+  results.push({ type: "adoption", path: "read-only-planner", expected: true, actual: adoption.passed, passed: adoption.passed, errors: adoption.errors });
+  return { passed: results.every((item) => item.passed), results };
+}
+
+function validateAdoption() {
+  const errors = [];
+  const registry = loadHostAdapters(root);
+  if (!registry.valid) errors.push(...registry.errors);
+  const workspace = resolve(root, "scripts/fixtures/workspaces/markdown-existing");
+  const before = JSON.stringify(workspaceSnapshot(workspace));
+  let single;
+  let multi;
+  try {
+    single = planAdoption(root, workspace, ["codex"]);
+    multi = planAdoption(root, workspace, ["codex", "claude-code", "cursor"]);
+  } catch (error) {
+    errors.push(error.message);
+  }
+  const after = JSON.stringify(workspaceSnapshot(workspace));
+  if (before !== after) errors.push("adoption planning mutated its fixture workspace");
+  if (single?.strategy !== "single-host-managed-block" || single?.proposedWrites?.length !== 1 || single?.proposedWrites?.[0]?.path !== "AGENTS.md") errors.push("single-host plan is not a bounded AGENTS.md managed block");
+  if (multi?.strategy !== "shared-contract-with-thin-bindings" || !multi?.proposedWrites?.some((write) => write.path === "FORGERAIL.md")) errors.push("multi-host plan is missing the shared Adoption Contract");
+  if (multi?.hosts?.find((host) => host.adapterId === "claude-code")?.status !== "profile-only" || multi?.hosts?.find((host) => host.adapterId === "cursor")?.status !== "profile-only") errors.push("unverified hosts must remain profile-only");
+  if ([...(single?.proposedWrites ?? []), ...(multi?.proposedWrites ?? [])].some((write) => write.path === ".forgerail" || write.path.startsWith(".forgerail/"))) errors.push("alpha.1 adoption plan cannot propose .forgerail state");
+  try {
+    planAdoption(root, workspace, ["codex"], "persisted-governance");
+    errors.push("persisted-governance planning must be refused in alpha.1");
+  } catch (error) {
+    if (!error.message.includes("evidence-gated")) errors.push(`unexpected persisted-governance error: ${error.message}`);
+  }
+  return { passed: errors.length === 0, errors, adapters: registry.adapters.map(({ id, status }) => ({ id, status })), single, multi };
+}
+
+const [command] = process.argv.slice(2);
+if (command === "validate") {
+  const result = validatePlugin(); emit(result); if (!result.valid) process.exitCode = 1;
+} else if (command === "validate-fixtures") {
+  const result = validateFixtures(); emit(result); if (!result.passed) process.exitCode = 1;
+} else if (command === "validate-adoption") {
+  const result = validateAdoption(); emit(result); if (!result.passed) process.exitCode = 1;
+} else if (command === "validate-contract") {
+  const type = arg("--type"); const file = arg("--file");
+  if (!type || !file) fail("validate-contract requires --type and --file");
+  const result = validateContract(type, readJson(resolve(file))); emit(result); if (!result.valid) process.exitCode = 1;
+} else if (command === "diagnose") {
+  const workspace = arg("--workspace"); if (!workspace) fail("diagnose requires --workspace"); emit(diagnoseWorkspace(workspace));
+} else if (command === "adoption-plan") {
+  const workspace = arg("--workspace"); const hosts = args("--host"); const level = arg("--level") ?? "lightweight-adoption";
+  if (!workspace || hosts.length === 0) fail("adoption-plan requires --workspace and at least one --host");
+  try { emit(planAdoption(root, workspace, hosts, level)); } catch (error) { fail(error.message); }
+} else if (command === "resolve-profile") {
+  const file = arg("--file"); if (!file) fail("resolve-profile requires --file");
+  const manifests = [
+    ...readdirSync(resolve(root, "packs")).filter((name) => name.endsWith(".json")).map((name) => readJson(resolve(root, "packs", name))),
+    ...args("--pack-manifest").map((path) => readJson(resolve(path))),
+  ];
+  for (const manifest of manifests) {
+    const validation = validateContract("pack", manifest);
+    if (!validation.valid) fail(`invalid pack manifest ${manifest.id ?? "unknown"}: ${validation.errors.join("; ")}`);
+  }
+  const result = resolveProfile(readJson(resolve(file)), manifests); emit(result); if (!result.valid) process.exitCode = 1;
+} else if (command === "launch") {
+  const profile = arg("--profile"); const envelope = arg("--envelope"); const hostAgent = arg("--host-agent");
+  if (!profile || !envelope || !hostAgent) fail("launch requires --profile, --envelope, and --host-agent");
+  const profilePayload = readJson(resolve(profile));
+  const effectiveProfile = profilePayload.profile ?? profilePayload;
+  const result = createLaunchContract(effectiveProfile, readJson(resolve(envelope)), hostAgent); emit(result); if (!result.valid) process.exitCode = 1;
+} else if (command === "verify-receipt") {
+  const receipt = arg("--receipt"); const workspace = arg("--workspace");
+  if (!receipt || !workspace) fail("verify-receipt requires --receipt and --workspace");
+  const result = verifyReceipt(readJson(resolve(receipt)), workspace); emit(result); if (!result.valid) process.exitCode = 1;
+} else if (command === "build-bundle") {
+  const output = arg("--output"); if (!output) fail("build-bundle requires --output");
+  const result = buildBundle(root, output);
+  emit(process.argv.includes("--summary") ? { schemaVersion: result.schemaVersion, productId: result.productId, projection: result.projection, fileCount: result.fileCount, totalBytes: result.totalBytes, digest: result.digest, receiptDigest: result.receiptDigest } : result);
+} else fail("usage: forgerail.mjs validate | validate-fixtures | validate-adoption | validate-contract | diagnose | adoption-plan | resolve-profile | launch | verify-receipt | build-bundle");

package/scripts/lib/adoption.mjs

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { validateContract } from "./contracts.mjs";
+
+const levels = ["plugin-only", "lightweight-adoption", "persisted-governance"];
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function read(path) {
+  return readFileSync(path, "utf8");
+}
+
+function adapterFiles(pluginRoot) {
+  return readdirSync(resolve(pluginRoot, "adapters"))
+    .filter((name) => name.endsWith(".json"))
+    .sort();
+}
+
+export function loadHostAdapters(pluginRoot) {
+  const adapters = adapterFiles(pluginRoot).map((name) => JSON.parse(read(resolve(pluginRoot, "adapters", name))));
+  const errors = [];
+  const ids = new Set();
+  for (const adapter of adapters) {
+    const validation = validateContract("host-adapter", adapter);
+    if (!validation.valid) errors.push(...validation.errors.map((error) => `${adapter.id ?? name}: ${error}`));
+    if (ids.has(adapter.id)) errors.push(`duplicate host adapter: ${adapter.id}`);
+    ids.add(adapter.id);
+  }
+  return { valid: errors.length === 0, errors, adapters };
+}
+
+export function observeAdoptionLevel(workspace, adapters = []) {
+  const root = resolve(workspace);
+  if (existsSync(resolve(root, ".forgerail"))) return "persisted-governance";
+  if (existsSync(resolve(root, "FORGERAIL.md"))) return "lightweight-adoption";
+  for (const adapter of adapters) {
+    const target = resolve(root, adapter.bindingTarget);
+    if (existsSync(target) && statSync(target).isFile() && read(target).includes(`<!-- ${adapter.managedMarker}:start -->`)) return "lightweight-adoption";
+  }
+  return "plugin-only";
+}
+
+function templateName(adapterId, strategy) {
+  if (adapterId === "codex") return strategy === "single-host-managed-block" ? "codex-compact.md" : "codex-thin.md";
+  if (adapterId === "claude-code") return "claude-code-thin.md";
+  if (adapterId === "cursor") return "cursor-thin.mdc";
+  throw new Error(`no binding template for host adapter: ${adapterId}`);
+}
+
+function proposedWrite(workspace, path, content, managedMarker) {
+  const target = resolve(workspace, path);
+  const exists = existsSync(target);
+  if (exists && !statSync(target).isFile()) throw new Error(`adoption target is not a file: ${path}`);
+  const prior = exists ? read(target) : null;
+  const start = `<!-- ${managedMarker}:start -->`;
+  const end = `<!-- ${managedMarker}:end -->`;
+  const hasStart = prior?.includes(start) ?? false;
+  const hasEnd = prior?.includes(end) ?? false;
+  if (hasStart !== hasEnd) throw new Error(`adoption target has an incomplete managed marker: ${path}`);
+  if (hasStart && prior.indexOf(start) > prior.indexOf(end)) throw new Error(`adoption target has reversed managed markers: ${path}`);
+  if (hasStart && (prior.match(new RegExp(start.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"))?.length ?? 0) !== 1) throw new Error(`adoption target has duplicate managed markers: ${path}`);
+  if (exists && path === ".cursor/rules/forgerail.mdc" && !hasStart) throw new Error("Cursor binding target already exists without a ForgeRail managed marker");
+  const operation = exists ? (hasStart ? "replace-managed-block" : "append-managed-block") : "create";
+  const approvedContent = operation === "replace-managed-block" && content.indexOf(start) > 0
+    ? `${content.slice(content.indexOf(start), content.indexOf(end) + end.length)}\n`
+    : content;
+  return {
+    path,
+    operation,
+    baseSha256: prior === null ? null : sha256(prior),
+    contentSha256: sha256(approvedContent),
+    content: approvedContent,
+    managedMarker,
+  };
+}
+
+export function renderProposedWrite(workspace, write) {
+  const target = resolve(workspace, write.path);
+  const prior = existsSync(target) ? read(target) : "";
+  if (write.operation === "create") return write.content;
+  if (sha256(prior) !== write.baseSha256) throw new Error(`base digest drifted for ${write.path}`);
+  if (write.operation === "append-managed-block") return `${prior.replace(/\s*$/, "")}\n\n${write.content}`;
+  const start = `<!-- ${write.managedMarker}:start -->`;
+  const end = `<!-- ${write.managedMarker}:end -->`;
+  const startIndex = prior.indexOf(start);
+  const endIndex = prior.indexOf(end, startIndex);
+  if (startIndex < 0 || endIndex < 0) throw new Error(`managed block is missing for ${write.path}`);
+  return `${prior.slice(0, startIndex)}${write.content}${prior.slice(endIndex + end.length)}`;
+}
+
+export function planAdoption(pluginRoot, workspace, hostIds, proposedLevel = "lightweight-adoption") {
+  const root = resolve(workspace);
+  if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error("workspace must be an existing directory");
+  if (!levels.includes(proposedLevel)) throw new Error(`unknown adoption level: ${proposedLevel}`);
+  if (proposedLevel === "persisted-governance") throw new Error("persisted-governance is evidence-gated and deferred in ForgeRail alpha.1");
+  if (!Array.isArray(hostIds) || hostIds.length === 0) throw new Error("at least one explicit --host is required");
+  if (new Set(hostIds).size !== hostIds.length) throw new Error("host selection contains duplicates");
+  const registry = loadHostAdapters(pluginRoot);
+  if (!registry.valid) throw new Error(`host adapter registry is invalid: ${registry.errors.join("; ")}`);
+  const byId = new Map(registry.adapters.map((adapter) => [adapter.id, adapter]));
+  const selected = hostIds.map((id) => {
+    const adapter = byId.get(id);
+    if (!adapter) throw new Error(`unknown host adapter: ${id}`);
+    return adapter;
+  });
+  const currentLevel = observeAdoptionLevel(root, registry.adapters);
+  if (currentLevel !== "plugin-only" && proposedLevel === "plugin-only") throw new Error("adoption removal or downgrade requires a separate reviewed plan and is not generated by alpha.1");
+  if (currentLevel === "persisted-governance") throw new Error("persisted-governance was observed; alpha.1 will diagnose it but will not generate replacement or downgrade writes");
+  const strategy = proposedLevel === "plugin-only" ? "no-change" : selected.length === 1 ? "single-host-managed-block" : "shared-contract-with-thin-bindings";
+  const writes = [];
+  if (strategy === "single-host-managed-block") {
+    const adapter = selected[0];
+    if (!adapter.bindingModes.includes("managed-block")) throw new Error(`${adapter.id} does not support a managed-block binding`);
+    const content = read(resolve(pluginRoot, "templates/bindings", templateName(adapter.id, strategy)));
+    writes.push(proposedWrite(root, adapter.bindingTarget, content, adapter.managedMarker));
+  } else if (strategy === "shared-contract-with-thin-bindings") {
+    const contract = read(resolve(pluginRoot, "templates/FORGERAIL.md")).replace("{{HOSTS}}", selected.map((adapter) => adapter.displayName).join(", "));
+    writes.push(proposedWrite(root, "FORGERAIL.md", contract, "forgerail:adoption-contract:v1"));
+    for (const adapter of selected) {
+      if (!adapter.bindingModes.includes("thin-reference")) throw new Error(`${adapter.id} does not support a thin-reference binding`);
+      const content = read(resolve(pluginRoot, "templates/bindings", templateName(adapter.id, strategy)));
+      writes.push(proposedWrite(root, adapter.bindingTarget, content, adapter.managedMarker));
+    }
+  }
+  const identity = sha256(JSON.stringify({ workspace: basename(root), currentLevel, proposedLevel, strategy, hosts: hostIds, writes: writes.map(({ path, operation, baseSha256, contentSha256 }) => ({ path, operation, baseSha256, contentSha256 })) })).slice(0, 20);
+  const plan = {
+    schemaVersion: "1.0",
+    planId: `adoption:${identity}`,
+    workspace: basename(root),
+    currentLevel,
+    proposedLevel,
+    strategy,
+    evidence: [
+      `Observed current adoption level: ${currentLevel}.`,
+      `User or host Agent explicitly selected host adapters: ${hostIds.join(", ")}.`,
+      "ForgeRail alpha.1 does not generate persisted .forgerail state.",
+    ],
+    hosts: selected.map((adapter) => ({ adapterId: adapter.id, status: adapter.status, bindingTarget: adapter.bindingTarget, verificationMode: adapter.verification.mode })),
+    proposedWrites: writes,
+    requiredConfirmation: true,
+    verification: selected.map((adapter) => adapter.status === "supported"
+      ? `${adapter.displayName}: start a new task in the adopted workspace and verify the binding plus expected Skills are discovered.`
+      : `${adapter.displayName}: profile-only; perform host-specific discovery verification before treating this binding as active.`),
+    confirmedNonMutations: [
+      "The planner did not write workspace files.",
+      "The planner did not create .forgerail/ state.",
+      "The planner did not enable Capability Packs or authorize external side effects.",
+    ],
+    mutations: [],
+    status: "candidate",
+  };
+  const validation = validateContract("adoption-plan", plan);
+  if (!validation.valid) throw new Error(`generated adoption plan is invalid: ${validation.errors.join("; ")}`);
+  return plan;
+}

package/scripts/lib/bundle.mjs

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+
+const roots = [".codex-plugin", ".github", "adapters", "contracts", "docs", "packs", "scripts", "skills", "templates"];
+const files = ["CHANGELOG.md", "CONTRIBUTING.md", "LICENSE", "NOTICE", "PLUGIN.md", "README.md", "README.zh-CN.md", "SECURITY.md", "package.json"];
+const catalog = "marketplace/.agents/plugins/marketplace.json";
+const externalPluginNames = [
+  "forgerail-cross-workspace-orchestration",
+  "forgerail-github-rulesets",
+  "forgerail-release-safety",
+  "forgerail-thread-closure",
+];
+
+function below(base, prefix, result = []) {
+  for (const entry of readdirSync(resolve(base, prefix), { withFileTypes: true })) {
+    const path = `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) below(base, path, result);
+    else if (entry.isFile()) result.push(path);
+    else throw new Error(`unsupported entry: ${path}`);
+  }
+  return result;
+}
+
+export function buildBundle(root, output) {
+  const target = resolve(output);
+  const relativeToTmp = relative("/private/tmp", target);
+  const relativeToSystemTmp = relative("/tmp", target);
+  const safe = (value) => value !== "" && value !== ".." && !value.startsWith(`..${sep}`) && !value.startsWith("/");
+  if (!safe(relativeToTmp) && !safe(relativeToSystemTmp)) throw new Error("output must be a new directory below /private/tmp or /tmp");
+  if (existsSync(target)) throw new Error("output already exists");
+  for (const required of [...roots, ...files, catalog]) if (!existsSync(resolve(root, required))) throw new Error(`public bundle source is missing: ${required}`);
+  const payload = [...files, ...roots.flatMap((prefix) => below(root, prefix))].sort();
+  const externalPlugins = externalPluginNames.map((name) => {
+    const pluginRoot = resolve(root, `../${name}`);
+    if (!existsSync(pluginRoot)) throw new Error(`external Plugin source is missing: ${name}`);
+    return {
+      name,
+      root: pluginRoot,
+      files: below(pluginRoot, ".").map((path) => path.startsWith("./") ? path.slice(2) : path).sort(),
+    };
+  });
+  const inventory = [];
+  const projections = [
+    { source: catalog, target: ".agents/plugins/marketplace.json" },
+    ...payload.flatMap((path) => [
+      { source: path, target: path },
+      { source: path, target: `plugins/forgerail/${path}` },
+    ]),
+    ...externalPlugins.flatMap((plugin) => plugin.files.map((path) => ({
+      source: resolve(plugin.root, path),
+      target: `plugins/${plugin.name}/${path}`,
+      externalSource: `../${plugin.name}/${path}`,
+      absolute: true,
+    }))),
+  ].sort((left, right) => left.target.localeCompare(right.target));
+  for (const { source: path, target: publicPath, externalSource, absolute = false } of projections) {
+    const source = absolute ? path : resolve(root, path);
+    if (!statSync(source).isFile()) throw new Error(`bundle source is not a file: ${path}`);
+    const destination = resolve(target, publicPath);
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(source, destination);
+    const bytes = readFileSync(source);
+    inventory.push({ path: publicPath, source: absolute ? externalSource : path, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") });
+  }
+  const digest = createHash("sha256").update(`${JSON.stringify(inventory)}\n`).digest("hex");
+  return {
+    schemaVersion: "1.0",
+    productId: "forgerail",
+    projection: "marketplace-root-plus-nested-plugin",
+    fileCount: inventory.length,
+    totalBytes: inventory.reduce((sum, item) => sum + item.bytes, 0),
+    digest,
+    receiptDigest: createHash("sha256").update(`forgerail\n${digest}\n${inventory.length}\n`).digest("hex"),
+    files: inventory,
+  };
+}