@echopath-labs/forgerail 0.1.0-alpha.1

package/docs/release.md

@@ -0,0 +1,50 @@
+# ForgeRail 0.1.0-alpha.1 Release Runbook
+
+This is the project-owned runbook for the first usable ForgeRail prerelease. It governs `@echopath-labs/forgerail@0.1.0-alpha.1`, the Git tag `v0.1.0-alpha.1`, and the matching EchoPath Labs Marketplace snapshot. The unscoped `forgerail@0.0.0-reserved.0` remains a reservation and is outside the product release path. This document does not authorize any operation by itself.
+
+## Independent Gates
+
+The gates are independent and non-transitive:
+
+1. `remote_integration_approval` may push one exact signed commit to `release/0.1.0-alpha.1`, open a Draft PR to an exact `main` base, observe Node.js 22 and 24 CI, and return a receipt.
+2. `release_approval` may make that exact PR Ready, merge it by the approved method, publish the exact npm prerelease, create the annotated tag and GitHub prerelease, and verify consumer installation.
+3. `lifecycle_change_approval` is required for any AGW deprecation, redirect, archive, removal, or activation change.
+
+Rulesets, branch protection, stable releases, other products, and OpenSpec archival are outside all three gates unless explicitly added to a new approval.
+
+## Source-First Candidate
+
+- Canonical source is owned in the EchoPath workspace.
+- Public-only fixes are prohibited. Change canonical source, validate it, generate the deterministic projection, and sign an exact source commit, tree, inventory, manifest digest, and projection receipt.
+- The first public candidate must be an ordinary child of the observed public `main`. After remote integration, a source-first replacement on the same release branch must be an ordinary fast-forward successor of the current release head. Push either form by exact SHA refspec without force; keep the PR base and publication comparison baseline bound to the observed `main`.
+- After squash merge, the resulting public `main` tree must equal the final signed projection tree.
+- Open a Draft PR from `release/0.1.0-alpha.1` to the bound `main` SHA. Any head, base, tree, version, license, or check drift stops the gate.
+- Required PR checks are Plugin Contracts on Node.js 22 and 24, including Core/contracts, progressive adoption, external packs, frozen AGW coverage, release-source validation, and disposable consumer lifecycle.
+
+## Release-Approval Execution
+
+Only after a new exact `release_approval`:
+
+1. Confirm the PR remains Open, Draft, mergeable, based on the approved `main`, and at the approved head with all required checks successful.
+2. Mark only that PR Ready and squash-merge it with an exact-head guard. Confirm merged `main` has the signed candidate tree.
+3. From a clean checkout of the merged `main`, run Node.js 22 and 24 validation: `npm test`, `npm run test:shadow`, `npm run test:release`, `npm run test:consumer`, `npm pack --dry-run --json`, and `npm audit`.
+4. Verify npm identity and `@echopath-labs` organization package permission without printing credentials. Confirm `@echopath-labs/forgerail@0.1.0-alpha.1` is absent and record the scoped package's current `latest` and `next` dist-tags. Separately confirm unscoped `forgerail` still contains only `0.0.0-reserved.0` with unchanged reservation tags.
+5. Publish exactly `@echopath-labs/forgerail@0.1.0-alpha.1` with public access and the `next` tag. Keep provenance disabled unless a separately validated trusted-publishing path replaces credential publication. Do not publish product code to unscoped `forgerail`.
+6. Verify registry version, shasum, integrity, license, repository, binary shim, and exact isolated install. Run `forgerail validate` and one bounded read-only diagnosis.
+7. Only after exact-version smoke succeeds, move the scoped package's `latest` to `0.1.0-alpha.1`. Verify exact, scoped `next`, and scoped `latest` isolated installs. Leave every unscoped `forgerail` version and dist-tag unchanged.
+8. Create annotated `v0.1.0-alpha.1` on the exact merged `main` commit and push it without moving any existing tag.
+9. Publish a GitHub prerelease titled `ForgeRail v0.1.0-alpha.1` using the versioned CHANGELOG section. ForgeRail has no standalone binary release assets in this version.
+10. Register the exact tag as a disposable Codex Marketplace, install the main Plugin, start a new Codex task, and verify `$forgerail`, `$forgerail-workspace-diagnosis`, and `$workspace-health-review`. Generate a single-host Codex Adoption Plan, prove planning leaves the workspace unchanged, explicitly approve and apply only its managed block in a disposable project, start another new task or perform the supported equivalent discovery check, and validate a Host Binding Receipt. Confirm no `.forgerail/` state appears. Install and discover each external Capability Pack separately without authenticating or executing it.
+11. Return one durable receipt binding canonical source, public PR/merge, tree, npm package, dist-tags, Git tag, GitHub prerelease, Plugin discovery, checks, non-mutations, and recovery anchors.
+
+## Stop And Rollback
+
+- Before npm publication, stop without remote release mutation when any identity, tree, check, credential, package, or consumer result differs.
+- Do not unpublish or overwrite an immutable npm version. Do not move a published Git tag. Shipped defects require a forward fix and a new version.
+- If exact scoped publication succeeds but consumer smoke fails, a separately approved rollback may remove or move mutable scoped `latest`/`next` to the last verified scoped version. The first scoped prerelease has no earlier scoped runtime version, so the immutable alpha.1 stays published while mutable tags are handled explicitly; never point scoped tags at the unscoped reservation.
+- A PR or merge defect is recovered with an ordinary reviewed revert or forward commit; no force push or history rewrite.
+- AGW remains available during the real compatibility-period canary. This release does not authorize an AGW lifecycle change.
+
+## Required Release Receipt
+
+Record exact repository, branch, PR, approved head/base, merged commit/tree, canonical source and projection digests, Node.js 22 and 24 checks, Host Adapter statuses, adoption non-mutation, Codex Host Binding Receipt, pack metadata, npm identity and immutable package metadata, final dist-tags, annotated tag object and peeled commit, GitHub prerelease identity, disposable Plugin/CLI install results, rollback anchors, and confirmation that no `.forgerail/`, Ruleset, branch-protection, stable-release, AGW lifecycle, or OpenSpec archive mutation occurred.

package/docs/release.zh-CN.md

@@ -0,0 +1,50 @@
+# ForgeRail 0.1.0-alpha.1 发布 Runbook
+
+这是 ForgeRail 首个可用预发布版的项目专属 runbook，约束 `@echopath-labs/forgerail@0.1.0-alpha.1`、Git tag `v0.1.0-alpha.1` 与同一 EchoPath Labs Marketplace 快照。未作用域 `forgerail@0.0.0-reserved.0` 继续只作名称占位，不属于产品发布路径；文档本身不授予任何执行权限。
+
+## 独立审批门
+
+三个审批门互不继承：
+
+1. `remote_integration_approval` 只允许将一个精确签名 commit 推到 `release/0.1.0-alpha.1`，基于精确 `main` 创建 Draft PR，观察 Node.js 22 and 24 CI 并返回 receipt。
+2. `release_approval` 才可把该精确 PR 转 Ready、按批准方式合并、发布精确 npm 预发布版、创建 annotated tag 与 GitHub prerelease，并核验消费者安装。
+3. 任何 AGW 弃用、重定向、归档、删除或激活切换都需要单独的 `lifecycle_change_approval`。
+
+Ruleset、branch protection、稳定版、其他产品与 OpenSpec archive 不在上述授权内，除非新的审批明确加入。
+
+## Source-first 候选
+
+- canonical source 只在 EchoPath 工作区维护；禁止 public-only 修复。
+- 每次修正都要重新校验、确定性投影，并绑定精确 source commit、tree、inventory、manifest digest 与 projection receipt。
+- 首个公共候选必须是已观测 `main` 的普通子 commit。remote integration 后若在同一 release branch 上进行 source-first 替换，新候选必须是当前 release head 的普通 fast-forward successor。两种形式都只能用精确 SHA refspec 推送且不得 force push；PR base 与 publication comparison baseline 继续绑定已观测 `main`。
+- squash merge 后的公共 `main` tree 必须等于最终签名 projection tree。
+- Draft PR 必须绑定精确 base/head；任何 SHA、tree、版本、许可证或 check 漂移都停止。
+- 必须通过 Node.js 22 and 24 Plugin Contracts，包括 Core/contracts、渐进式采用、外部 packs、冻结 AGW 覆盖、发布源校验与一次性消费者生命周期。
+
+## 发布审批后的门序
+
+获得新的精确 `release_approval` 后才执行：
+
+1. 复核 PR 仍为 Open/Draft、可合并、base/head 与批准包一致，required checks 全部成功。
+2. 仅将该 PR 转 Ready，并用 exact-head guard squash merge；确认合并后 `main` tree 等于签名候选 tree。
+3. 在干净的 merged `main` 上用 Node.js 22 和 24 运行 `npm test`、`npm run test:shadow`、`npm run test:release`、`npm run test:consumer`、`npm pack --dry-run --json` 与 `npm audit`。
+4. 不暴露凭据地验证 npm 身份及 `@echopath-labs` 组织 package 权限；确认 scoped alpha.1 尚不存在，并记录 scoped package 的 `latest`、`next`。另行确认未作用域 `forgerail` 仍只有 `0.0.0-reserved.0` 且占位 tags 未变。
+5. 仅以 public access 与 `next` tag 发布 `@echopath-labs/forgerail@0.1.0-alpha.1`；在可信发布链完成独立验证前关闭 provenance。不得向未作用域 `forgerail` 发布产品代码。
+6. 核验 registry version、shasum、integrity、license、repository、binary shim，并执行精确版本隔离安装、`forgerail validate` 与一次有界只读诊断。
+7. 精确版本 smoke 通过后才把 scoped package 的 `latest` 移到 alpha.1；核验 exact、scoped `next`、scoped `latest` 隔离安装，并保持未作用域 `forgerail` 的所有 version/dist-tag 不变。
+8. 在精确 merged `main` 上创建 annotated `v0.1.0-alpha.1` 并推送，不移动任何已有 tag。
+9. 发布标题为 `ForgeRail v0.1.0-alpha.1` 的 GitHub prerelease，release notes 使用版本化 CHANGELOG；此版本没有 standalone binary assets。
+10. 在一次性环境中注册精确 tag Marketplace，安装主插件并启动新 Codex 任务，验证三个主 Skill；生成单宿主 Codex Adoption Plan，证明规划不修改工作区，仅在显式批准后向一次性项目写入 managed block，再启动新任务或执行受支持的等价发现检查，并校验 Host Binding Receipt；确认没有 `.forgerail/` 状态。每个外部 Capability Pack 分别安装与发现，不认证、不执行。
+11. 返回绑定 canonical、PR/merge、tree、npm、dist-tags、tag、prerelease、Plugin discovery、校验、非变更项与恢复锚点的 durable receipt。
+
+## 停止与回滚
+
+- npm 发布前任何身份、tree、check、凭据、package 或消费者结果漂移都立即停止，不产生发布副作用。
+- Do not unpublish 或覆盖不可变 npm version；不得移动已发布 Git tag。发布后缺陷通过新版本前向修复。
+- 若 scoped npm 精确发布成功但消费者 smoke 失败，只有得到单独批准后才可删除或移动 scoped `latest`/`next` 到最近已验证的 scoped 版本。首个 scoped prerelease 没有更早 runtime，immutable alpha.1 必须保留；不得把 scoped tags 指向未作用域占位版本。
+- PR 或 merge 缺陷使用普通 review 后的 revert/forward commit；禁止 force push 与历史重写。
+- 真实兼容期 canary 完成前 AGW 继续可用；本次发布不授权 AGW 生命周期变更。
+
+## 必需 receipt
+
+记录精确 repo、branch、PR、批准 head/base、merged commit/tree、canonical 与投影 digest、Node.js 22/24 checks、Host Adapter 状态、采用规划非变更、Codex Host Binding Receipt、pack metadata、npm 身份及不可变 package metadata、最终 dist-tags、annotated tag object/peeled commit、GitHub prerelease、一次性 Plugin/CLI 安装结果、rollback anchors，并确认没有 `.forgerail/`、Ruleset、branch protection、stable release、AGW lifecycle 或 OpenSpec archive 变更。

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@echopath-labs/forgerail",
+  "version": "0.1.0-alpha.1",
+  "description": "Deterministic validation and diagnosis CLI for the ForgeRail Agent Plugin.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "forgerail": "scripts/forgerail.mjs"
+  },
+  "files": [
+    ".codex-plugin/",
+    "adapters/",
+    "contracts/",
+    "docs/",
+    "marketplace/",
+    "packs/",
+    "scripts/",
+    "skills/",
+    "templates/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "NOTICE",
+    "PLUGIN.md",
+    "README.md",
+    "README.zh-CN.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node scripts/forgerail.mjs validate && node scripts/forgerail.mjs validate-fixtures && node scripts/forgerail.mjs validate-adoption",
+    "test:consumer": "node scripts/disposable-consumer.mjs",
+    "test:release": "node scripts/validate-release.mjs",
+    "test:shadow": "node scripts/shadow-comparison.mjs",
+    "diagnose:fixture": "node scripts/forgerail.mjs diagnose --workspace scripts/fixtures/workspaces/markdown-existing",
+    "prepublishOnly": "npm test && npm run test:shadow && npm run test:release && npm run test:consumer"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/echopath-labs/forgerail.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}

package/packs/workspace-health-review.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "1.0",
+  "id": "workspace-health-review",
+  "purpose": "Audit workspace governance, drift, context debt, ownership, and recovery health without executing implementation work.",
+  "entry": "skills/workspace-health-review/SKILL.md",
+  "risk": "low",
+  "states": ["available", "recommended", "enabled", "required", "blocked", "disabled"],
+  "triggers": ["explicit workspace health request", "pre-refactor governance audit", "pre-release governance audit", "recovery difficulty"],
+  "inputs": ["workspace boundary evidence", "agent instructions", "durable record inventory", "skill inventory", "recovery entries"],
+  "dependencies": [],
+  "conflicts": [],
+  "approvals": ["durable-write-approval"],
+  "validation": ["report separates observations from proposed modifications", "no mutation occurs in Analyze First mode"],
+  "receiptExtensions": ["healthStatus", "contextDebt", "recoveryRisks"]
+}

package/scripts/disposable-consumer.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const base = mkdtempSync(resolve(tmpdir(), "forgerail-consumer-"));
+const cache = resolve(base, "npm-cache");
+const consumer = resolve(base, "consumer");
+const target = resolve(base, "target-workspace");
+const priorSource = resolve(base, "prior-source");
+const packageName = "@echopath-labs/forgerail";
+const installedPackageRoot = resolve(consumer, "node_modules", "@echopath-labs", "forgerail");
+mkdirSync(consumer, { recursive: true });
+mkdirSync(resolve(target, "docs/adr"), { recursive: true });
+writeFileSync(resolve(consumer, "package.json"), `${JSON.stringify({ name: "forgerail-disposable-consumer", private: true }, null, 2)}\n`);
+writeFileSync(resolve(target, "AGENTS.md"), "# Target\n\nUse the existing Markdown ADRs.\n");
+writeFileSync(resolve(target, "docs/adr/0001.md"), "# ADR 0001\n\nUse Markdown decisions.\n");
+cpSync(root, priorSource, { recursive: true });
+const priorManifest = JSON.parse(readFileSync(resolve(priorSource, "package.json"), "utf8"));
+priorManifest.version = "0.1.0-alpha.0";
+writeFileSync(resolve(priorSource, "package.json"), `${JSON.stringify(priorManifest, null, 2)}\n`);
+const priorPlugin = JSON.parse(readFileSync(resolve(priorSource, ".codex-plugin/plugin.json"), "utf8"));
+priorPlugin.version = "0.1.0-alpha.0";
+writeFileSync(resolve(priorSource, ".codex-plugin/plugin.json"), `${JSON.stringify(priorPlugin, null, 2)}\n`);
+
+function run(command, args, cwd = consumer) {
+  const result = spawnSync(command, args, { cwd, encoding: "utf8", env: { ...process.env, npm_config_cache: cache }, maxBuffer: 16 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed: ${(result.stderr || result.stdout).trim()}`);
+  return result.stdout.trim();
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function snapshot(path) {
+  return readdirSync(path, { recursive: true })
+    .sort()
+    .map((entry) => {
+      const target = resolve(path, entry);
+      const stat = statSync(target);
+      return stat.isFile() ? `${entry}:file:${sha256(readFileSync(target))}` : `${entry}:directory`;
+    });
+}
+
+function renderApprovedWrite(write) {
+  const targetPath = resolve(target, write.path);
+  const prior = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+  if (write.operation === "create") return write.content;
+  if (sha256(prior) !== write.baseSha256) throw new Error(`adoption 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(`adoption managed block is missing for ${write.path}`);
+  return `${prior.slice(0, startIndex)}${write.content}${prior.slice(endIndex + end.length)}`;
+}
+
+const priorPack = JSON.parse(run("npm", ["pack", priorSource, "--json"], base))[0];
+const priorTarball = resolve(base, priorPack.filename);
+run("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", priorTarball]);
+const priorInstalled = JSON.parse(readFileSync(resolve(installedPackageRoot, "package.json"), "utf8")).version === "0.1.0-alpha.0";
+const pack = JSON.parse(run("npm", ["pack", root, "--json"], base))[0];
+const tarball = resolve(base, pack.filename);
+run("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", tarball]);
+const cli = resolve(consumer, "node_modules/.bin/forgerail");
+const firstValidation = JSON.parse(run(cli, ["validate"]));
+const before = JSON.stringify(snapshot(target));
+const diagnosis = JSON.parse(run(cli, ["diagnose", "--workspace", target]));
+const after = JSON.stringify(snapshot(target));
+const adoptionPlan = JSON.parse(run(cli, ["adoption-plan", "--workspace", target, "--host", "codex"]));
+const afterPlan = JSON.stringify(snapshot(target));
+const proposed = adoptionPlan.proposedWrites[0];
+const approvedContent = renderApprovedWrite(proposed);
+writeFileSync(resolve(target, proposed.path), approvedContent);
+const approvedDigest = sha256(approvedContent);
+const discoveredSkills = firstValidation.skills;
+const bindingReceipt = {
+  schemaVersion: "1.0",
+  planId: adoptionPlan.planId,
+  workspace: adoptionPlan.workspace,
+  adoptionLevel: "lightweight-adoption",
+  contractPath: null,
+  hosts: [{
+    adapterId: "codex",
+    target: proposed.path,
+    baseSha256: proposed.baseSha256,
+    appliedSha256: approvedDigest,
+    status: "verified",
+    verification: ["Equivalent supported discovery read the approved managed block and the installed Plugin Skill inventory from the disposable package."],
+  }],
+  changedFiles: [proposed.path],
+  validationEvidence: ["Applied managed content and exact base digest matched the approved Adoption Plan."],
+  discoveredSkills,
+  activationVerification: { mode: "equivalent-supported-discovery", verified: approvedContent.includes("forgerail:binding:codex:v1:start") && discoveredSkills.includes("forgerail") },
+  confirmedNonMutations: ["No .forgerail directory was created.", "No Capability Pack was enabled or executed."],
+  deviations: [],
+  closeout: "complete",
+};
+const receiptPath = resolve(base, "host-binding-receipt.json");
+writeFileSync(receiptPath, `${JSON.stringify(bindingReceipt, null, 2)}\n`);
+const receiptValidation = JSON.parse(run(cli, ["validate-contract", "--type", "binding-receipt", "--file", receiptPath]));
+const launch = JSON.parse(run(cli, ["launch", "--profile", resolve(root, "scripts/fixtures/contracts/effective-profile.valid.json"), "--envelope", resolve(root, "scripts/fixtures/contracts/task-envelope.valid.json"), "--host-agent", "Codex"]));
+const upgraded = JSON.parse(readFileSync(resolve(installedPackageRoot, "package.json"), "utf8")).version === pack.version;
+run("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", priorTarball]);
+const rolledBack = JSON.parse(readFileSync(resolve(installedPackageRoot, "package.json"), "utf8")).version === "0.1.0-alpha.0";
+run("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", tarball]);
+const reinstallValidation = JSON.parse(run(cli, ["validate"]));
+run("npm", ["uninstall", "--no-audit", "--no-fund", packageName]);
+
+const result = {
+  schemaVersion: "1.0",
+  packageName,
+  sourceVersion: pack.version,
+  tarball: { files: pack.entryCount, bytes: pack.size, shasum: pack.shasum, integrity: pack.integrity },
+  install: firstValidation.valid,
+  binaryShim: cli.endsWith("node_modules/.bin/forgerail"),
+  priorInstall: priorInstalled,
+  discovery: firstValidation.skills,
+  diagnosis: diagnosis.mode === "read-only" && diagnosis.recommendations.length === 0 && diagnosis.adoption.currentLevel === "plugin-only",
+  targetUnchangedByDiagnosis: before === after,
+  adoptionPlan: adoptionPlan.strategy === "single-host-managed-block" && adoptionPlan.requiredConfirmation && adoptionPlan.mutations.length === 0 && proposed.path === "AGENTS.md",
+  targetUnchangedByPlanner: after === afterPlan,
+  explicitApprovedWrite: approvedDigest === sha256(approvedContent) && approvedContent.includes("forgerail:binding:codex:v1:start"),
+  equivalentNewTaskDiscovery: bindingReceipt.activationVerification.verified && discoveredSkills.length === 3,
+  bindingReceipt: receiptValidation.valid,
+  noPersistedGovernance: !existsSync(resolve(target, ".forgerail")),
+  launch: launch.valid && launch.launch.executionOwner === "host-agent",
+  reinstall: reinstallValidation.valid,
+  upgrade: upgraded,
+  rollback: rolledBack,
+  uninstall: !existsSync(installedPackageRoot),
+  disposableRoot: "[disposable]",
+};
+result.passed = result.priorInstall && result.install && result.binaryShim && result.diagnosis && result.targetUnchangedByDiagnosis && result.adoptionPlan && result.targetUnchangedByPlanner && result.explicitApprovedWrite && result.equivalentNewTaskDiscovery && result.bindingReceipt && result.noPersistedGovernance && result.launch && result.upgrade && result.rollback && result.reinstall && result.uninstall;
+console.log(JSON.stringify(result, null, 2));
+if (!result.passed) process.exitCode = 1;

package/scripts/fixtures/contracts/adoption-plan.multi-host.valid.json

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": "1.0",
+  "planId": "adoption:multi-host",
+  "workspace": "fixture",
+  "currentLevel": "plugin-only",
+  "proposedLevel": "lightweight-adoption",
+  "strategy": "shared-contract-with-thin-bindings",
+  "evidence": ["Codex and Claude Code were explicitly selected."],
+  "hosts": [
+    { "adapterId": "codex", "status": "supported", "bindingTarget": "AGENTS.md", "verificationMode": "new-task-discovery" },
+    { "adapterId": "claude-code", "status": "profile-only", "bindingTarget": "CLAUDE.md", "verificationMode": "profile-only" }
+  ],
+  "proposedWrites": [
+    {
+      "path": "FORGERAIL.md",
+      "operation": "create",
+      "baseSha256": null,
+      "contentSha256": "ebba8da7ae587252193419a647f0d8e6898074899158b4f441df573351c9de7c",
+      "content": "<!-- forgerail:adoption-contract:v1:start -->\nShared contract.\n<!-- forgerail:adoption-contract:v1:end -->\n",
+      "managedMarker": "forgerail:adoption-contract:v1"
+    },
+    {
+      "path": "AGENTS.md",
+      "operation": "create",
+      "baseSha256": null,
+      "contentSha256": "989f89220b826a5f355083497552db142fcf1f19cd299febf22b037494c71645",
+      "content": "<!-- forgerail:binding:codex:v1:start -->\nRead FORGERAIL.md.\n<!-- forgerail:binding:codex:v1:end -->\n",
+      "managedMarker": "forgerail:binding:codex:v1"
+    },
+    {
+      "path": "CLAUDE.md",
+      "operation": "create",
+      "baseSha256": null,
+      "contentSha256": "e72fdc3bd532202c2b9c52095e8e20050d428a150285c3b4f1cfce040d3a481c",
+      "content": "<!-- forgerail:binding:claude-code:v1:start -->\nRead FORGERAIL.md.\n<!-- forgerail:binding:claude-code:v1:end -->\n",
+      "managedMarker": "forgerail:binding:claude-code:v1"
+    }
+  ],
+  "requiredConfirmation": true,
+  "verification": ["Verify Codex in a new task.", "Verify Claude Code before claiming activation."],
+  "confirmedNonMutations": ["No files were written."],
+  "mutations": [],
+  "status": "candidate"
+}

package/scripts/fixtures/contracts/adoption-plan.mutating.invalid.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "1.0",
+  "planId": "adoption:invalid",
+  "workspace": "fixture",
+  "currentLevel": "plugin-only",
+  "proposedLevel": "lightweight-adoption",
+  "strategy": "single-host-managed-block",
+  "evidence": ["Codex was selected."],
+  "hosts": [
+    { "adapterId": "codex", "status": "supported", "bindingTarget": "AGENTS.md", "verificationMode": "new-task-discovery" }
+  ],
+  "proposedWrites": [],
+  "requiredConfirmation": true,
+  "verification": ["Start a new task."],
+  "confirmedNonMutations": ["No files should be written."],
+  "mutations": ["AGENTS.md written without confirmation"],
+  "status": "candidate"
+}

package/scripts/fixtures/contracts/adoption-plan.single-host.valid.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": "1.0",
+  "planId": "adoption:codex-single",
+  "workspace": "fixture",
+  "currentLevel": "plugin-only",
+  "proposedLevel": "lightweight-adoption",
+  "strategy": "single-host-managed-block",
+  "evidence": ["Codex was explicitly selected."],
+  "hosts": [
+    { "adapterId": "codex", "status": "supported", "bindingTarget": "AGENTS.md", "verificationMode": "new-task-discovery" }
+  ],
+  "proposedWrites": [
+    {
+      "path": "AGENTS.md",
+      "operation": "create",
+      "baseSha256": null,
+      "contentSha256": "0bccefea0979ec3ad7b80555d1da43a793ab710417b9d4541aa2a15be9ad0810",
+      "content": "<!-- forgerail:binding:codex:v1:start -->\nUse ForgeRail.\n<!-- forgerail:binding:codex:v1:end -->\n",
+      "managedMarker": "forgerail:binding:codex:v1"
+    }
+  ],
+  "requiredConfirmation": true,
+  "verification": ["Start a new Codex task."],
+  "confirmedNonMutations": ["No files were written."],
+  "mutations": [],
+  "status": "candidate"
+}

package/scripts/fixtures/contracts/effective-profile.valid.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "1.0",
+  "workspace": "fixture-workspace",
+  "computed": true,
+  "rules": [
+    {
+      "id": "git.primary-branch",
+      "value": "main",
+      "source": "repository metadata",
+      "precedence": 1,
+      "status": "observed"
+    },
+    {
+      "id": "records.strategy",
+      "value": "markdown-adr",
+      "source": "docs/adr/",
+      "precedence": 5,
+      "status": "observed"
+    }
+  ],
+  "packs": [
+    {
+      "id": "workspace-health-review",
+      "state": "available",
+      "reason": "Installed with ForgeRail but not required for this task."
+    }
+  ],
+  "conflicts": []
+}

package/scripts/fixtures/contracts/host-adapter.claude-code.profile-only.valid.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "1.0",
+  "id": "claude-code",
+  "displayName": "Claude Code",
+  "status": "profile-only",
+  "instructionDiscovery": "task-start",
+  "skillDiscovery": "agent-skills",
+  "bindingTarget": "CLAUDE.md",
+  "bindingModes": ["managed-block", "thin-reference"],
+  "managedMarker": "forgerail:binding:claude-code:v1",
+  "activationBoundary": "host-specific-verification-required",
+  "verification": { "mode": "profile-only", "expectedSkills": [] },
+  "limitations": ["End-to-end activation has not been verified for alpha.1."]
+}

package/scripts/fixtures/contracts/host-adapter.codex.valid.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "1.0",
+  "id": "codex",
+  "displayName": "Codex",
+  "status": "supported",
+  "instructionDiscovery": "task-start",
+  "skillDiscovery": "agent-plugin-skills",
+  "bindingTarget": "AGENTS.md",
+  "bindingModes": ["managed-block", "thin-reference"],
+  "managedMarker": "forgerail:binding:codex:v1",
+  "activationBoundary": "new-task-required",
+  "verification": {
+    "mode": "new-task-discovery",
+    "expectedSkills": ["forgerail", "forgerail-workspace-diagnosis", "workspace-health-review"]
+  },
+  "limitations": ["A new task is required after adoption."]
+}

package/scripts/fixtures/contracts/host-adapter.cursor.profile-only.valid.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "1.0",
+  "id": "cursor",
+  "displayName": "Cursor",
+  "status": "profile-only",
+  "instructionDiscovery": "rules",
+  "skillDiscovery": "unknown",
+  "bindingTarget": ".cursor/rules/forgerail.mdc",
+  "bindingModes": ["thin-reference"],
+  "managedMarker": "forgerail:binding:cursor:v1",
+  "activationBoundary": "host-specific-verification-required",
+  "verification": { "mode": "profile-only", "expectedSkills": [] },
+  "limitations": ["End-to-end activation has not been verified for alpha.1."]
+}

package/scripts/fixtures/contracts/host-binding-receipt.unverified.invalid.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": "1.0",
+  "planId": "adoption:codex-single",
+  "workspace": "fixture",
+  "adoptionLevel": "lightweight-adoption",
+  "contractPath": null,
+  "hosts": [
+    {
+      "adapterId": "codex",
+      "target": "AGENTS.md",
+      "baseSha256": null,
+      "appliedSha256": "0bccefea0979ec3ad7b80555d1da43a793ab710417b9d4541aa2a15be9ad0810",
+      "status": "unverified",
+      "verification": ["No new Codex task was started."]
+    }
+  ],
+  "changedFiles": ["AGENTS.md"],
+  "validationEvidence": ["The file digest matched."],
+  "discoveredSkills": [],
+  "activationVerification": {
+    "mode": "new-task",
+    "verified": false
+  },
+  "confirmedNonMutations": ["No .forgerail directory was created."],
+  "deviations": [],
+  "closeout": "complete"
+}

package/scripts/fixtures/contracts/host-binding-receipt.valid.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": "1.0",
+  "planId": "adoption:codex-single",
+  "workspace": "fixture",
+  "adoptionLevel": "lightweight-adoption",
+  "contractPath": null,
+  "hosts": [
+    {
+      "adapterId": "codex",
+      "target": "AGENTS.md",
+      "baseSha256": null,
+      "appliedSha256": "0bccefea0979ec3ad7b80555d1da43a793ab710417b9d4541aa2a15be9ad0810",
+      "status": "verified",
+      "verification": ["A new Codex task discovered the binding and expected Skills."]
+    }
+  ],
+  "changedFiles": ["AGENTS.md"],
+  "validationEvidence": ["Applied content digest matched the approved Adoption Plan."],
+  "discoveredSkills": ["forgerail", "forgerail-workspace-diagnosis", "workspace-health-review"],
+  "activationVerification": {
+    "mode": "new-task",
+    "verified": true
+  },
+  "confirmedNonMutations": ["No .forgerail directory was created."],
+  "deviations": [],
+  "closeout": "complete"
+}

package/scripts/fixtures/contracts/launch-contract.valid.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "1.0",
+  "envelope": {
+    "schemaVersion": "1.0",
+    "taskId": "fixture-task-1",
+    "intent": "Update local documentation with ForgeRail guidance.",
+    "nonGoals": ["Publish a release"],
+    "ownerWorkspace": "fixture-workspace",
+    "allowedOperations": ["read files", "edit documentation", "run local validation"],
+    "prohibitedOperations": ["push", "merge", "tag", "release"],
+    "packs": [],
+    "approvalGates": ["remote-integration-approval", "release-approval"],
+    "validation": ["git diff --check passes"],
+    "returnContract": "forgerail-return-receipt-v1"
+  },
+  "effectiveRuleSources": ["AGENTS.md", "ForgeRail Core"],
+  "hostAgent": "Codex",
+  "executionOwner": "host-agent"
+}

package/scripts/fixtures/contracts/profile-change-candidate.valid.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": "1.0",
+  "candidateId": "candidate:fixture-validation-rule",
+  "workspace": "fixture-workspace",
+  "ruleId": "validation.docs-links",
+  "proposedValue": "run documentation link validation after navigation changes",
+  "evidence": ["three completed tasks required the same missing link check"],
+  "targetOwner": "fixture-workspace",
+  "targetSource": "AGENTS.md",
+  "reason": "The repeated validation requirement should become an explicit project rule.",
+  "requiresConfirmation": true,
+  "status": "candidate"
+}

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

@@ -0,0 +1,26 @@
+{
+  "workspace": "fixture-workspace",
+  "rules": [
+    {
+      "id": "git.primary-branch",
+      "value": "main",
+      "source": "ForgeRail portable default",
+      "precedence": 6,
+      "status": "default"
+    },
+    {
+      "id": "git.primary-branch",
+      "value": "release",
+      "source": "AGENTS.md",
+      "precedence": 2,
+      "status": "confirmed"
+    }
+  ],
+  "packs": [
+    {
+      "id": "workspace-health-review",
+      "state": "available",
+      "reason": "Installed but irrelevant to the current task."
+    }
+  ]
+}

package/scripts/fixtures/contracts/profile-input.conflict.json

@@ -0,0 +1,20 @@
+{
+  "workspace": "fixture-workspace",
+  "rules": [
+    {
+      "id": "release.test-branch",
+      "value": "release",
+      "source": "AGENTS.md",
+      "precedence": 2,
+      "status": "confirmed"
+    },
+    {
+      "id": "release.test-branch",
+      "value": "develop",
+      "source": "docs/release.md",
+      "precedence": 2,
+      "status": "confirmed"
+    }
+  ],
+  "packs": []
+}