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

package/scripts/lib/diagnosis.mjs

@@ -1,65 +1,173 @@
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import {
+  lstatSync,
+  opendirSync,
+  realpathSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadHostAdapters } from "./adoption.mjs";
+import { inspectBoundedPath } from "./bounded-read.mjs";
+
+const defaultPluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const maximumDiagnosticDirectoryEntries = 4096;
 
 function observed(id, source, value) {
   return { id, kind: "observed_fact", source, value };
 }
 
-function safeJson(path) {
-  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+function confined(root, target) {
+  const value = relative(root, target);
+  return value === "" || (
+    !isAbsolute(value)
+    && !/^[a-zA-Z]:/.test(value)
+    && value !== ".."
+    && !value.startsWith(`..${sep}`)
+    && !value.startsWith("/")
+  );
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
 }
 
-function hasMarkdown(directory) {
-  if (!existsSync(directory) || !statSync(directory).isDirectory()) return false;
-  return readdirSync(directory, { withFileTypes: true }).some((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"));
+function safeJson(root, path) {
+  const inspected = inspectBoundedPath(root, path, { finalKind: "file", read: true });
+  if (inspected.state === "absent") return { state: "absent", value: null, error: null };
+  if (inspected.state !== "available") return { state: "unavailable", value: null, error: inspected.state };
+  try {
+    const value = JSON.parse(inspected.content);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return { state: "malformed", value: null, error: "invalid-root-shape" };
+    }
+    return { state: "available", value, error: null };
+  } catch (error) {
+    return { state: "malformed", value: null, error: error instanceof SyntaxError ? "invalid-json" : "unreadable" };
+  }
 }
 
-export function diagnoseWorkspace(workspace) {
-  const root = resolve(workspace);
-  if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error("workspace must be an existing directory");
+function hasMarkdownRecord(root, path) {
+  const inspected = inspectBoundedPath(root, path, { finalKind: "directory" });
+  if (inspected.state !== "available") return false;
+  const directory = resolve(root, path);
+  let before;
+  let observed;
+  let handle;
+  try {
+    before = lstatSync(directory);
+    observed = realpathSync(directory);
+    const after = lstatSync(observed);
+    if (!confined(root, observed) || after.isSymbolicLink() || !sameFile(before, after) || !after.isDirectory()) return false;
+    handle = opendirSync(observed);
+    const openedObserved = realpathSync(directory);
+    const opened = lstatSync(openedObserved);
+    if (openedObserved !== observed || !confined(root, openedObserved) || !sameFile(after, opened) || !opened.isDirectory()) return false;
+    const names = [];
+    while (true) {
+      const entry = handle.readSync();
+      if (entry === null) break;
+      if (names.length >= maximumDiagnosticDirectoryEntries) return false;
+      names.push(entry.name);
+    }
+    const finalObserved = realpathSync(directory);
+    const final = lstatSync(finalObserved);
+    if (finalObserved !== observed || !confined(root, finalObserved) || !sameFile(after, final) || !final.isDirectory()) return false;
+    return names.some((name) => typeof name === "string"
+      && name.toLowerCase().endsWith(".md")
+      && inspectBoundedPath(root, `${path}/${name}`, { finalKind: "file", verify: true }).state === "available");
+  } catch {
+    return false;
+  } finally {
+    try { handle?.closeSync(); } catch {}
+  }
+}
+
+export function diagnoseWorkspace(workspace, pluginRoot = defaultPluginRoot) {
+  let root;
+  try { root = realpathSync(resolve(workspace)); }
+  catch { throw new Error("workspace must be an existing directory"); }
+  const rootMetadata = lstatSync(root);
+  if (rootMetadata.isSymbolicLink() || !rootMetadata.isDirectory()) throw new Error("workspace must be an existing directory");
+  const registry = loadHostAdapters(pluginRoot);
+  if (!registry.valid) throw new Error(`host adapter registry is invalid: ${registry.errors.join("; ")}`);
   const evidence = [];
   const recommendations = [];
   const confirmationRequired = [];
+  const gaps = [];
+
+  const hostAdapters = registry.adapters.map((adapter) => {
+    const binding = inspectBoundedPath(root, adapter.bindingTarget, { finalKind: "file", read: true });
+    const detected = adapter.detectionTargets.some((path) => inspectBoundedPath(root, path).present);
+    if (binding.present && binding.state !== "available") gaps.push(`host-binding-unavailable:${adapter.id}`);
+    return {
+      id: adapter.id,
+      status: adapter.status,
+      target: adapter.bindingTarget,
+      observed: detected || binding.present,
+      readState: binding.state,
+      managedBindingObserved: binding.state === "available" && binding.content.includes(`<!-- ${adapter.managedMarker}:start -->`),
+    };
+  });
 
-  for (const entry of ["AGENTS.md", "CLAUDE.md", ".cursor/rules/forgerail.mdc", ".github/copilot-instructions.md", "README.md"]) {
-    if (existsSync(resolve(root, entry))) evidence.push(observed(`instructions:${entry}`, entry, "available"));
+  for (const adapter of hostAdapters) {
+    if (adapter.readState === "available") evidence.push(observed(`instructions:${adapter.target}`, adapter.target, "available"));
+  }
+  if (inspectBoundedPath(root, "README.md", { finalKind: "file" }).state === "available") {
+    evidence.push(observed("instructions:README.md", "README.md", "available"));
   }
 
-  const hostAdapters = [
-    { id: "codex", status: "supported", target: "AGENTS.md", observed: existsSync(resolve(root, "AGENTS.md")) },
-    { id: "claude-code", status: "profile-only", target: "CLAUDE.md", observed: existsSync(resolve(root, "CLAUDE.md")) },
-    { id: "cursor", status: "profile-only", target: ".cursor/rules/forgerail.mdc", observed: existsSync(resolve(root, ".cursor/rules/forgerail.mdc")) },
-  ];
-  const managedBindingObserved = hostAdapters.some((adapter) => {
-    if (!adapter.observed) return false;
-    try { return readFileSync(resolve(root, adapter.target), "utf8").includes(`forgerail:binding:${adapter.id}:v1:start`); } catch { return false; }
-  });
-  const adoptionLevel = existsSync(resolve(root, ".forgerail"))
-    ? "persisted-governance"
-    : existsSync(resolve(root, "FORGERAIL.md")) || managedBindingObserved
-      ? "lightweight-adoption"
-      : "plugin-only";
-  evidence.push(observed("host-adapters", "bounded host instruction paths", hostAdapters));
+  const managedBindingObserved = hostAdapters.some((adapter) => adapter.managedBindingObserved);
+  const persisted = inspectBoundedPath(root, ".forgerail").state === "available";
+  const portableContract = inspectBoundedPath(root, "FORGERAIL.md", { finalKind: "file" }).state === "available";
+  const adoptionLevel = persisted ? "persisted-governance" : portableContract || managedBindingObserved ? "lightweight-adoption" : "plugin-only";
+  evidence.push(observed("host-adapters", "registry-owned bounded host instruction paths", hostAdapters));
   evidence.push(observed("forgerail-adoption-level", "bounded ForgeRail markers", adoptionLevel));
 
   const recordSystems = [];
-  if (existsSync(resolve(root, "openspec"))) recordSystems.push({ type: "openspec", source: "openspec/" });
-  if (existsSync(resolve(root, ".specify")) || existsSync(resolve(root, "specs"))) recordSystems.push({ type: "spec-kit-or-spec-directory", source: existsSync(resolve(root, ".specify")) ? ".specify/" : "specs/" });
+  if (inspectBoundedPath(root, "openspec").state === "available") recordSystems.push({ type: "openspec", source: "openspec/" });
+  const specify = inspectBoundedPath(root, ".specify").state === "available";
+  const specs = inspectBoundedPath(root, "specs").state === "available";
+  if (specify || specs) recordSystems.push({ type: "spec-kit-or-spec-directory", source: specify ? ".specify/" : "specs/" });
   for (const directory of ["docs/adr", "docs/adrs", "adr", "adrs", "decisions"]) {
-    if (hasMarkdown(resolve(root, directory))) recordSystems.push({ type: "markdown-adr", source: `${directory}/` });
+    if (hasMarkdownRecord(root, directory)) recordSystems.push({ type: "markdown-adr", source: `${directory}/` });
   }
-  if (hasMarkdown(resolve(root, "docs")) && recordSystems.length === 0) recordSystems.push({ type: "markdown-docs", source: "docs/" });
+  if (hasMarkdownRecord(root, "docs") && recordSystems.length === 0) recordSystems.push({ type: "markdown-docs", source: "docs/" });
   evidence.push(observed("record-systems", "bounded well-known paths", recordSystems));
 
-  const packageJsonPath = resolve(root, "package.json");
-  const packageJson = existsSync(packageJsonPath) ? safeJson(packageJsonPath) : null;
-  if (packageJson) evidence.push(observed("package-scripts", "package.json", Object.keys(packageJson.scripts ?? {}).sort()));
+  const packageJson = safeJson(root, "package.json");
+  if (packageJson.state === "available") evidence.push(observed("package-scripts", "package.json", Object.keys(packageJson.value.scripts ?? {}).sort()));
+  else if (packageJson.state === "malformed" || packageJson.state === "unavailable") {
+    const state = packageJson.state === "malformed" ? "malformed" : "unavailable";
+    evidence.push(observed("package-metadata", "package.json", { state, reason: packageJson.error }));
+    gaps.push(packageJson.state === "malformed" ? "package-metadata-malformed" : "package-metadata-unavailable");
+    recommendations.push({
+      kind: "recommendation",
+      priority: "P1",
+      reason: packageJson.state === "malformed"
+        ? "package.json exists but is not usable as object metadata."
+        : "package.json is not a bounded readable regular file.",
+      options: [packageJson.state === "malformed"
+        ? "repair package.json before relying on package-script observations"
+        : "replace the unsafe package.json entry with a reviewed regular file before relying on package-script observations"],
+    });
+    confirmationRequired.push("Confirm whether unavailable package metadata should block the intended task.");
+  }
+
+  if (gaps.some((gap) => gap.startsWith("host-binding-unavailable:"))) {
+    recommendations.push({
+      kind: "recommendation",
+      priority: "P1",
+      reason: "One or more registered Host bindings are present but cannot be read within the no-follow regular-file boundary.",
+      options: ["inspect the named Host binding and replace unsafe entries only after human confirmation"],
+    });
+    confirmationRequired.push("Confirm how each unavailable Host binding should be repaired before adoption.");
+  }
 
-  if (existsSync(resolve(root, ".git"))) evidence.push(observed("git-root", ".git/", "available"));
-  const skillRoots = [".codex/skills", ".agents/skills"].filter((path) => existsSync(resolve(root, path)));
+  if (inspectBoundedPath(root, ".git").state === "available") evidence.push(observed("git-root", ".git/", "available"));
+  const skillRoots = [".codex/skills", ".agents/skills"].filter((path) => inspectBoundedPath(root, path).state === "available");
   evidence.push(observed("skill-roots", "bounded well-known paths", skillRoots));
 
   if (recordSystems.length === 0) {
+    gaps.push("durable-record-practice-not-observed");
     recommendations.push({
       kind: "recommendation",
       priority: "P1",
@@ -73,10 +181,9 @@ export function diagnoseWorkspace(workspace) {
     schemaVersion: "1.0",
     mode: "read-only",
     workspace: basename(root),
-    workspacePath: root,
     evidence,
     inheritedHabits: recordSystems,
-    gaps: recordSystems.length === 0 ? ["durable-record-practice-not-observed"] : [],
+    gaps,
     recommendations,
     confirmationRequired,
     mutations: [],
@@ -85,7 +192,7 @@ export function diagnoseWorkspace(workspace) {
       recommendedLevel: adoptionLevel,
       changeRecommended: false,
       reason: "ForgeRail keeps the minimum observed adoption level unless the user requests durable adoption or concrete evidence justifies escalation.",
-      planCommandAvailable: "forgerail adoption-plan --workspace . --host codex",
+      planCommandAvailable: "forgerail adoption-plan --workspace .",
       persistedGovernanceGeneration: "deferred",
     },
     fullHealthReviewRecommended: evidence.filter((item) => item.id.startsWith("instructions:")).length > 2,

package/scripts/shadow-comparison.mjs

@@ -2,7 +2,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const core = readFileSync(resolve(root, "skills/forgerail/SKILL.md"), "utf8");
@@ -23,76 +23,94 @@ function externalSkill(plugin, skill = plugin) {
 const rulesets = externalSkill("forgerail-github-rulesets");
 const releaseSafety = externalSkill("forgerail-release-safety");
 const threadClosure = externalSkill("forgerail-thread-closure");
-const agwEvidence = frozen.behaviorAssertions;
+const expectedAgwEvidence = Object.freeze({
+  featureBranchRecords: ["smallest child workspace", "durable records", "git status"],
+  dirtyWorktreePreservation: ["Preserve user changes"],
+  existingRecordHabit: ["existing durable record system"],
+  workspaceHealth: ["Workspace Health Review"],
+  githubRulesets: ["project-specific workflow or safety checklist"],
+  releaseSafety: ["project-specific release or operations checklist"],
+  threadClosure: ["machine-readable closeout"],
+});
 
-const scenarios = [
+const scenarioDefinitions = [
   {
     id: "feature-branch-records",
-    agwEvidence: agwEvidence.featureBranchRecords,
+    agwEvidence: expectedAgwEvidence.featureBranchRecords,
     forgerailEvidence: ["smallest owner workspace", "Task Envelope", "existing habits"],
-    source: `${agwEvidence.featureBranchRecords.join("\n")}\n${core}\n${diagnosis}`,
+    source: `${core}\n${diagnosis}`,
     status: "covered",
   },
   {
     id: "dirty-worktree-preservation",
-    agwEvidence: agwEvidence.dirtyWorktreePreservation,
+    agwEvidence: expectedAgwEvidence.dirtyWorktreePreservation,
     forgerailEvidence: ["preserve unrelated user changes", "dirty-worktree state"],
-    source: `${agwEvidence.dirtyWorktreePreservation.join("\n")}\n${core}`,
+    source: core,
     status: "covered",
   },
   {
     id: "markdown-existing-habit",
-    agwEvidence: agwEvidence.existingRecordHabit,
+    agwEvidence: expectedAgwEvidence.existingRecordHabit,
     forgerailEvidence: ["existing habits", "OpenSpec may be a preferred example"],
-    source: `${agwEvidence.existingRecordHabit.join("\n")}\n${diagnosis}`,
+    source: diagnosis,
     status: "covered",
   },
   {
     id: "workspace-health",
-    agwEvidence: agwEvidence.workspaceHealth,
+    agwEvidence: expectedAgwEvidence.workspaceHealth,
     forgerailEvidence: ["first built-in ForgeRail Capability Pack", "Analyze First"],
-    source: `${agwEvidence.workspaceHealth.join("\n")}\n${health}`,
+    source: health,
     status: "covered-with-follow-up",
   },
   {
     id: "github-rulesets-read-first",
-    agwEvidence: agwEvidence.githubRulesets,
+    agwEvidence: expectedAgwEvidence.githubRulesets,
     forgerailEvidence: ["read-only diagnosis", "Stop until the user explicitly approves"],
-    source: `${agwEvidence.githubRulesets.join("\n")}\n${rulesets}`,
+    source: rulesets,
     status: "covered",
   },
   {
     id: "release-safety-project-runbook",
-    agwEvidence: agwEvidence.releaseSafety,
+    agwEvidence: expectedAgwEvidence.releaseSafety,
     forgerailEvidence: ["project-owned release runbook", "does not contain publish, deploy"],
-    source: `${agwEvidence.releaseSafety.join("\n")}\n${releaseSafety}`,
+    source: releaseSafety,
     status: "covered",
   },
   {
     id: "evidence-first-thread-closure",
-    agwEvidence: agwEvidence.threadClosure,
+    agwEvidence: expectedAgwEvidence.threadClosure,
     forgerailEvidence: ["Keep closeout incomplete", "Do not implement follow-up work"],
-    source: `${agwEvidence.threadClosure.join("\n")}\n${core}\n${threadClosure}`,
+    source: `${core}\n${threadClosure}`,
     status: "covered",
   },
 ];
 
-for (const scenario of scenarios) {
-  scenario.missingAgw = scenario.agwEvidence.filter((phrase) => !scenario.source.toLocaleLowerCase("en-US").includes(phrase.toLocaleLowerCase("en-US")));
-  scenario.missingForgeRail = scenario.forgerailEvidence.filter((phrase) => !scenario.source.toLocaleLowerCase("en-US").includes(phrase.toLocaleLowerCase("en-US")));
-  scenario.passed = scenario.missingAgw.length === 0 && scenario.missingForgeRail.length === 0 && scenario.status !== "unresolved";
-  delete scenario.source;
+export function evaluateShadowComparison(overrides = {}, baseline = frozen) {
+  const baselineSource = JSON.stringify(baseline);
+  const scenarios = scenarioDefinitions.map((definition) => {
+    const source = overrides[definition.id] ?? definition.source;
+    const scenario = { ...definition };
+    scenario.missingAgw = scenario.agwEvidence.filter((phrase) => !baselineSource.toLocaleLowerCase("en-US").includes(phrase.toLocaleLowerCase("en-US")));
+    scenario.missingForgeRail = scenario.forgerailEvidence.filter((phrase) => !source.toLocaleLowerCase("en-US").includes(phrase.toLocaleLowerCase("en-US")));
+    scenario.passed = scenario.missingAgw.length === 0 && scenario.missingForgeRail.length === 0 && scenario.status !== "unresolved";
+    delete scenario.source;
+    return scenario;
+  });
+  return {
+    schemaVersion: "1.0",
+    agwBaseline: "plugins/agent-workflow-governance@0.2.0-canonical",
+    forgeRailCandidate: "plugins/forgerail@0.1.0-alpha.4-canonical",
+    scenarios,
+    covered: scenarios.filter((item) => item.passed).length,
+    unresolved: scenarios.filter((item) => !item.passed).map((item) => item.id),
+    behaviorCoverageReady: scenarios.every((item) => item.passed),
+    migrationReady: false,
+    migrationBlockers: ["real compatibility-period canaries are incomplete", "AGW lifecycle change is not approved"],
+  };
 }
 
-const result = {
-  schemaVersion: "1.0",
-  agwBaseline: "plugins/agent-workflow-governance@0.2.0-canonical",
-  forgeRailCandidate: "plugins/forgerail@0.1.0-alpha.2-canonical",
-  scenarios,
-  covered: scenarios.filter((item) => item.passed).length,
-  unresolved: scenarios.filter((item) => !item.passed).map((item) => item.id),
-  behaviorCoverageReady: scenarios.every((item) => item.passed),
-  migrationReady: false,
-  migrationBlockers: ["usable ForgeRail prerelease is not published", "real compatibility-period canaries are incomplete", "AGW lifecycle change is not approved"],
-};
-console.log(JSON.stringify(result, null, 2));
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const result = evaluateShadowComparison();
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.behaviorCoverageReady) process.exitCode = 1;
+}

package/scripts/validate-open-source-docs.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, extname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const checks = [];
+const failures = [];
+
+const requiredFiles = [
+  "README.md",
+  "README.zh-CN.md",
+  "CONTRIBUTING.md",
+  "SECURITY.md",
+  "CODE_OF_CONDUCT.md",
+  "SUPPORT.md",
+  "LICENSE",
+  "docs/installation.md",
+  "docs/installation.zh-CN.md",
+  "docs/adoption.md",
+  "docs/adoption.zh-CN.md",
+  "docs/composable-autonomy.zh-CN.md",
+  ".github/PULL_REQUEST_TEMPLATE.md",
+  ".github/ISSUE_TEMPLATE/bug_report.yml",
+  ".github/ISSUE_TEMPLATE/feature_request.yml",
+  ".github/ISSUE_TEMPLATE/documentation.yml",
+  ".github/ISSUE_TEMPLATE/config.yml"
+];
+
+const publicTextFiles = requiredFiles.filter((path) => extname(path) === ".md" || extname(path) === ".yml");
+const entryFiles = ["README.md", "README.zh-CN.md", "docs/installation.md", "docs/installation.zh-CN.md", "docs/adoption.md", "docs/adoption.zh-CN.md"];
+const issueForms = [
+  ".github/ISSUE_TEMPLATE/bug_report.yml",
+  ".github/ISSUE_TEMPLATE/feature_request.yml",
+  ".github/ISSUE_TEMPLATE/documentation.yml"
+];
+const skills = ["$forgerail", "$forgerail-workspace-diagnosis", "$workspace-health-review", "$architecture-convergence-audit"];
+const exactInstall = "codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.4";
+
+function record(condition, message) {
+  if (!condition) failures.push(message);
+  else checks.push(message);
+}
+
+function read(relativePath) {
+  return readFileSync(resolve(pluginRoot, relativePath), "utf8");
+}
+
+function classify(kind, content, base = pluginRoot) {
+  const errors = [];
+  if (kind === "release-text") {
+    if (/current[^\n]{0,80}(?:alpha\.2|0\.1\.0-alpha\.2)|install[^\n]{0,80}v0\.1\.0-alpha\.2/i.test(content)) errors.push("stale-release");
+  }
+  if (kind === "markdown-link") {
+    for (const match of content.matchAll(/\[[^\]]+\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g)) {
+      const target = match[1];
+      if (/^(?:https?:\/\/|mailto:|#)/.test(target)) continue;
+      const path = decodeURIComponent(target.split("#")[0]);
+      if (!path) continue;
+      const resolved = resolve(base, path);
+      if (!resolved.startsWith(`${pluginRoot}${sep}`) || !existsSync(resolved)) errors.push("broken-link");
+    }
+  }
+  if (kind === "issue-form") {
+    if (!/^name:\s*\S.+$/m.test(content) || !/^description:\s*\S.+$/m.test(content)) errors.push("invalid-issue-metadata");
+    if (/current alpha\.3 documentation|example v0\.1\.0-alpha\.3/i.test(content)) errors.push("stale-issue-version");
+  }
+  if (kind === "public-text") {
+    if (/\/Users\/|\.codex\/worktrees\/|[A-Za-z]:\\Users\\/.test(content)) errors.push("private-path");
+    if (/openspec\/changes\/|canonical private source workspace|active change[^\n]{0,80}tasks\.md|inventory\/[^\s`)]+-\d{8}\.md/i.test(content)) {
+      errors.push("private-process-reference");
+    }
+  }
+  if (kind === "no-node-claim") {
+    const lines = content.split(/\r?\n/);
+    const requiresProjectNode = lines.some((line) => {
+      if (!/(?:project|workspace)[^\n]{0,80}(?:requires?|must have|needs?)[^\n]{0,40}Node\.js/i.test(line)) return false;
+      return !/(?:does not|doesn't|do not|don't|no project-local|不要求|不需要|无需)/i.test(line);
+    });
+    if (/(?:before|to) (?:use|using|install)[^\n]{0,100}(?:initialize|create|add)[^\n]{0,40}package\.json/i.test(content) || requiresProjectNode) errors.push("project-node-required");
+  }
+  return [...new Set(errors)].sort();
+}
+
+for (const path of requiredFiles) record(existsSync(resolve(pluginRoot, path)), `required public file exists: ${path}`);
+
+for (const path of entryFiles) {
+  const content = read(path);
+  record(content.includes("0.1.0-alpha.4") && content.includes("v0.1.0-alpha.4"), `released alpha.4 identity is explicit: ${path}`);
+  record(!classify("release-text", content).includes("stale-release"), `no stale alpha.2 current-install claim: ${path}`);
+  record(classify("public-text", content).length === 0, `no private path: ${path}`);
+  record(classify("markdown-link", content, dirname(resolve(pluginRoot, path))).length === 0, `relative Markdown links resolve: ${path}`);
+}
+
+for (const path of ["README.md", "README.zh-CN.md", "docs/installation.md", "docs/installation.zh-CN.md"]) {
+  const content = read(path);
+  record(content.includes(exactInstall), `exact alpha.4 Marketplace command is present: ${path}`);
+  for (const skill of skills) record(content.includes(skill), `${path} covers ${skill}`);
+}
+
+for (const path of ["README.md", "README.zh-CN.md", "docs/installation.md", "docs/installation.zh-CN.md"]) {
+  const content = read(path);
+  record(/does not (?:require|need)|不要求|不需要/.test(content) && content.includes("package.json") && content.includes("node_modules") && content.includes(".forgerail/"), `Plugin Only no-project-Node boundary is explicit: ${path}`);
+  record(classify("no-node-claim", content).length === 0, `no accidental project Node requirement: ${path}`);
+}
+
+for (const path of publicTextFiles) {
+  const content = read(path);
+  record(classify("public-text", content).length === 0, `public text has no private path or process reference: ${path}`);
+}
+
+for (const path of issueForms) {
+  record(classify("issue-form", read(path)).length === 0, `issue form has current version, name, and description: ${path}`);
+}
+
+const fixtures = JSON.parse(read("scripts/fixtures/open-source-docs/cases.json"));
+record(fixtures.schemaVersion === "1.0" && Array.isArray(fixtures.cases), "documentation fixture schema is valid");
+for (const fixture of fixtures.cases) {
+  const base = fixture.kind === "markdown-link" ? resolve(pluginRoot, "scripts/fixtures/open-source-docs") : pluginRoot;
+  const content = fixture.content.replace("__PRIVATE_USER_PATH__", ["", "Users", "example", ".codex", "worktrees", "private", "project"].join("/"));
+  const actual = classify(fixture.kind, content, base);
+  const expected = [...fixture.expectedErrors].sort();
+  record(JSON.stringify(actual) === JSON.stringify(expected), `fixture fails closed as expected: ${fixture.id}`);
+}
+
+if (failures.length > 0) {
+  console.error(JSON.stringify({ status: "failed", checks: checks.length, failures }, null, 2));
+  process.exit(1);
+}
+
+console.log(JSON.stringify({ status: "passed", checks: checks.length, fixtures: fixtures.cases.length }, null, 2));