@echopath-labs/forgerail 0.1.0-alpha.2 → 0.1.0-alpha.4

package/docs/release-alpha4.md

@@ -0,0 +1,33 @@
+# ForgeRail 0.1.0-alpha.4 Integrity Runbook
+
+This source-first runbook governs the proposed `@echopath-labs/forgerail@0.1.0-alpha.4`, tag `v0.1.0-alpha.4`, and matching Agent Plugin projection. It does not grant `remote_integration_approval`, `release_approval`, `submission_approval`, `rollback_approval`, or `lifecycle_change_approval`. The unscoped `forgerail@0.0.0-reserved.0` remains a reservation and must never receive product code or serve as an install or rollback source.
+
+## Candidate integration
+
+The public candidate is an ordinary child of the observed remote `main`. The observed base is exactly `e8fa29cd9f0f782d423d2fdd8abd778fbd362d61`. A future exact `remote_integration_approval` may push only the signed commit to `codex/forgerail-alpha4-critical-integrity`, create one Draft PR, and observe Node.js 22 and 24 Plugin Contracts CI. The Draft PR base and publication comparison baseline remain bound to the observed remote `main`.
+
+Any correction is an ordinary source-first successor commit. Do not force push, rewrite the candidate, transition the PR to Ready, merge, tag, publish, or create a release under remote-integration authority. Install and discover each external Capability Pack separately; availability never implies authentication, enablement, or mutation authority.
+
+## Integrity and compatibility proof
+
+Run Core, integrity regressions, Shadow comparison, release source, Directory, disposable consumer and external Pack validation. Alpha.3 Profiles, Packs, Task Envelopes and Return Receipts that remain valid under the explicit alpha.4 constraints must continue to pass. Launch Contracts and Adoption Plans are intentionally tightened and require regeneration before alpha.4 validation. Invalid identifiers, dates, paths, duplicate identities, missing required Packs, malformed receipts, escaped adoption targets, unsafe bundle sources and inconsistent orchestration events must fail closed.
+
+Each proposed Adoption write carries an `approvalSha256` over its canonical workspace identity and complete executable metadata: path, operation, base digest, content digest, content and managed marker. An integration must preserve the human-approved digest separately from the mutable proposal and provide it when applying the write; ForgeRail validates one immutable field snapshot, rejects every operation except `create`, `append-managed-block`, or `replace-managed-block`, and therefore fails workspace replay, accessor drift, unsupported-operation replay, or ordinary metadata drift before destination mutation. Replacing an existing managed binding uses a same-directory atomic rename while retaining a recovery hard link, so the target path is never deliberately absent and a missing installed leaf can be restored without masking the original failure. Four-digit contract years, including `0000` through `0099`, are interpreted literally rather than through JavaScript's legacy 1900 offset.
+
+An existing managed binding is replaceable only when its opening and closing boundary markers each occur exactly once and in the expected order. Incomplete, reversed, duplicate-opening, or duplicate-closing structures fail before a proposal is generated and remain untouched.
+
+The intentional alpha.3 compatibility tightenings are explicit: contract identifiers now require at least two characters and a leading alphanumeric character; every Launch Contract requires the validated `effectiveProfile` digest plus canonical identities for its active Pack manifests, while workspace identity appears only once at `envelope.ownerWorkspace`; its resolved `envelope.packs` is an identity-to-manifest-digest map so every requested Pack is schema-native and self-bound; Effective Profile `packs` is an identity-keyed object rather than an array, so alpha.3 Profiles must be regenerated; every required active Pack must have an available manifest and be included by the task envelope; Adoption paths must use canonical portable segments and every write in one plan must bind the same workspace identity. Launch construction sorts copies rather than mutating Task Envelope inputs, and projection directory deny lists are case-insensitive. These are fail-closed corrections, not silent compatibility regressions.
+
+The source-repository projection builder is a maintainer tool and must not enter the npm package or public CLI. Public projection requires an explicit array-valued `package.json.files` publication allowlist, must be repeatable, reject sensitive filename families case-insensitively, reserve a new output directory without replacing a concurrent target, exclude private process evidence and preserve the exact public-main documentation baseline.
+
+## Separate release gate
+
+Only a later exact `release_approval` can authorize Ready/merge, scoped npm publication, dist-tags, annotated tag, GitHub prerelease, and disposable consumer verification. The merged public `main` tree must equal the final signed projection tree before release validation begins.
+
+Run Node.js 22 and 24 checks for Core, contracts, integrity, external Packs, frozen AGW behavior coverage, release source, Directory readiness, disposable consumer lifecycle, pack metadata, and audit. Verify GitHub API/SSH/npm identity as `chasechou007` without exposing credentials. Preserve Apache-2.0, the unscoped reservation, and the immutable alpha.1 through alpha.3 package/tag history.
+
+Do not unpublish or move an immutable version or Git tag. A shipped defect requires an ordinary source-first successor commit. Installation and diagnosis must leave project files unchanged unless the user separately approves an exact managed binding; return a Host Binding Receipt and confirm no implicit `.forgerail/` state.
+
+## Independent Directory and lifecycle gates
+
+Universal Plugins Directory draft, submission, review publication, verified publisher identity, Apps Management Write, portal regions and assets remain under a separate `submission_approval` or publication gate. AGW deprecation, redirect, archive, or deletion requires `lifecycle_change_approval`. No approval is transitive.

package/docs/release-alpha4.zh-CN.md

@@ -0,0 +1,33 @@
+# ForgeRail 0.1.0-alpha.4 完整性发布 Runbook
+
+本 source-first runbook 约束拟议的 `@echopath-labs/forgerail@0.1.0-alpha.4`、tag `v0.1.0-alpha.4` 与对应 Agent Plugin 投影。文档本身不授予 `remote_integration_approval`、`release_approval`、`submission_approval`、`rollback_approval` 或 `lifecycle_change_approval`。未作用域 `forgerail@0.0.0-reserved.0` 继续只作占位，不得接收产品代码，也不是安装或回滚来源。
+
+## 候选集成
+
+公共候选是已观测远端 `main` 的普通子 commit。该基线精确为 `e8fa29cd9f0f782d423d2fdd8abd778fbd362d61`。未来的精确 `remote_integration_approval` 最多允许把已签名 commit 推送到 `codex/forgerail-alpha4-critical-integrity`、创建一个 Draft PR，并观察 Node.js 22 与 24 Plugin Contracts CI。Draft PR base 与 publication comparison baseline 继续绑定已观测远端 `main`。
+
+任何修正都必须形成普通的 source-first successor commit。远端集成授权不允许 force push、改写候选、把 PR 转为 Ready、合并、打 tag、发布 npm 或创建 Release。每个外部 Capability Pack 分别安装与发现；可见不等于已认证、已启用或具有变更权限。
+
+## 完整性与兼容性证明
+
+运行 Core、完整性回归、Shadow comparison、release source、Directory、一次性消费者与外部 Pack 验证。仍满足 alpha.4 显式约束的 alpha.3 Profile、Pack、Task Envelope 与 Return Receipt 必须继续通过；Launch Contract 与 Adoption Plan 已有意收紧，必须重新生成后再交给 alpha.4 validator。非法标识符、日期、路径、重复身份、缺少必需 Pack、畸形 receipt、逃逸 adoption target、不安全 bundle source 与矛盾 orchestration event 必须 fail closed。
+
+每一条 Adoption 候选写入都携带 `approvalSha256`，绑定 canonical workspace 身份与完整可执行元数据：路径、操作、基线摘要、内容摘要、内容与 managed marker。集成方必须把人类已批准的摘要与可变候选分开保存，并在应用写入时显式传入；ForgeRail 只校验并使用一次不可变字段快照，且只接受 `create`、`append-managed-block`、`replace-managed-block` 三种操作，因此跨工作区重放、accessor 漂移、非法操作重放或普通元数据漂移都会在目标修改之前失败。替换既有 managed binding 时使用同目录原子 rename，并以 hard link 保留恢复入口，因此不会主动制造目标路径缺失的时间窗；若已安装 leaf 消失，可恢复原 binding 且不会遮蔽原始错误。四位年份（包括 `0000` 至 `0099`）按字面解释，不再触发 JavaScript 旧式的 1900 年偏移。
+
+只有起始和结束边界标记都恰好出现一次且顺序正确时，既有 managed binding 才能被替换。不完整、顺序颠倒、重复起始或重复结束的结构都会在生成候选前失败，并保持原文件不变。
+
+相对 alpha.3 的兼容性收紧必须明确：contract 标识符至少包含两个字符且首字符必须为字母或数字；每个 Launch Contract 必须携带已验证的 `effectiveProfile` 摘要以及当前 active Pack manifest 的规范身份摘要，工作区身份仅在 `envelope.ownerWorkspace` 出现一次；解析后的 `envelope.packs` 使用 Pack 身份到 manifest 摘要的映射，使每个 requested Pack 在公开 Schema 中直接自绑定；Effective Profile 的 `packs` 改为以 Pack 身份为键的对象，因此 alpha.3 Profile 必须重新生成；每个 required active Pack 必须存在可用 manifest，并由 task envelope 显式包含；Adoption 路径必须采用规范 portable segments，且一份计划中的所有写入必须绑定同一 workspace identity。Launch 构造只排序输入副本，不修改 Task Envelope；投影目录 denylist 不区分大小写。这些是 fail-closed 修正，不是未说明的兼容性回归。
+
+source-repository projection builder 仅供维护者使用，不得进入 npm 包或公共 CLI。公共投影必须要求 `package.json.files` 是显式数组、保持可重复、以不区分大小写的方式拒绝敏感文件名族、先独占保留新输出目录且不得替换并发出现的目标、排除私有过程证据，并保留公共 main 的文档基线。
+
+## 独立发布门
+
+只有后续精确 `release_approval` 才能授权 Ready/merge、作用域 npm 发布、dist-tags、annotated tag、GitHub prerelease 与一次性消费者复验。合并后的公共 `main` tree 必须等于最终签名 projection tree，之后才能开始发布验证。
+
+Node.js 22 和 24 必须验证 Core、contracts、integrity、外部 Packs、冻结 AGW 行为覆盖、release source、Directory readiness、一次性消费者生命周期、pack metadata 与 audit。GitHub API/SSH/npm 身份必须为 `chasechou007`，且不得暴露凭据。保留 Apache-2.0、未作用域占位包以及 alpha.1 至 alpha.3 的不可变 package/tag 历史。
+
+不得 unpublish 或移动不可变版本和 Git tag。已发布缺陷只能通过普通的 source-first successor commit 修复。安装和诊断默认不得修改项目文件；只有用户另行批准精确 managed binding 后才可写入，并须返回 Host Binding Receipt，确认未隐式创建 `.forgerail/` 状态。
+
+## 独立 Directory 与生命周期门
+
+Universal Plugins Directory draft、submission、review publication、verified publisher identity、Apps Management Write、portal regions 与 assets 仍属于独立 `submission_approval` 或 publication gate。AGW deprecation、redirect、archive 或 deletion 需要 `lifecycle_change_approval`。任何审批都不可传递。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echopath-labs/forgerail",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Deterministic validation and diagnosis CLI for the ForgeRail Agent Plugin.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,6 +20,7 @@
     "skills/",
     "templates/",
     "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
     "CONTRIBUTING.md",
     "LICENSE",
     "NOTICE",
@@ -28,20 +29,23 @@
     "README.md",
     "README.zh-CN.md",
     "SECURITY.md",
+    "SUPPORT.md",
     "TERMS.md"
   ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "test": "node scripts/forgerail.mjs validate && node scripts/forgerail.mjs validate-fixtures && node scripts/forgerail.mjs validate-adoption",
+    "test": "node scripts/forgerail.mjs validate && node scripts/forgerail.mjs validate-fixtures && node scripts/forgerail.mjs validate-adoption && npm run test:docs",
+    "test:integrity": "node scripts/integrity-regressions.mjs",
+    "test:docs": "node scripts/validate-open-source-docs.mjs",
     "test:consumer": "node scripts/disposable-consumer.mjs",
     "test:release": "node scripts/validate-release.mjs",
     "test:shadow": "node scripts/shadow-comparison.mjs",
     "test:directory": "node scripts/validate-universal-directory.mjs",
     "build:directory-candidate": "node scripts/build-universal-directory-candidate.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 && npm run test:directory"
+    "prepublishOnly": "npm test && npm run test:integrity && npm run test:shadow && npm run test:release && npm run test:consumer && npm run test:directory"
   },
   "repository": {
     "type": "git",

package/scripts/adoption-closeout-regressions.mjs

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { adoptionWriteApprovalDigest, loadHostAdapters, planAdoption } from "./lib/adoption.mjs";
+import { validateContract } from "./lib/contracts.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+function temporary(t, prefix) {
+  const path = mkdtempSync(resolve(tmpdir(), prefix));
+  t.after(() => rmSync(path, { recursive: true, force: true }));
+  return path;
+}
+function registry(t) {
+  const path = temporary(t, "forgerail-closeout-registry-");
+  for (const name of ["adapters", "templates"]) cpSync(resolve(root, name), resolve(path, name), { recursive: true });
+  return path;
+}
+
+test("registry reports every non-object JSON root without crashing", (t) => {
+  const plugin = registry(t);
+  for (const value of [null, [], false, 1, "invalid"]) {
+    writeFileSync(resolve(plugin, "adapters/malformed.json"), JSON.stringify(value));
+    const result = loadHostAdapters(plugin);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some((error) => error.startsWith("malformed.json:")));
+  }
+});
+
+test("received plans reject reserved, case-folded and ancestor target collisions", (t) => {
+  const workspace = temporary(t, "forgerail-closeout-plan-");
+  const plan = planAdoption(root, workspace, ["codex", "claude-code"]);
+  assert.equal(validateContract("adoption-plan", plan).valid, true);
+  for (const target of ["FORGERAIL.md/CLAUDE.md", "forgerail.md", "AGENTS.md", "agents.md", "AGENTS.md/nested.md"]) {
+    const invalid = structuredClone(plan);
+    invalid.hostSelection.hosts["claude-code"].bindingTarget = target;
+    const write = invalid.proposedWrites.find(({ path }) => path === "CLAUDE.md");
+    write.path = target;
+    write.approvalSha256 = adoptionWriteApprovalDigest(write);
+    const result = validateContract("adoption-plan", invalid);
+    assert.equal(result.valid, false, target);
+    assert.ok(result.errors.some((error) => error.includes("conflict")), result.errors.join("; "));
+  }
+  for (const writes of [null, {}, [null]]) {
+    const invalid = structuredClone(plan);
+    invalid.proposedWrites = writes;
+    assert.equal(validateContract("adoption-plan", invalid).valid, false);
+  }
+  assert.equal(existsSync(resolve(workspace, "FORGERAIL.md")), false);
+});
+
+test("subset plans report existing unselected adoption without granting it writes", (t) => {
+  const workspace = temporary(t, "forgerail-closeout-existing-host-");
+  const path = resolve(workspace, "AGENTS.md");
+  const content = "<!-- forgerail:binding:codex:v1:start -->\nExisting standalone rules.\n<!-- forgerail:binding:codex:v1:end -->\n";
+  writeFileSync(path, content);
+  const plan = planAdoption(root, workspace, ["claude-code"]);
+  assert.equal(plan.currentLevel, "lightweight-adoption");
+  assert.ok(plan.evidence.some((value) => value.includes("Unselected managed binding retained: AGENTS.md")));
+  assert.deepEqual(plan.proposedWrites.map(({ path }) => path), ["FORGERAIL.md", "CLAUDE.md"]);
+  assert.equal(readFileSync(path, "utf8"), content);
+  const noChange = planAdoption(root, workspace, ["claude-code"], "plugin-only");
+  assert.equal(noChange.strategy, "no-change");
+  assert.equal(noChange.currentLevel, "lightweight-adoption");
+  assert.deepEqual(noChange.proposedWrites, []);
+});
+
+test("unsafe unselected bindings remain non-blocking and unavailable", (t) => {
+  const workspace = temporary(t, "forgerail-closeout-unsafe-host-");
+  const outside = temporary(t, "forgerail-closeout-outside-");
+  writeFileSync(resolve(outside, "CLAUDE.md"), "<!-- forgerail:binding:claude-code:v1:start -->\n");
+  symlinkSync(resolve(outside, "CLAUDE.md"), resolve(workspace, "CLAUDE.md"));
+  const plan = planAdoption(root, workspace, ["codex"]);
+  assert.equal(plan.currentLevel, "plugin-only");
+  assert.ok(plan.evidence.some((value) => value.includes("Unselected binding unavailable: CLAUDE.md")));
+  assert.equal(plan.evidence.some((value) => value.includes(outside)), false);
+  assert.deepEqual(plan.proposedWrites.map(({ path }) => path), ["AGENTS.md"]);
+});
+
+test("thin templates contain an exact shared-contract reference inside their managed block", (t) => {
+  const plugin = registry(t);
+  const adapter = JSON.parse(readFileSync(resolve(plugin, "adapters/claude-code.json"), "utf8"));
+  const path = resolve(plugin, "templates", adapter.bindingTemplates["thin-reference"]);
+  const start = `<!-- ${adapter.managedMarker}:start -->`;
+  const end = `<!-- ${adapter.managedMarker}:end -->`;
+  for (const content of [
+    `${start}\nUnrelated instructions.\n${end}`,
+    `Follow FORGERAIL.md.\n${start}\nUnrelated instructions.\n${end}`,
+    `${start}\nFollow NOTFORGERAIL.md.\n${end}`,
+  ]) {
+    writeFileSync(path, content);
+    const result = loadHostAdapters(plugin);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some((error) => error.includes("shared contract reference")), result.errors.join("; "));
+  }
+  writeFileSync(path, `${start}\nFollow \`FORGERAIL.md\`.\n${end}\n`);
+  assert.equal(loadHostAdapters(plugin).valid, true);
+});

package/scripts/build-universal-directory-candidate.mjs

@@ -54,8 +54,8 @@ const result = {
   approvalStatus: candidate.approval.status,
   product: manifest.name,
   pluginVersion: manifest.version,
-  privateBaseline: "59c7bb52f16cda2d47a8a49bb43860517f9bd7eb",
-  sourceDate: "2026-08-30",
+  privateBaseline: "ebf1851300b549c97cd909cbe7354c32661f5063",
+  sourceDate: "2026-08-31",
   inventory,
   contentDigest: sha256(JSON.stringify(inventory)),
   unresolvedGates: candidate.unresolvedGates,

package/scripts/disposable-consumer.mjs

@@ -5,7 +5,7 @@ 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";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
 const base = mkdtempSync(resolve(tmpdir(), "forgerail-consumer-"));
@@ -48,20 +48,6 @@ function snapshot(path) {
     });
 }
 
-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]);
@@ -77,9 +63,12 @@ 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 adoptionLibrary = await import(pathToFileURL(resolve(installedPackageRoot, "scripts/lib/adoption.mjs")).href);
+const approvedContent = adoptionLibrary.renderProposedWrite(target, proposed);
+const approvedWriteDigest = proposed.approvalSha256;
+const appliedWrite = adoptionLibrary.applyApprovedAdoptionWrite(target, proposed, approvedWriteDigest);
 const approvedDigest = sha256(approvedContent);
+if (appliedWrite.contentSha256 !== approvedDigest) throw new Error("approved adoption write digest mismatch");
 const discoveredSkills = firstValidation.skills;
 const bindingReceipt = {
   schemaVersion: "1.0",
@@ -112,6 +101,7 @@ run("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", priorTarba
 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"]));
+const installedIntegrity = JSON.parse(run("npm", ["run", "test:integrity", "--silent"], installedPackageRoot));
 run("npm", ["uninstall", "--no-audit", "--no-fund", packageName]);
 
 const result = {
@@ -133,11 +123,14 @@ const result = {
   noPersistedGovernance: !existsSync(resolve(target, ".forgerail")),
   launch: launch.valid && launch.launch.executionOwner === "host-agent",
   reinstall: reinstallValidation.valid,
+  installedIntegrity: installedIntegrity.valid
+    && installedIntegrity.assertions.includes("source-only-bundle-regressions-not-installed")
+    && installedIntegrity.assertions.includes("source-only-shadow-regressions-not-installed"),
   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;
+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.installedIntegrity && 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

@@ -5,35 +5,44 @@
   "currentLevel": "plugin-only",
   "proposedLevel": "lightweight-adoption",
   "strategy": "shared-contract-with-thin-bindings",
+  "hostSelection": {
+    "mode": "explicit",
+    "hosts": {
+      "codex": { "status": "supported", "bindingTarget": "AGENTS.md", "verificationMode": "new-task-discovery" },
+      "claude-code": { "status": "profile-only", "bindingTarget": "CLAUDE.md", "verificationMode": "profile-only" }
+    }
+  },
   "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": [
     {
+      "workspaceSha256": "f16d05ec6b29248d2c61adb1e9263f78e4f7bace1b955014a2d17872cfe4064d",
       "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"
+      "managedMarker": "forgerail:adoption-contract:v1",
+      "approvalSha256": "c074e0b035d4dd68ac597b1ebedc7b58f29b3b3ba98d4cf33de49d437ed27fe0"
     },
     {
+      "workspaceSha256": "f16d05ec6b29248d2c61adb1e9263f78e4f7bace1b955014a2d17872cfe4064d",
       "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"
+      "managedMarker": "forgerail:binding:codex:v1",
+      "approvalSha256": "b2f76b3d4f6730ebac4771e7fcecb1969df6ec62a05c2f6bcc441e8e8aa2741a"
     },
     {
+      "workspaceSha256": "f16d05ec6b29248d2c61adb1e9263f78e4f7bace1b955014a2d17872cfe4064d",
       "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"
+      "managedMarker": "forgerail:binding:claude-code:v1",
+      "approvalSha256": "cc472c070fcc287f1d226600e316b0cb0cfbf8303dfd9ed44dc2b6b98b9d47ff"
     }
   ],
   "requiredConfirmation": true,

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

@@ -5,10 +5,13 @@
   "currentLevel": "plugin-only",
   "proposedLevel": "lightweight-adoption",
   "strategy": "single-host-managed-block",
+  "hostSelection": {
+    "mode": "explicit",
+    "hosts": {
+      "codex": { "status": "supported", "bindingTarget": "AGENTS.md", "verificationMode": "new-task-discovery" }
+    }
+  },
   "evidence": ["Codex was selected."],
-  "hosts": [
-    { "adapterId": "codex", "status": "supported", "bindingTarget": "AGENTS.md", "verificationMode": "new-task-discovery" }
-  ],
   "proposedWrites": [],
   "requiredConfirmation": true,
   "verification": ["Start a new task."],

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

@@ -5,18 +5,23 @@
   "currentLevel": "plugin-only",
   "proposedLevel": "lightweight-adoption",
   "strategy": "single-host-managed-block",
+  "hostSelection": {
+    "mode": "explicit",
+    "hosts": {
+      "codex": { "status": "supported", "bindingTarget": "AGENTS.md", "verificationMode": "new-task-discovery" }
+    }
+  },
   "evidence": ["Codex was explicitly selected."],
-  "hosts": [
-    { "adapterId": "codex", "status": "supported", "bindingTarget": "AGENTS.md", "verificationMode": "new-task-discovery" }
-  ],
   "proposedWrites": [
     {
+      "workspaceSha256": "f16d05ec6b29248d2c61adb1e9263f78e4f7bace1b955014a2d17872cfe4064d",
       "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"
+      "managedMarker": "forgerail:binding:codex:v1",
+      "approvalSha256": "4a3ac2446e5f1ec0fe3273c106b9ca6aead4aaa4c355ae722ee9921fae9148da"
     }
   ],
   "requiredConfirmation": true,

package/scripts/fixtures/contracts/effective-profile.duplicate-rule.invalid.json

@@ -18,6 +18,6 @@
       "status": "inferred"
     }
   ],
-  "packs": [],
+  "packs": {},
   "conflicts": []
 }

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

@@ -18,12 +18,11 @@
       "status": "observed"
     }
   ],
-  "packs": [
-    {
-      "id": "workspace-health-review",
+  "packs": {
+    "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

@@ -6,7 +6,12 @@
   "instructionDiscovery": "task-start",
   "skillDiscovery": "agent-skills",
   "bindingTarget": "CLAUDE.md",
-  "bindingModes": ["managed-block", "thin-reference"],
+  "detectionTargets": ["CLAUDE.md", ".claude"],
+  "bindingModes": ["thin-reference"],
+  "bindingTemplates": {
+    "thin-reference": "bindings/claude-code-thin.md"
+  },
+  "unmanagedBindingPolicy": "append-managed-block",
   "managedMarker": "forgerail:binding:claude-code:v1",
   "activationBoundary": "host-specific-verification-required",
   "verification": { "mode": "profile-only", "expectedSkills": [] },

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

@@ -6,7 +6,13 @@
   "instructionDiscovery": "task-start",
   "skillDiscovery": "agent-plugin-skills",
   "bindingTarget": "AGENTS.md",
+  "detectionTargets": ["AGENTS.md"],
   "bindingModes": ["managed-block", "thin-reference"],
+  "bindingTemplates": {
+    "managed-block": "bindings/codex-compact.md",
+    "thin-reference": "bindings/codex-thin.md"
+  },
+  "unmanagedBindingPolicy": "append-managed-block",
   "managedMarker": "forgerail:binding:codex:v1",
   "activationBoundary": "new-task-required",
   "verification": {

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

@@ -6,7 +6,12 @@
   "instructionDiscovery": "rules",
   "skillDiscovery": "unknown",
   "bindingTarget": ".cursor/rules/forgerail.mdc",
+  "detectionTargets": [".cursor"],
   "bindingModes": ["thin-reference"],
+  "bindingTemplates": {
+    "thin-reference": "bindings/cursor-thin.mdc"
+  },
+  "unmanagedBindingPolicy": "reject",
   "managedMarker": "forgerail:binding:cursor:v1",
   "activationBoundary": "host-specific-verification-required",
   "verification": { "mode": "profile-only", "expectedSkills": [] },

package/scripts/fixtures/contracts/host-adapter.false-supported.invalid.json

@@ -6,7 +6,12 @@
   "instructionDiscovery": "task-start",
   "skillDiscovery": "agent-skills",
   "bindingTarget": "CLAUDE.md",
-  "bindingModes": ["managed-block", "thin-reference"],
+  "detectionTargets": ["CLAUDE.md", ".claude"],
+  "bindingModes": ["thin-reference"],
+  "bindingTemplates": {
+    "thin-reference": "bindings/claude-code-thin.md"
+  },
+  "unmanagedBindingPolicy": "append-managed-block",
   "managedMarker": "forgerail:binding:claude-code:v1",
   "activationBoundary": "host-specific-verification-required",
   "verification": { "mode": "profile-only", "expectedSkills": [] },

package/scripts/fixtures/contracts/launch-contract.execution-owner.invalid.json

@@ -8,11 +8,15 @@
     "ownerWorkspace": "fixture-workspace",
     "allowedOperations": ["read files", "edit documentation", "run local validation"],
     "prohibitedOperations": ["push", "merge", "tag", "release"],
-    "packs": [],
+    "packs": {},
     "approvalGates": ["remote-integration-approval", "release-approval"],
     "validation": ["git diff --check passes"],
     "returnContract": "forgerail-return-receipt-v1"
   },
+  "effectiveProfile": {
+    "digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+  },
+  "effectivePackManifests": {},
   "effectiveRuleSources": ["AGENTS.md", "ForgeRail Core"],
   "hostAgent": "Codex",
   "executionOwner": "forgerail"

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

@@ -8,11 +8,15 @@
     "ownerWorkspace": "fixture-workspace",
     "allowedOperations": ["read files", "edit documentation", "run local validation"],
     "prohibitedOperations": ["push", "merge", "tag", "release"],
-    "packs": [],
+    "packs": {},
     "approvalGates": ["remote-integration-approval", "release-approval"],
     "validation": ["git diff --check passes"],
     "returnContract": "forgerail-return-receipt-v1"
   },
+  "effectiveProfile": {
+    "digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+  },
+  "effectivePackManifests": {},
   "effectiveRuleSources": ["AGENTS.md", "ForgeRail Core"],
   "hostAgent": "Codex",
   "executionOwner": "host-agent"

package/scripts/fixtures/open-source-docs/cases.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": "1.0",
+  "cases": [
+    {
+      "id": "current-release-and-install",
+      "kind": "release-text",
+      "content": "Current public prerelease 0.1.0-alpha.4. codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.4",
+      "expectedErrors": []
+    },
+    {
+      "id": "stale-alpha2-install",
+      "kind": "release-text",
+      "content": "Install the current v0.1.0-alpha.2 release.",
+      "expectedErrors": ["stale-release"]
+    },
+    {
+      "id": "broken-relative-link",
+      "kind": "markdown-link",
+      "content": "Read [missing](does-not-exist.md).",
+      "expectedErrors": ["broken-link"]
+    },
+    {
+      "id": "valid-issue-form",
+      "kind": "issue-form",
+      "content": "name: Bug report\ndescription: Report a problem.\nbody: []\n",
+      "expectedErrors": []
+    },
+    {
+      "id": "missing-issue-description",
+      "kind": "issue-form",
+      "content": "name: Bug report\nbody: []\n",
+      "expectedErrors": ["invalid-issue-metadata"]
+    },
+    {
+      "id": "stale-alpha3-issue-version",
+      "kind": "issue-form",
+      "content": "name: Documentation issue\ndescription: Report stale docs.\nbody:\n  - label: I checked the current alpha.3 documentation.\n",
+      "expectedErrors": ["stale-issue-version"]
+    },
+    {
+      "id": "private-path-leak",
+      "kind": "public-text",
+      "content": "Continue in __PRIVATE_USER_PATH__.",
+      "expectedErrors": ["private-path"]
+    },
+    {
+      "id": "private-process-reference-leak",
+      "kind": "public-text",
+      "content": "Canonical architecture change: openspec/changes/private-control-system/",
+      "expectedErrors": ["private-process-reference"]
+    },
+    {
+      "id": "project-node-requirement",
+      "kind": "no-node-claim",
+      "content": "Before using the Plugin, initialize package.json in your project and install Node.js.",
+      "expectedErrors": ["project-node-required"]
+    },
+    {
+      "id": "plugin-only-no-node",
+      "kind": "no-node-claim",
+      "content": "Plugin Only does not require Node.js, package.json, node_modules, or .forgerail/ in the target project.",
+      "expectedErrors": []
+    }
+  ]
+}