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

package/scripts/validate-release.mjs

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 
-import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const expectedPackageName = "@echopath-labs/forgerail";
-const expectedVersion = "0.1.0-alpha.2";
+const expectedVersion = "0.1.0-alpha.4";
 const expectedTag = `v${expectedVersion}`;
-const expectedDate = "2026-08-30";
+const expectedDate = "2026-09-01";
 const expectedPlugins = [
   "forgerail",
   "forgerail-cross-workspace-orchestration",
@@ -38,6 +40,30 @@ function findExisting(candidates) {
 
 const packageJson = json("package.json");
 const packageLock = json("package-lock.json");
+const launchContractSchema = json("contracts/launch-contract.schema.json");
+const effectiveProfileSchema = json("contracts/effective-profile.schema.json");
+const publicCli = read("scripts/forgerail.mjs");
+const packCache = mkdtempSync(resolve(tmpdir(), "forgerail-pack-cache-"));
+const packEnvironment = Object.fromEntries(
+  Object.entries(process.env).filter(([key]) => key.toLowerCase() !== "npm_config_cache"),
+);
+packEnvironment.NPM_CONFIG_CACHE = packCache;
+let packResult;
+try {
+  packResult = spawnSync("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"], {
+    cwd: root,
+    encoding: "utf8",
+    env: packEnvironment,
+  });
+} finally {
+  rmSync(packCache, { recursive: true, force: true });
+}
+let packedFiles = [];
+try {
+  packedFiles = packResult.status === 0
+    ? JSON.parse(packResult.stdout)[0]?.files?.map(({ path }) => path) ?? []
+    : [];
+} catch {}
 record("package-name", packageJson.name === expectedPackageName, packageJson.name);
 record("package-lock-name", packageLock.name === expectedPackageName && packageLock.packages?.[""]?.name === expectedPackageName, packageLock.name);
 record("package-version", packageJson.version === expectedVersion, packageJson.version);
@@ -45,9 +71,26 @@ record("package-lock-version", packageLock.version === expectedVersion && packag
 record("package-license", packageJson.license === "Apache-2.0", packageJson.license);
 record("package-lock-license", packageLock.packages?.[""]?.license === "Apache-2.0", packageLock.packages?.[""]?.license ?? null);
 record("npm-next-tag", packageJson.publishConfig?.tag === "next", packageJson.publishConfig?.tag ?? null);
+record("no-public-bundle-builder-command", !publicCli.includes('command === "build-bundle"'), "source-repository maintainer tool only");
+record("npm-pack-dry-run", packResult.status === 0 && packedFiles.length > 0, packResult.status === 0 ? `${packedFiles.length} files` : packResult.stderr.trim());
+record("bundle-builder-source-only", existsSync(resolve(root, "tools/lib/bundle.mjs")) && !packedFiles.includes("tools/lib/bundle.mjs"), "tools/lib/bundle.mjs");
+record(
+  "launch-requested-pack-schema-native-binding",
+  launchContractSchema.properties?.envelope?.properties?.packs?.type === "object"
+    && launchContractSchema.properties?.envelope?.properties?.packs?.additionalProperties?.pattern === "^[0-9a-f]{64}$",
+  launchContractSchema.properties?.envelope?.properties?.packs ?? null,
+);
+record(
+  "profile-pack-schema-native-identity",
+  effectiveProfileSchema.properties?.packs?.type === "object"
+    && effectiveProfileSchema.properties?.packs?.propertyNames?.pattern === "^[a-z][a-z0-9-]+$"
+    && effectiveProfileSchema.properties?.packs?.additionalProperties?.required?.includes("state")
+    && effectiveProfileSchema.properties?.packs?.additionalProperties?.required?.includes("reason"),
+  effectiveProfileSchema.properties?.packs ?? null,
+);
 record(
   "prepublish-gate",
-  ["npm test", "npm run test:shadow", "npm run test:release", "npm run test:consumer", "npm run test:directory"].every((command) => packageJson.scripts?.prepublishOnly?.includes(command)),
+  ["npm test", "npm run test:integrity", "npm run test:shadow", "npm run test:release", "npm run test:consumer", "npm run test:directory"].every((command) => packageJson.scripts?.prepublishOnly?.includes(command)),
   packageJson.scripts?.prepublishOnly ?? null,
 );
 
@@ -89,7 +132,11 @@ for (const phrase of ["Workspace Diagnosis", "Return Receipts", "GitHub Rulesets
   record(`changelog-${phrase.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-")}`, changelog.includes(phrase), phrase);
 }
 
-const marketplacePath = findExisting(["marketplace/.agents/plugins/marketplace.json", ".agents/plugins/marketplace.json"]);
+const marketplacePath = findExisting([
+  "marketplace/.agents/plugins/marketplace.json",
+  ".agents/plugins/marketplace.json",
+  "../../.agents/plugins/marketplace.json",
+]);
 const marketplace = json(marketplacePath);
 const marketplacePlugins = new Map(marketplace.plugins.map((plugin) => [plugin.name, plugin]));
 record("marketplace-name", marketplace.name === "echopath-labs", marketplace.name);
@@ -99,15 +146,17 @@ for (const name of expectedPlugins) {
   if (name !== "forgerail") record(`marketplace-${name}-on-use`, plugin?.policy?.authentication === "ON_USE", plugin?.policy?.authentication ?? null);
 }
 
-const installation = `${read("docs/installation.md")}\n${read("docs/installation.zh-CN.md")}`;
+const installation = `${read("docs/installation.md")}\n${read("docs/installation.zh-CN.md")}\n${read("docs/adoption.md")}\n${read("docs/adoption.zh-CN.md")}`;
 for (const phrase of [
-  "codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.1",
+  `codex plugin marketplace add echopath-labs/forgerail --ref ${expectedTag}`,
   "codex plugin add forgerail@echopath-labs",
   "codex plugin add forgerail-cross-workspace-orchestration@echopath-labs",
   "codex plugin add forgerail-github-rulesets@echopath-labs",
   `${expectedPackageName}@${expectedVersion}`,
   "new Codex task",
   "adoption-plan --workspace . --host codex",
+  "adoption-plan --workspace . --selection all-detected",
+  "adoption-plan --workspace . --selection all-available",
   "Host Binding Receipt",
 ]) {
   record(`installation-${phrase.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-")}`, installation.includes(phrase), phrase);
@@ -122,6 +171,9 @@ for (const path of [
   "adapters/cursor.json",
   "templates/FORGERAIL.md",
   "templates/bindings/codex-compact.md",
+  "templates/bindings/codex-thin.md",
+  "templates/bindings/claude-code-thin.md",
+  "templates/bindings/cursor-thin.mdc",
   "docs/adoption.md",
   "docs/adoption.zh-CN.md",
 ]) record(`adoption-path-${path.replaceAll(/[^a-z0-9]+/gi, "-").toLowerCase()}`, existsSync(resolve(root, path)), path);
@@ -129,15 +181,24 @@ for (const path of [
 const codexAdapter = json("adapters/codex.json");
 const claudeAdapter = json("adapters/claude-code.json");
 const cursorAdapter = json("adapters/cursor.json");
-record("codex-adapter-supported", codexAdapter.status === "supported" && codexAdapter.bindingTarget === "AGENTS.md", codexAdapter.status);
-record("claude-adapter-profile-only", claudeAdapter.status === "profile-only", claudeAdapter.status);
-record("cursor-adapter-profile-only", cursorAdapter.status === "profile-only", cursorAdapter.status);
+record("codex-adapter-supported", codexAdapter.status === "supported" && codexAdapter.bindingTarget === "AGENTS.md" && codexAdapter.detectionTargets?.includes("AGENTS.md"), codexAdapter.status);
+record("claude-adapter-profile-only", claudeAdapter.status === "profile-only" && claudeAdapter.detectionTargets?.includes("CLAUDE.md"), claudeAdapter.status);
+record("claude-adapter-thin-only", JSON.stringify(claudeAdapter.bindingModes) === JSON.stringify(["thin-reference"]), claudeAdapter.bindingModes);
+record("cursor-adapter-profile-only", cursorAdapter.status === "profile-only" && cursorAdapter.detectionTargets?.includes(".cursor"), cursorAdapter.status);
+for (const adapter of [codexAdapter, claudeAdapter, cursorAdapter]) {
+  const modes = Object.keys(adapter.bindingTemplates ?? {}).sort();
+  record(`adapter-${adapter.id}-template-modes`, JSON.stringify(modes) === JSON.stringify([...adapter.bindingModes].sort()), { modes, bindingModes: adapter.bindingModes });
+  record(`adapter-${adapter.id}-all-host-thin-reference`, adapter.bindingModes.includes("thin-reference"), adapter.bindingModes);
+  for (const [mode, template] of Object.entries(adapter.bindingTemplates ?? {})) {
+    record(`adapter-${adapter.id}-${mode}-template`, existsSync(resolve(root, "templates", template)), template);
+  }
+}
 record("package-adapters", packageJson.files?.includes("adapters/"), packageJson.files ?? null);
 record("package-templates", packageJson.files?.includes("templates/"), packageJson.files ?? null);
 record("no-apply-adoption-script", !read("scripts/forgerail.mjs").includes('command === "apply-adoption"'), "no apply-adoption command");
 
-const releaseEnglish = read("docs/release-alpha2.md");
-const releaseChinese = read("docs/release-alpha2.zh-CN.md");
+const releaseEnglish = read("docs/release-alpha4.md");
+const releaseChinese = read("docs/release-alpha4.zh-CN.md");
 const releaseDocs = `${releaseEnglish}\n${releaseChinese}`;
 for (const phrase of [
   "remote_integration_approval",
@@ -146,7 +207,7 @@ for (const phrase of [
   expectedVersion,
   expectedTag,
   "Node.js 22 and 24",
-  "codex/forgerail-alpha2-scoped",
+  "codex/forgerail-alpha4-critical-integrity",
   "Do not unpublish",
   "AGW",
   "Host Binding Receipt",
@@ -179,8 +240,11 @@ record("runbook-no-fixed-external-pack-count", !releaseChinese.includes("三个
 const workflow = read(".github/workflows/plugin-contracts.yml");
 record("ci-node-22", workflow.includes("- 22"), "Node.js 22");
 record("ci-node-24", workflow.includes("- 24"), "Node.js 24");
+record("ci-full-core", workflow.includes("run: npm test"), "npm test");
+record("ci-integrity-regressions", workflow.includes("run: npm run test:integrity"), "npm run test:integrity");
 record("ci-release-source", workflow.includes("node scripts/validate-release.mjs"), "release source validator");
 record("ci-progressive-adoption", workflow.includes("node scripts/forgerail.mjs validate-adoption"), "progressive adoption validator");
+record("ci-directory", workflow.includes("node scripts/validate-universal-directory.mjs"), "Universal Directory validator");
 
 const failures = checks.filter((check) => !check.passed);
 const report = {

package/scripts/validate-universal-directory.mjs

@@ -64,11 +64,11 @@ function validateMarkdownLinks(relativePath) {
 }
 
 assert(candidate.submissionType === "skills_only", "candidate is Skills-only");
-assert(candidate.status === "local_alpha2_source_candidate", "candidate status is local alpha.2 source preparation");
+assert(candidate.status === "local_alpha4_integrity_candidate", "candidate status is local alpha.4 integrity preparation");
 assert(candidate.approval.status === "not_granted", "submission approval is not granted");
 assert(candidate.plugin.id === manifest.name, "candidate and manifest Plugin identity match");
 assert(candidate.plugin.version === manifest.version, "candidate and manifest version match");
-assert(candidate.plugin.version === "0.1.0-alpha.2", "candidate version is alpha.2");
+assert(candidate.plugin.version === "0.1.0-alpha.4", "candidate version is alpha.4");
 assert(packageJson.version === candidate.plugin.version, "optional scoped package version matches candidate");
 assert(candidate.plugin.mcpServers.length === 0, "candidate has no MCP server requirement");
 assert(candidate.plugin.authentication === "none", "candidate has no authentication requirement");
@@ -76,6 +76,18 @@ assert(candidate.plugin.coreRequirements.projectPackageJson === false, "Core req
 assert(candidate.plugin.coreRequirements.projectNodeModules === false, "Core requires no project node_modules");
 assert(candidate.plugin.coreRequirements.npmCli === "optional", "npm CLI is optional");
 
+const expectedDefaultPrompts = [
+  "Use ForgeRail to govern this engineering task.",
+  "Diagnose this workspace before recommending governance changes.",
+  "Review workspace health or audit duplicated architecture ownership using the matching independent ForgeRail Skill.",
+];
+assert(Array.isArray(manifest.interface.defaultPrompt), "defaultPrompt is an array");
+assert(manifest.interface.defaultPrompt.length <= 3, "defaultPrompt stays within the Codex maximum of three");
+assert(manifest.interface.defaultPrompt.length === expectedDefaultPrompts.length, "defaultPrompt exposes the three reviewed intents");
+assert(new Set(manifest.interface.defaultPrompt).size === manifest.interface.defaultPrompt.length, "defaultPrompt entries are unique");
+assert(manifest.interface.defaultPrompt.every((prompt) => typeof prompt === "string" && prompt.trim().length > 0), "defaultPrompt entries are non-empty strings");
+assert(JSON.stringify(manifest.interface.defaultPrompt) === JSON.stringify(expectedDefaultPrompts), "defaultPrompt entries match the reviewed governance, diagnosis, and either-or review router");
+
 for (const skill of candidate.plugin.skills) {
   assert(existsSync(resolve(pluginRoot, "skills", skill, "SKILL.md")), `declared Skill exists: ${skill}`);
 }
@@ -96,8 +108,8 @@ for (const field of ["websiteUrl", "supportUrl", "privacyPolicyUrl", "termsOfSer
 }
 assert(candidate.availability.intent.state === "confirmed_by_user" && candidate.availability.intent.value === "all_platform_supported_regions", "all-platform-supported-regions intent is user-confirmed");
 assert(candidate.availability.portalEnumeration.state === "pending_confirmation" && candidate.availability.portalEnumeration.values.length === 0, "portal region enumeration remains pending without an invented country list");
-assert(candidate.releaseNotes.state === "candidate" && candidate.releaseNotes.path === "./directory/release-notes-alpha2.md", "alpha.2 release notes path is explicit");
-assert(existsSync(resolve(pluginRoot, candidate.releaseNotes.path)), "alpha.2 release notes file exists");
+assert(candidate.releaseNotes.state === "candidate" && candidate.releaseNotes.path === "./directory/release-notes-alpha4.md", "alpha.4 release notes path is explicit");
+assert(existsSync(resolve(pluginRoot, candidate.releaseNotes.path)), "alpha.4 release notes file exists");
 
 const privacy = readFileSync(resolve(pluginRoot, "PRIVACY.md"), "utf8");
 const terms = readFileSync(resolve(pluginRoot, "TERMS.md"), "utf8");
@@ -107,7 +119,7 @@ for (const phrase of ["Skills-only Agent Plugin", "does not operate its own serv
 for (const phrase of ["Apache License 2.0", "without warranties", "You are responsible", "external actions", "does not provide legal advice", "service-level agreement"]) {
   assert(terms.includes(phrase), `Terms contain required boundary: ${phrase}`);
 }
-for (const path of ["PRIVACY.md", "TERMS.md", "README.md", "README.zh-CN.md", "docs/installation.md", "docs/installation.zh-CN.md", "docs/release-alpha2.md", "docs/release-alpha2.zh-CN.md"]) {
+for (const path of ["PRIVACY.md", "TERMS.md", "README.md", "README.zh-CN.md", "docs/installation.md", "docs/installation.zh-CN.md", "docs/release-alpha4.md", "docs/release-alpha4.zh-CN.md"]) {
   validateMarkdownLinks(path);
 }
 

package/skills/forgerail/references/adoption.md

@@ -6,8 +6,8 @@ Use the minimum level:
 2. `lightweight-adoption`: user-confirmed host instruction binding.
 3. `persisted-governance`: evidence-gated and deferred in alpha.1.
 
-For one host, propose one versioned managed block in its native target. For multiple hosts, propose `FORGERAIL.md` plus thin references. Host files are adapters, not Core sources.
+For one host, propose one versioned managed block when its adapter supports that mode. For multiple hosts, or one thin-reference-only host, propose `FORGERAIL.md` plus thin references. Host files are adapters, not Core sources.
 
-Run `forgerail adoption-plan --workspace <path> --host <adapter>` when the deterministic CLI is available. Never infer permission to apply the returned writes. Display exact content and paths, obtain confirmation, verify base digests immediately before writing, preserve unrelated content, and produce a Host Binding Receipt.
+Translate the user's natural-language host intent into one deterministic selection: repeated `--host <adapter>` for an explicit subset, `--selection all-detected` for registry adapters evidenced in the workspace, or `--selection all-available` for every adapter in the current registry. Omitting both options defaults to `all-detected`. Do not invent a host ID or instruction path; an unknown host needs a reviewed Host Adapter. Run `forgerail adoption-plan --workspace <path> ...` when the deterministic CLI is available. Never infer permission to apply the returned writes. Display the retained selection, exact content, paths and each write's `approvalSha256`, obtain confirmation, and preserve the approved digest separately from the mutable proposal. Node-based integrations must pass that retained digest as the third argument to `applyApprovedAdoptionWrite()` from `scripts/lib/adoption.mjs` to revalidate the canonical workspace identity and complete executable write metadata from one immutable snapshot, plus confinement, no-follow open, file identity and base digest at write time. Produce a Host Binding Receipt after verification.
 
 Codex is `supported` in alpha.1. Claude Code and Cursor are `profile-only`; do not close their binding as verified without a host-specific activation check.

package/skills/forgerail/references/contracts.md

@@ -16,7 +16,7 @@ Task authorization expires with the task. Never promote it into workspace policy
 
 ## Launch Contract
 
-Give the host Agent the Envelope plus the effective rule sources. Specify outcomes and boundaries, not unnecessary implementation steps.
+Give the host Agent the resolved Envelope plus the effective rule sources. In the Launch Contract, `envelope.packs` is an identity-to-canonical-manifest-digest map rather than the Task Envelope's pre-resolution id list. This makes every requested Pack self-bound for schema-only consumers; `effectivePackManifests` retains the complete active Pack set. Specify outcomes and boundaries, not unnecessary implementation steps.
 
 ## Return Receipt
 
@@ -37,7 +37,7 @@ Compare the receipt with observable state. A mismatch keeps closeout incomplete.
 Record:
 
 - current and proposed adoption level;
-- explicitly selected Host Adapters and their support status;
+- deterministically resolved Host Adapters, their selection mode, and their support status;
 - exact target paths, operations, base SHA-256 digests, candidate content, and content digests;
 - required user confirmation and activation verification;
 - confirmed non-mutations.

package/scripts/lib/bundle.mjs

@@ -1,77 +0,0 @@
-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,
-  };
-}