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

package/scripts/shadow-comparison.mjs

@@ -87,7 +87,7 @@ for (const scenario of scenarios) {
 const result = {
   schemaVersion: "1.0",
   agwBaseline: "plugins/agent-workflow-governance@0.2.0-canonical",
-  forgeRailCandidate: "plugins/forgerail@0.1.0-alpha.1-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),

package/scripts/validate-release.mjs

@@ -6,9 +6,9 @@ import { fileURLToPath } from "node:url";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const expectedPackageName = "@echopath-labs/forgerail";
-const expectedVersion = "0.1.0-alpha.1";
+const expectedVersion = "0.1.0-alpha.2";
 const expectedTag = `v${expectedVersion}`;
-const expectedDate = "2026-08-13";
+const expectedDate = "2026-08-30";
 const expectedPlugins = [
   "forgerail",
   "forgerail-cross-workspace-orchestration",
@@ -47,7 +47,7 @@ record("package-lock-license", packageLock.packages?.[""]?.license === "Apache-2
 record("npm-next-tag", packageJson.publishConfig?.tag === "next", packageJson.publishConfig?.tag ?? null);
 record(
   "prepublish-gate",
-  ["npm test", "npm run test:shadow", "npm run test:release", "npm run test:consumer"].every((command) => packageJson.scripts?.prepublishOnly?.includes(command)),
+  ["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)),
   packageJson.scripts?.prepublishOnly ?? null,
 );
 
@@ -101,7 +101,7 @@ for (const name of expectedPlugins) {
 
 const installation = `${read("docs/installation.md")}\n${read("docs/installation.zh-CN.md")}`;
 for (const phrase of [
-  `codex plugin marketplace add echopath-labs/forgerail --ref ${expectedTag}`,
+  "codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.1",
   "codex plugin add forgerail@echopath-labs",
   "codex plugin add forgerail-cross-workspace-orchestration@echopath-labs",
   "codex plugin add forgerail-github-rulesets@echopath-labs",
@@ -136,8 +136,8 @@ record("package-adapters", packageJson.files?.includes("adapters/"), packageJson
 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.md");
-const releaseChinese = read("docs/release.zh-CN.md");
+const releaseEnglish = read("docs/release-alpha2.md");
+const releaseChinese = read("docs/release-alpha2.zh-CN.md");
 const releaseDocs = `${releaseEnglish}\n${releaseChinese}`;
 for (const phrase of [
   "remote_integration_approval",
@@ -146,7 +146,7 @@ for (const phrase of [
   expectedVersion,
   expectedTag,
   "Node.js 22 and 24",
-  "release/0.1.0-alpha.1",
+  "codex/forgerail-alpha2-scoped",
   "Do not unpublish",
   "AGW",
   "Host Binding Receipt",
@@ -156,17 +156,17 @@ for (const phrase of [
 }
 for (const [id, document, phrases] of [
   ["english", releaseEnglish, [
-    "The first public candidate must be an ordinary child of the observed public `main`.",
-    "an ordinary fast-forward successor of the current release head",
-    "the PR base and publication comparison baseline bound to the observed `main`",
-    "the resulting public `main` tree must equal the final signed projection tree",
+    "The public candidate is an ordinary child of the observed remote `main`.",
+    "an ordinary source-first successor commit",
+    "The Draft PR base and publication comparison baseline remain bound to the observed remote `main`",
+    "The merged public `main` tree must equal the final signed projection tree",
     "Install and discover each external Capability Pack separately",
   ]],
   ["chinese", releaseChinese, [
-    "首个公共候选必须是已观测 `main` 的普通子 commit。",
-    "当前 release head 的普通 fast-forward successor",
-    "PR base 与 publication comparison baseline 继续绑定已观测 `main`",
-    "公共 `main` tree 必须等于最终签名 projection tree",
+    "公共候选是已观测远端 `main` 的普通子 commit。",
+    "普通的 source-first successor commit",
+    "Draft PR base 与 publication comparison baseline 继续绑定已观测远端 `main`",
+    "合并后的公共 `main` tree 必须等于最终签名 projection tree",
     "每个外部 Capability Pack 分别安装与发现",
   ]],
 ]) {

package/scripts/validate-universal-directory.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { diagnoseWorkspace } from "./lib/diagnosis.mjs";
+
+const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const readJson = (path) => JSON.parse(readFileSync(path, "utf8"));
+const manifest = readJson(resolve(pluginRoot, ".codex-plugin/plugin.json"));
+const packageJson = readJson(resolve(pluginRoot, "package.json"));
+const candidate = readJson(resolve(pluginRoot, "directory/submission-candidate.json"));
+const evaluations = readJson(resolve(pluginRoot, "directory/evaluations.json"));
+const fixture = resolve(pluginRoot, "scripts/fixtures/workspaces/no-node-project");
+const checks = [];
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+  checks.push(message);
+}
+
+function hashTree(root) {
+  const entries = [];
+  function visit(current) {
+    for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = resolve(current, entry.name);
+      const rel = relative(root, full).split(sep).join("/");
+      if (entry.isDirectory()) visit(full);
+      else {
+        assert(!lstatSync(full).isSymbolicLink(), `fixture contains no symlink: ${rel}`);
+        const content = readFileSync(full);
+        entries.push({ path: rel, bytes: content.length, sha256: createHash("sha256").update(content).digest("hex") });
+      }
+    }
+  }
+  visit(root);
+  return entries;
+}
+
+function validateAsset(label, assetPath) {
+  assert(typeof assetPath === "string", `${label} is a string`);
+  assert(assetPath.startsWith("./assets/"), `${label} starts with ./assets/`);
+  assert(!assetPath.split("/").includes(".."), `${label} contains no parent traversal`);
+  const resolved = resolve(pluginRoot, assetPath);
+  assert(resolved.startsWith(`${pluginRoot}${sep}`), `${label} remains inside the Plugin root`);
+  assert(existsSync(resolved), `${label} exists`);
+  const svg = readFileSync(resolved, "utf8");
+  assert(svg.includes("<svg") && svg.includes("</svg>"), `${label} is parseable SVG source`);
+  assert(!/(?:href|src)\s*=\s*["'](?:https?:|data:)/i.test(svg), `${label} has no external or data URL`);
+}
+
+function validateMarkdownLinks(relativePath) {
+  const documentPath = resolve(pluginRoot, relativePath);
+  const markdown = readFileSync(documentPath, "utf8");
+  for (const match of markdown.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)) {
+    const target = match[1];
+    if (/^(?:https:\/\/|mailto:|#)/.test(target)) continue;
+    const withoutFragment = target.split("#")[0];
+    const resolved = resolve(dirname(documentPath), withoutFragment);
+    assert(resolved.startsWith(`${pluginRoot}${sep}`), `Markdown link remains in Plugin root: ${relativePath} -> ${target}`);
+    assert(existsSync(resolved), `Markdown link target exists: ${relativePath} -> ${target}`);
+  }
+}
+
+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.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(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");
+assert(candidate.plugin.coreRequirements.projectPackageJson === false, "Core requires no project package.json");
+assert(candidate.plugin.coreRequirements.projectNodeModules === false, "Core requires no project node_modules");
+assert(candidate.plugin.coreRequirements.npmCli === "optional", "npm CLI is optional");
+
+for (const skill of candidate.plugin.skills) {
+  assert(existsSync(resolve(pluginRoot, "skills", skill, "SKILL.md")), `declared Skill exists: ${skill}`);
+}
+assert(new Set(candidate.plugin.skills).size === candidate.plugin.skills.length, "declared Skill identities are unique");
+
+validateAsset("composerIcon", manifest.interface.composerIcon);
+validateAsset("logo", manifest.interface.logo);
+assert(manifest.interface.composerIcon === candidate.listing.composerIcon.value, "composer icon candidate matches manifest");
+assert(manifest.interface.logo === candidate.listing.logo.value, "logo candidate matches manifest");
+
+assert(candidate.listing.category.state === "confirmed_by_user" && candidate.listing.category.value === "Productivity", "Productivity category is user-confirmed");
+assert(candidate.listing.supportUrl.state === "confirmed_by_user" && candidate.listing.supportUrl.value === "https://github.com/echopath-labs/forgerail/issues", "GitHub Issues support URL is user-confirmed");
+assert(candidate.listing.privacyPolicyUrl.state === "confirmed_by_user" && candidate.listing.privacyPolicyUrl.value.endsWith("/PRIVACY.md"), "Privacy URL is user-confirmed and repository-owned");
+assert(candidate.listing.termsOfServiceUrl.state === "confirmed_by_user" && candidate.listing.termsOfServiceUrl.value.endsWith("/TERMS.md"), "Terms URL is user-confirmed and repository-owned");
+for (const field of ["websiteUrl", "supportUrl", "privacyPolicyUrl", "termsOfServiceUrl"]) {
+  const url = new URL(candidate.listing[field].value);
+  assert(url.protocol === "https:" && url.hostname === "github.com", `listing URL is confined to reviewed GitHub HTTPS origin: ${field}`);
+}
+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");
+
+const privacy = readFileSync(resolve(pluginRoot, "PRIVACY.md"), "utf8");
+const terms = readFileSync(resolve(pluginRoot, "TERMS.md"), "utf8");
+for (const phrase of ["Skills-only Agent Plugin", "does not operate its own server", "do not themselves collect, transmit, or store telemetry", "host Agent or platform", "external Capability Packs"]) {
+  assert(privacy.includes(phrase), `Privacy notice contains required boundary: ${phrase}`);
+}
+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"]) {
+  validateMarkdownLinks(path);
+}
+
+const requiredGates = [
+  "publisher_verified_identity",
+  "apps_management_write_permission",
+  "portal_region_enumeration",
+  "portal_asset_format_acceptance",
+  "exact_submission_public_source_confirmation"
+];
+assert(JSON.stringify(candidate.unresolvedGates) === JSON.stringify(requiredGates), "all external submission facts remain explicit gates");
+
+const positive = evaluations.cases.filter((item) => item.polarity === "positive");
+const negative = evaluations.cases.filter((item) => item.polarity === "negative");
+assert(positive.length >= 5, "evaluation set has at least five positive cases");
+assert(negative.length >= 3, "evaluation set has at least three negative cases");
+assert(new Set(evaluations.cases.map((item) => item.id)).size === evaluations.cases.length, "evaluation ids are unique");
+for (const item of positive) {
+  assert(Boolean(item.prompt && item.expectedBehavior && item.expectedResultShape?.length && item.fixture), `positive case is complete: ${item.id}`);
+}
+for (const item of negative) {
+  assert(Boolean(item.prompt && item.expectedFallback && item.reason && item.fixture), `negative case is complete: ${item.id}`);
+}
+for (const skill of candidate.plugin.skills) {
+  assert(positive.some((item) => item.skill === skill), `positive cases cover Skill: ${skill}`);
+}
+assert(!evaluations.cases.some((item) => /\/Users\/|secret|token=/i.test(item.prompt)), "evaluation prompts contain no private paths or credential material");
+
+assert(!existsSync(resolve(fixture, "package.json")), "fixture has no package.json");
+assert(!existsSync(resolve(fixture, "node_modules")), "fixture has no node_modules");
+assert(!existsSync(resolve(fixture, ".forgerail")), "fixture starts without .forgerail state");
+const before = hashTree(fixture);
+const diagnosis = diagnoseWorkspace(fixture);
+const after = hashTree(fixture);
+assert(diagnosis.mode === "read-only", "no-Node-project diagnosis is read-only");
+assert(diagnosis.mutations.length === 0, "no-Node-project diagnosis reports no mutation");
+assert(diagnosis.inheritedHabits.some((item) => item.type === "markdown-adr"), "no-Node-project diagnosis discovers Markdown ADR habit");
+assert(JSON.stringify(before) === JSON.stringify(after), "no-Node-project fixture remains byte-for-byte unchanged");
+assert(!existsSync(resolve(fixture, ".forgerail")), "diagnosis creates no .forgerail state");
+
+process.stdout.write(`${JSON.stringify({ status: "passed", checks: checks.length, positiveCases: positive.length, negativeCases: negative.length, skills: candidate.plugin.skills, fixture: "scripts/fixtures/workspaces/no-node-project", mutations: [] }, null, 2)}\n`);

package/skills/architecture-convergence-audit/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: architecture-convergence-audit
+description: Use when explicitly asked to find duplicate capability ownership, parallel state or recovery paths, premature abstractions, or the smallest remaining implementation boundary. Produces a read-only evidence-backed convergence audit; do not use for general workspace discovery or recurring health review.
+---
+
+# Architecture Convergence Audit
+
+Run independently when applicable. ForgeRail Core does not need to run first.
+Default to Analyze First, read-only operation, and `medium` risk.
+
+## Audit
+
+1. Bind the request to a reproducible baseline and state what freshness remains unverified.
+2. Map each requested outcome as `product invariant -> authoritative owner -> current implementation -> callers -> persistence/lifecycle -> validation evidence`.
+3. Trace suspected duplicate identity fences, state machines, parsers, adapters, compatibility paths, workers, recovery paths, schemas, and implementation-shaped tests to their durable fact owner and current consumer.
+4. Apply the retention burden: require accepted behavior or a real failure/concurrency scenario, why the existing owner is insufficient, the durable fact owner, a current or committed consumer, and a validation method.
+5. Separate confirmed redundancy from inference. Incomplete evidence returns an exact verification need, not a deletion claim.
+6. Return the smallest remaining independently useful vertical slices and a deletion-first consolidation plan that preserves required invariants and failure coverage.
+
+Do not infer redundancy from diff size, file count, test count, interface thinness,
+or abstraction count. Read `references/audit-contract.md` for ownership routing,
+required output, negative constraints, and acceptance rules.
+
+## Boundaries
+
+- Workspace Diagnosis discovers sources, habits, owner boundaries, commands, and dependency availability.
+- Workspace Health owns recurring stale, drift, orphan, debt, and recovery signals.
+- ForgeRail Core owns deterministic identity, authority, topology, revision, and Receipt invariants.
+- This Pack owns only bounded capability-owner duplication analysis and the convergence plan.
+- Project facts come from the existing Governance Source Inventory, Effective Profile, and Task Envelope. Do not create another Profile, adoption lifecycle, task ledger, Receipt, `.forgerail/` state, or writeback path.
+- Do not edit, delete, merge, release, deploy, publish, change lifecycle state, or create an external issue. The template in `assets/github-issue-template.md` is output material only and requires exact external-write authorization before use.

package/skills/architecture-convergence-audit/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Architecture Convergence Audit"
+  short_description: "Trace capability owners and minimize duplicate architecture."
+  brand_color: "#B45309"
+  default_prompt: "Use $architecture-convergence-audit to identify existing owners and the smallest remaining implementation without changing the workspace."
+policy:
+  allow_implicit_invocation: true

package/skills/architecture-convergence-audit/assets/github-issue-template.md

@@ -0,0 +1,26 @@
+## Architecture convergence candidate
+
+Baseline and freshness:
+
+Requested outcome:
+
+Authoritative owner and current implementation:
+
+Confirmed redundancy:
+
+Inferred redundancy and verification needed:
+
+Required invariants and failure coverage:
+
+Smallest remaining implementation boundary:
+
+Deletion or consolidation slices:
+
+Negative constraints:
+
+Validation and acceptance:
+
+Owner decisions required:
+
+This template is inert output material. Creating or changing an external issue
+requires separate authorization for the exact repository and content.

package/skills/architecture-convergence-audit/references/audit-contract.md

@@ -0,0 +1,62 @@
+# Architecture Convergence Audit Contract
+
+## Evidence and ownership
+
+Start from the selected task outcome, not the shape of the proposed code. For
+each outcome, identify:
+
+- the accepted behavior and failure or concurrency scenario;
+- the component that owns the durable fact;
+- current implementation and direct callers;
+- persistence, lifecycle, recovery, and compatibility responsibilities;
+- local validation, provider/CI evidence, deployment, and real-consumer proof;
+- freshness and any exact evidence still required.
+
+An interface that owns authorization, transactionality, substitution,
+anti-corruption, or failure isolation is not redundant merely because it is
+thin. A large cohesive slice is not overbuilt merely because it spans many
+files.
+
+## Duplication tests
+
+Investigate when evidence indicates two owners for the same:
+
+- canonical identity or normalization boundary;
+- durable state transition or lifecycle;
+- parser or source-of-truth interpretation;
+- compatibility or version negotiation path;
+- recovery, replay, rollback, or resume mechanism;
+- background worker coordination responsibility;
+- schema, projection, or generated-contract authority.
+
+Classify a finding as `confirmed` only when ownership and behavior are traced.
+Otherwise use `inferred` and name the smallest verification that can resolve it.
+
+## Required output
+
+Return:
+
+1. baseline, freshness, allowed scope, and explicit non-mutations;
+2. already-owned capability map;
+3. confirmed redundancy and inferred redundancy in separate sections;
+4. invariants and failure coverage that must remain;
+5. smallest remaining implementation boundary;
+6. deletion, consolidation, or deferral candidates;
+7. negative constraints and prohibited shortcuts;
+8. independently verifiable vertical slices;
+9. validation requirements and observable acceptance conditions;
+10. owner decisions or confirmations still required.
+
+Prefer deletion or consolidation before introducing a replacement abstraction.
+Tests that only encode an obsolete duplicate implementation may be removed,
+while tests that prove user-visible behavior, security, concurrency, data, or
+operational invariants remain.
+
+## Routing and stopping conditions
+
+- Route source discovery to Workspace Diagnosis.
+- Route recurring stale or drift assessment to Workspace Health.
+- Route deterministic transition decisions to ForgeRail Core.
+- Stop with inference when callers, durable fact ownership, or current behavior cannot be verified.
+- Do not block an otherwise safe functional path solely for incomplete convergence evidence.
+- Any mutation or external tracker operation requires a separate exact target, content, authority, and validation boundary.

package/skills/workspace-health-review/references/health-review.md

@@ -12,6 +12,21 @@ Review the smallest useful evidence for:
 - release or production rules mixed into generic workflow guidance;
 - hidden durable mutation without human approval.
 
+Also report these as recurring Health signals when bounded evidence exists:
+
+- stale or unclaimed worktrees and worktrees whose recovery owner is unknown;
+- active specification records that conflict with delivered behavior or remain active after completion;
+- stale governance links, superseded ADR references, and generated artifacts that drift from their declared source;
+- declared CI topology that differs from provider-observed topology, while keeping unavailable provider evidence unavailable;
+- compatibility, test, or abstraction growth whose current consumer and recovery value are unclear;
+- runner qualification evidence made stale by a relevant configuration or trust-boundary change.
+
+Health observes recurring drift, debt, orphaning, and recovery cost. It does not
+discover the workspace from scratch, mint authority, evaluate a protected
+transition, or decide that an implementation layer is redundant. Route those
+questions to Workspace Diagnosis, ForgeRail Core, or an explicitly invoked
+architecture convergence audit respectively.
+
 Prefer categorical status. Recommendations are:
 
 - `P0`: blocks high-risk work or safe recovery;