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

package/SUPPORT.md

@@ -0,0 +1,37 @@
+# ForgeRail Support
+
+ForgeRail is alpha software maintained as an open-source project. Support is best effort; no response-time or resolution-time service level is promised.
+
+## Start here
+
+1. Read the [README](README.md) and [installation guide](docs/installation.md).
+2. Confirm you installed the exact public tag `v0.1.0-alpha.4`.
+3. Start a new Codex task and verify the four ForgeRail Skills.
+4. Reproduce the problem with Plugin Only and a read-only request when possible.
+5. Remove secrets, private paths, project memory, customer data, and production configuration before sharing evidence.
+
+## Where to ask
+
+- **Reproducible bug:** use the Bug report issue form.
+- **Feature or product proposal:** use the Feature request form and explain the user problem before the proposed mechanism.
+- **Documentation problem:** use the Documentation issue form.
+- **Security vulnerability:** do not open a normal issue; follow [SECURITY.md](SECURITY.md).
+- **Conduct concern:** follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+The issue tracker is not a place to request access to private repositories, share API keys, ask maintainers to operate production systems, or bypass a human approval boundary.
+
+## Include useful evidence
+
+Share the ForgeRail version, Codex/host version, operating system, installation route, exact Skill invoked, expected result, observed result, and the smallest sanitized reproduction. State whether the workspace changed and whether any remote action occurred.
+
+Screenshots and receipts must be redacted. Prefer copied error text over an image when it does not expose private data.
+
+## Current support boundary
+
+- Codex is the verified host for `0.1.0-alpha.4`.
+- Claude Code and Cursor are `profile-only`; end-to-end support is not claimed.
+- Plugin Only and reviewed Lightweight Adoption are usable; persisted `.forgerail/` governance is deferred.
+- Capability Packs are independent Plugins and keep their own identity, permissions, and approval requirements.
+- Universal Plugins Directory publication is not currently available; exact-tag Marketplace installation is the supported route.
+
+If your case falls outside this boundary, an issue can still be useful as product evidence, but it may not receive an immediate fix.

package/adapters/claude-code.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": {

package/adapters/codex.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/adapters/cursor.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": {

package/contracts/adoption-plan.schema.json

@@ -2,45 +2,66 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://forgerail.dev/schemas/adoption-plan-v1.json",
   "title": "ForgeRail Adoption Plan",
+  "$comment": "Before approval or applying any write, validate the complete plan with ForgeRail validateContract('adoption-plan', plan). Runtime validation additionally rejects case-folded duplicate and ancestor/descendant target paths and reserved shared-contract collisions; standard JSON Schema cannot compare arbitrary path strings across entries.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "planId", "workspace", "currentLevel", "proposedLevel", "strategy", "evidence", "hosts", "proposedWrites", "requiredConfirmation", "verification", "confirmedNonMutations", "mutations", "status"],
+  "required": ["schemaVersion", "planId", "workspace", "currentLevel", "proposedLevel", "strategy", "hostSelection", "evidence", "proposedWrites", "requiredConfirmation", "verification", "confirmedNonMutations", "mutations", "status"],
   "properties": {
     "schemaVersion": { "const": "1.0" },
-    "planId": { "type": "string", "pattern": "^[a-zA-Z0-9._:-]+$" },
+    "planId": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]+$" },
     "workspace": { "type": "string", "minLength": 1 },
     "currentLevel": { "enum": ["plugin-only", "lightweight-adoption", "persisted-governance"] },
     "proposedLevel": { "enum": ["plugin-only", "lightweight-adoption", "persisted-governance"] },
     "strategy": { "enum": ["no-change", "single-host-managed-block", "shared-contract-with-thin-bindings"] },
-    "evidence": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
-    "hosts": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["adapterId", "status", "bindingTarget", "verificationMode"],
-        "properties": {
-          "adapterId": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" },
-          "status": { "enum": ["supported", "profile-only"] },
-          "bindingTarget": { "type": "string", "minLength": 1 },
-          "verificationMode": { "enum": ["new-task-discovery", "profile-only"] }
+    "hostSelection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "hosts"],
+      "properties": {
+        "mode": { "enum": ["explicit", "all-detected", "all-available"] },
+        "hosts": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": { "pattern": "^[a-z][a-z0-9-]+$" },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["status", "bindingTarget", "verificationMode"],
+            "properties": {
+              "status": { "enum": ["supported", "profile-only"] },
+              "bindingTarget": { "type": "string", "minLength": 1, "pattern": "^(?![\\\\/])(?![a-zA-Z]:)(?!.*//)(?!.*(?:^|/)\\.(?:/|$))(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*(?:^|/)[^/]*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.|/|$))(?!.*/$)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$" },
+              "verificationMode": { "enum": ["new-task-discovery", "profile-only"] }
+            },
+            "allOf": [
+              {
+                "if": { "properties": { "status": { "const": "supported" } }, "required": ["status"] },
+                "then": { "properties": { "verificationMode": { "const": "new-task-discovery" } } }
+              },
+              {
+                "if": { "properties": { "status": { "const": "profile-only" } }, "required": ["status"] },
+                "then": { "properties": { "verificationMode": { "const": "profile-only" } } }
+              }
+            ]
+          }
         }
       }
     },
+    "evidence": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
     "proposedWrites": {
       "type": "array",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["path", "operation", "baseSha256", "contentSha256", "content", "managedMarker"],
+        "required": ["workspaceSha256", "path", "operation", "baseSha256", "contentSha256", "content", "managedMarker", "approvalSha256"],
         "properties": {
-          "path": { "type": "string", "minLength": 1 },
+          "workspaceSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+          "path": { "type": "string", "minLength": 1, "pattern": "^(?![\\\\/])(?![a-zA-Z]:)(?!.*//)(?!.*(?:^|/)\\.(?:/|$))(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*(?:^|/)[^/]*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.|/|$))(?!.*/$)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$" },
           "operation": { "enum": ["create", "append-managed-block", "replace-managed-block"] },
           "baseSha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$" },
           "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
           "content": { "type": "string", "minLength": 1 },
-          "managedMarker": { "type": "string", "pattern": "^forgerail:(binding:[a-z][a-z0-9-]+|adoption-contract):v1$" }
+          "managedMarker": { "type": "string", "pattern": "^forgerail:(binding:[a-z][a-z0-9-]+|adoption-contract):v1$" },
+          "approvalSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
         }
       }
     },

package/contracts/effective-profile.schema.json

@@ -25,13 +25,13 @@
       }
     },
     "packs": {
-      "type": "array",
-      "items": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]+$" },
+      "additionalProperties": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "state", "reason"],
+        "required": ["state", "reason"],
         "properties": {
-          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" },
           "state": { "enum": ["available", "recommended", "enabled", "required", "blocked", "disabled"] },
           "reason": { "type": "string", "minLength": 1 }
         }

package/contracts/host-adapter.schema.json

@@ -4,7 +4,7 @@
   "title": "ForgeRail Host Adapter",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "id", "displayName", "status", "instructionDiscovery", "skillDiscovery", "bindingTarget", "bindingModes", "managedMarker", "activationBoundary", "verification", "limitations"],
+  "required": ["schemaVersion", "id", "displayName", "status", "instructionDiscovery", "skillDiscovery", "bindingTarget", "detectionTargets", "bindingModes", "bindingTemplates", "unmanagedBindingPolicy", "managedMarker", "activationBoundary", "verification", "limitations"],
   "properties": {
     "schemaVersion": { "const": "1.0" },
     "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" },
@@ -12,13 +12,29 @@
     "status": { "enum": ["supported", "profile-only"] },
     "instructionDiscovery": { "enum": ["task-start", "rules", "explicit-only", "unknown"] },
     "skillDiscovery": { "enum": ["agent-plugin-skills", "agent-skills", "explicit-only", "unknown"] },
-    "bindingTarget": { "type": "string", "minLength": 1 },
+    "bindingTarget": { "type": "string", "minLength": 1, "pattern": "^(?![\\\\/])(?![a-zA-Z]:)(?!.*//)(?!.*(?:^|/)\\.(?:/|$))(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*(?:^|/)[^/]*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.|/|$))(?!.*/$)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$" },
+    "detectionTargets": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "pattern": "^(?![\\\\/])(?![a-zA-Z]:)(?!.*//)(?!.*(?:^|/)\\.(?:/|$))(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*(?:^|/)[^/]*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.|/|$))(?!.*/$)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$" },
+      "minItems": 1,
+      "uniqueItems": true
+    },
     "bindingModes": {
       "type": "array",
       "items": { "enum": ["managed-block", "thin-reference"] },
       "minItems": 1,
-      "uniqueItems": true
+      "uniqueItems": true,
+      "contains": { "const": "thin-reference" }
+    },
+    "bindingTemplates": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "managed-block": { "type": "string", "minLength": 1, "pattern": "^(?![\\\\/])(?![a-zA-Z]:)(?!.*//)(?!.*(?:^|/)\\.(?:/|$))(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*(?:^|/)[^/]*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.|/|$))(?!.*/$)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$" },
+        "thin-reference": { "type": "string", "minLength": 1, "pattern": "^(?![\\\\/])(?![a-zA-Z]:)(?!.*//)(?!.*(?:^|/)\\.(?:/|$))(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*(?:^|/)[^/]*\\.(?:/|$))(?!.*(?:^|/)(?:[Cc][Oo][Nn]|[Pp][Rr][Nn]|[Aa][Uu][Xx]|[Nn][Uu][Ll]|[Cc][Oo][Mm][1-9]|[Ll][Pp][Tt][1-9])(?:\\.|/|$))(?!.*/$)[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)*$" }
+      }
     },
+    "unmanagedBindingPolicy": { "enum": ["append-managed-block", "reject"] },
     "managedMarker": { "type": "string", "pattern": "^forgerail:binding:[a-z][a-z0-9-]+:v1$" },
     "activationBoundary": { "enum": ["new-task-required", "host-specific-verification-required"] },
     "verification": {
@@ -39,5 +55,51 @@
       "items": { "type": "string", "minLength": 1 },
       "uniqueItems": true
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "supported" } }, "required": ["status"] },
+      "then": {
+        "properties": {
+          "activationBoundary": { "const": "new-task-required" },
+          "verification": {
+            "properties": {
+              "mode": { "const": "new-task-discovery" },
+              "expectedSkills": { "minItems": 1 }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "const": "profile-only" } }, "required": ["status"] },
+      "then": {
+        "properties": {
+          "activationBoundary": { "const": "host-specific-verification-required" },
+          "verification": {
+            "properties": {
+              "mode": { "const": "profile-only" },
+              "expectedSkills": { "maxItems": 0 }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "bindingModes": { "contains": { "const": "managed-block" } } }, "required": ["bindingModes"] },
+      "then": { "properties": { "bindingTemplates": { "required": ["managed-block"] } } }
+    },
+    {
+      "if": { "properties": { "bindingModes": { "contains": { "const": "thin-reference" } } }, "required": ["bindingModes"] },
+      "then": { "properties": { "bindingTemplates": { "required": ["thin-reference"] } } }
+    },
+    {
+      "if": { "properties": { "bindingTemplates": { "required": ["managed-block"] } }, "required": ["bindingTemplates"] },
+      "then": { "properties": { "bindingModes": { "contains": { "const": "managed-block" } } } }
+    },
+    {
+      "if": { "properties": { "bindingTemplates": { "required": ["thin-reference"] } }, "required": ["bindingTemplates"] },
+      "then": { "properties": { "bindingModes": { "contains": { "const": "thin-reference" } } } }
+    }
+  ]
 }

package/contracts/host-binding-receipt.schema.json

@@ -7,7 +7,7 @@
   "required": ["schemaVersion", "planId", "workspace", "adoptionLevel", "contractPath", "hosts", "changedFiles", "validationEvidence", "discoveredSkills", "activationVerification", "confirmedNonMutations", "deviations", "closeout"],
   "properties": {
     "schemaVersion": { "const": "1.0" },
-    "planId": { "type": "string", "pattern": "^[a-zA-Z0-9._:-]+$" },
+    "planId": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]+$" },
     "workspace": { "type": "string", "minLength": 1 },
     "adoptionLevel": { "enum": ["plugin-only", "lightweight-adoption", "persisted-governance"] },
     "contractPath": { "type": ["string", "null"] },

package/contracts/launch-contract.schema.json

@@ -4,10 +4,46 @@
   "title": "ForgeRail Launch Contract",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "envelope", "effectiveRuleSources", "hostAgent", "executionOwner"],
+  "required": ["schemaVersion", "envelope", "effectiveProfile", "effectivePackManifests", "effectiveRuleSources", "hostAgent", "executionOwner"],
   "properties": {
     "schemaVersion": { "const": "1.0" },
-    "envelope": { "$ref": "task-envelope.schema.json" },
+    "envelope": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Resolved Task Envelope. Requested Pack identities are represented once as an identity-to-manifest-digest map so schema-only consumers cannot accept an unbound requested Pack.",
+      "required": ["schemaVersion", "taskId", "intent", "nonGoals", "ownerWorkspace", "allowedOperations", "prohibitedOperations", "packs", "approvalGates", "validation", "returnContract"],
+      "properties": {
+        "schemaVersion": { "const": "1.0" },
+        "taskId": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]+$" },
+        "intent": { "type": "string", "minLength": 1 },
+        "nonGoals": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "ownerWorkspace": { "type": "string", "minLength": 1 },
+        "allowedOperations": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "prohibitedOperations": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "packs": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z][a-z0-9-]+$" },
+          "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+        },
+        "approvalGates": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" }, "uniqueItems": true },
+        "validation": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "returnContract": { "const": "forgerail-return-receipt-v1" }
+      }
+    },
+    "effectiveProfile": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Identity of the validated effective profile. Workspace identity is represented once by envelope.ownerWorkspace.",
+      "required": ["digest"],
+      "properties": {
+        "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+      }
+    },
+    "effectivePackManifests": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]+$" },
+      "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+    },
     "effectiveRuleSources": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
     "hostAgent": { "type": "string", "minLength": 1 },
     "executionOwner": { "const": "host-agent" }

package/contracts/profile-change-candidate.schema.json

@@ -7,7 +7,7 @@
   "required": ["schemaVersion", "candidateId", "workspace", "ruleId", "proposedValue", "evidence", "targetOwner", "targetSource", "reason", "requiresConfirmation", "status"],
   "properties": {
     "schemaVersion": { "const": "1.0" },
-    "candidateId": { "type": "string", "pattern": "^[a-zA-Z0-9._:-]+$" },
+    "candidateId": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]+$" },
     "workspace": { "type": "string", "minLength": 1 },
     "ruleId": { "type": "string", "pattern": "^[a-z][a-z0-9.-]+$" },
     "proposedValue": {},

package/contracts/return-receipt.schema.json

@@ -7,7 +7,7 @@
   "required": ["schemaVersion", "taskId", "ownerWorkspace", "branch", "commit", "changedScope", "validationEvidence", "externalSideEffects", "confirmedNonMutations", "residualRisks", "rollbackOrRecovery", "deviations", "closeout"],
   "properties": {
     "schemaVersion": { "const": "1.0" },
-    "taskId": { "type": "string", "pattern": "^[a-zA-Z0-9._:-]+$" },
+    "taskId": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]+$" },
     "ownerWorkspace": { "type": "string", "minLength": 1 },
     "branch": { "type": ["string", "null"] },
     "commit": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40}$" },

package/contracts/task-envelope.schema.json

@@ -7,7 +7,7 @@
   "required": ["schemaVersion", "taskId", "intent", "nonGoals", "ownerWorkspace", "allowedOperations", "prohibitedOperations", "packs", "approvalGates", "validation", "returnContract"],
   "properties": {
     "schemaVersion": { "const": "1.0" },
-    "taskId": { "type": "string", "pattern": "^[a-zA-Z0-9._:-]+$" },
+    "taskId": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]+$" },
     "intent": { "type": "string", "minLength": 1 },
     "nonGoals": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "ownerWorkspace": { "type": "string", "minLength": 1 },

package/directory/README.md

@@ -9,7 +9,7 @@ The candidate follows the OpenAI submission guidance observed on 2026-08-30:
 - <https://developers.openai.com/plugins/build/plugins>
 - <https://developers.openai.com/plugins/deploy/submission>
 
-The alpha.2 source candidate records the user-confirmed `Productivity` category, GitHub Issues support, repository Privacy and Terms URLs, and an intent to make ForgeRail available in all platform-supported regions. The live portal's exact region enumeration remains `pending_confirmation`; no country list is invented locally.
+The alpha.4 forward-fix candidate records the user-confirmed `Productivity` category, GitHub Issues support, repository Privacy and Terms URLs, and an intent to make ForgeRail available in all platform-supported regions. It also keeps the main Plugin within Codex's maximum of three starter prompts while preserving four independently owned Skills. The live portal's exact region enumeration remains `pending_confirmation`; no country list is invented locally.
 
 Before any Platform draft or submission, a human must still verify the publisher identity, Apps Management Write permission, live portal region encoding, accepted asset format, and exact final public source. `submission-candidate.json` records every unresolved item; `evaluations.json` contains the local positive and negative evaluation cases. Remote Git integration cannot grant Directory submission or publication authority.
 

package/directory/release-notes-alpha3.md

@@ -0,0 +1,7 @@
+# ForgeRail 0.1.0-alpha.3 release notes candidate
+
+ForgeRail alpha.3 is a narrow host-compatibility forward fix. The main Agent Plugin now exposes three reviewed starter prompts, which stays within the Codex host limit, while all four Skills remain independently discoverable and directly invokable.
+
+The third prompt is an either-or router: it directs a workspace-health request to `$workspace-health-review` or a duplicated-architecture-ownership request to `$architecture-convergence-audit`. It does not merge those Skills, make either depend on the other, or activate both implicitly.
+
+The candidate retains the alpha.2 Skills-only Directory shape, public Privacy and Terms, GitHub Issues support, Productivity category, all-platform-supported-regions intent, optional scoped npm CLI, no project Node.js requirement, and no implicit `.forgerail/` state. Directory submission, release, and lifecycle approvals remain separate and are not granted by this candidate.

package/directory/release-notes-alpha4.md

@@ -0,0 +1,9 @@
+# ForgeRail 0.1.0-alpha.4 release notes candidate
+
+ForgeRail alpha.4 is an integrity-focused forward fix for real project use. It makes contract, Profile, Pack, Launch, Receipt, Adoption, projection, Shadow and cross-workspace orchestration boundaries fail closed when input is malformed, duplicated, inconsistent or outside the declared workspace.
+
+Adoption approvals now bind the canonical workspace and every executable write field with a separately retained digest and immutable apply-time snapshot, while existing managed bindings are replaced atomically without intentionally removing the target path. Contract timestamps also preserve literal four-digit years, including `0000` through `0099`.
+
+The release adds deterministic regression coverage and complete Node.js 22 and 24 CI gates. It preserves the public product shape: four independently invokable Skills, a maximum of three starter prompts, Skills-only Marketplace installation, optional scoped npm CLI, no project `package.json` or `node_modules` requirement, no implicit `.forgerail/` state, and Apache-2.0.
+
+Some previously tolerated invalid inputs are intentionally rejected. Valid alpha.3 contracts remain supported; full v2 receipt lineage, cross-platform CI expansion, SBOM/OIDC provenance and other architectural improvements remain future work. Directory submission, release and lifecycle approvals stay independent and are not granted by this candidate.

package/directory/submission-candidate.json

@@ -2,7 +2,7 @@
   "schemaVersion": "1.0",
   "candidateType": "openai-universal-plugin-directory",
   "submissionType": "skills_only",
-  "status": "local_alpha2_source_candidate",
+  "status": "local_alpha4_integrity_candidate",
   "approval": { "type": "submission_approval", "status": "not_granted" },
   "officialBaseline": {
     "observedAt": "2026-08-30",
@@ -13,7 +13,7 @@
   },
   "plugin": {
     "id": "forgerail",
-    "version": "0.1.0-alpha.2",
+    "version": "0.1.0-alpha.4",
     "manifest": ".codex-plugin/plugin.json",
     "skills": [
       "forgerail",
@@ -43,8 +43,7 @@
     "starterPrompts": [
       "Use ForgeRail to govern this engineering task.",
       "Diagnose this workspace before recommending governance changes.",
-      "Review this workspace for governance and recovery risks.",
-      "Audit this architecture for duplicated capability ownership."
+      "Review workspace health or audit duplicated architecture ownership using the matching independent ForgeRail Skill."
     ]
   },
   "availability": {
@@ -58,8 +57,8 @@
   },
   "releaseNotes": {
     "state": "candidate",
-    "path": "./directory/release-notes-alpha2.md",
-    "value": "ForgeRail alpha.2 adds an independently invoked read-only architecture convergence audit and prepares a Skills-only Directory candidate with public Privacy and Terms, deterministic evaluations, and no project-local Node.js or persistent ForgeRail state requirement."
+    "path": "./directory/release-notes-alpha4.md",
+    "value": "ForgeRail alpha.4 hardens fail-closed contracts, profile and Pack identity, filesystem confinement, deterministic projection, shadow evidence and cross-workspace orchestration while preserving four independent Skills, no project Node.js requirement and read-only adoption defaults."
   },
   "evaluationFile": "./directory/evaluations.json",
   "unresolvedGates": [

package/docs/adoption.md

@@ -1,51 +1,88 @@
 # Progressive Adoption
 
-ForgeRail separates availability from project adoption. Installing the Agent Plugin or optional CLI makes capabilities available; it does not edit workspace instructions, create durable state, enable Capability Packs, or authorize external effects.
+ForgeRail separates **installation**, **availability**, **project adoption**, and **execution approval**. Installing the Plugin exposes guidance to the Agent; it does not edit workspace instructions, create durable state, enable Capability Packs, or authorize external effects.
 
-## Three Levels
+This guide describes the `0.1.0-alpha.4` / `v0.1.0-alpha.4` candidate. Check the published release for availability; this source document does not prove publication.
 
-### Level 0 — Plugin Only
+Start with Plugin Only. Move up only when repeated evidence shows that a small durable project binding is more useful than asking explicitly each time.
 
-This is the default. Skills are available to the host Agent, while the workspace remains unchanged. Use this level when occasional explicit or implicit Skill discovery is enough.
+## Level 0 — Plugin Only
 
-### Level 1 — Lightweight Adoption
+This is the default and recommended first experience. The workspace remains unchanged while these four Skills are available:
 
-Use this only after an Agent shows an exact Adoption Plan and the user confirms its writes.
+- `$forgerail` for bounded engineering guidance;
+- `$forgerail-workspace-diagnosis` for a read-only project picture;
+- `$workspace-health-review` for an independent health review;
+- `$architecture-convergence-audit` for duplicated-capability and ownership review.
 
-- For one host with concise principles, ForgeRail proposes one versioned managed block in that host's native instruction entry.
-- For multiple hosts, ForgeRail proposes `FORGERAIL.md` as the portable Adoption Contract plus thin host bindings that point to it.
+Use Plugin Only for occasional diagnosis, unfamiliar repositories, early experimentation, and any project whose existing instructions are already sufficient.
 
-The planner is read-only:
+## Level 1 — Lightweight Adoption
+
+Use this level only when repeated ForgeRail use justifies a small, reviewable project binding.
+
+- A single-host project may add one versioned managed block when its adapter supports that mode.
+- A multi-host project, or a single host whose adapter supports only thin references, uses `FORGERAIL.md` as a portable Adoption Contract plus thin host bindings.
+- Existing project instructions, specifications, ADRs, CI, and documentation remain authoritative in their own domains.
+
+The optional planner is read-only:
 
 ```bash
-forgerail adoption-plan --workspace . --host codex
-forgerail adoption-plan --workspace . --host codex --host claude-code --host cursor
+# Default: resolve only registered hosts detected in this workspace.
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 adoption-plan --workspace . --selection all-detected
+
+# Explicit subset chosen from the validated Host Adapter Registry.
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 adoption-plan --workspace . --host codex
+
+# Every adapter in the current validated registry.
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 adoption-plan --workspace . --selection all-available
 ```
 
-Each proposal contains the current and proposed level, exact target paths and content, base SHA-256 digests, required confirmation, verification steps, support status, and confirmed non-mutations. There is deliberately no `apply-adoption` command. The host Agent must display the proposal or diff, wait for confirmation, make only the approved writes, then return a Host Binding Receipt.
+Read-only diagnosis never follows links inside the selected workspace. It reads only bounded regular `package.json` and registered Host binding files, with a 4 MiB per-file limit; opened paths are revalidated against the canonical workspace before content is consumed. Unsafe, changed, non-regular, or oversized entries are reported as unavailable evidence for human review. A Markdown record practice is reported only when a safely confined well-known directory contains at least one bounded regular `.md` file; enumeration is capped at 4,096 entries, and empty, oversized, linked, or non-regular evidence is not treated as an ADR practice.
+
+The active Agent may translate a request such as “only Codex”, “all Agents used by this project”, or “all currently available adapters” into these deterministic modes. ForgeRail Core does not guess instruction paths, template names, or how to treat an existing unmanaged binding: detection targets, binding targets, binding templates, and that existing-content policy belong to versioned Host Adapters. Omitting both `--host` and `--selection` defaults to `all-detected`; if no registered host is detected, the planner asks for an explicit host or `all-available` instead of guessing. For human review, the plan records the mode and one `hostSelection.hosts` map keyed by each resolved adapter ID; it does not duplicate Host identity in requested/resolved arrays.
+
+Every proposal must show the current and proposed level, exact target paths and content, base digests, each write's `approvalSha256`, required confirmation, verification steps, support status, and non-actions. ForgeRail deliberately has no `apply-adoption` command. The Agent shows the proposal and waits for a human decision. Node-based integrations must retain the approved `approvalSha256` separately from the mutable proposal, then pass it as the third argument to `applyApprovedAdoptionWrite()` from `scripts/lib/adoption.mjs` so the canonical workspace path plus opened directory identity, destination, operation, marker, content, confinement, no-follow open, file identity and base digest are revalidated against one immutable snapshot at write time. Apply accepts only `create`, `append-managed-block`, or `replace-managed-block`, even when another operation is covered by a syntactically valid digest. Replacing the directory at the same path invalidates the approval. If a post-install check fails after replacing an existing binding, ForgeRail atomically renames the retained original inode directly over the verified installed candidate; it preserves recovery evidence and returns the original failure when safe restoration is impossible. The Agent verifies discovery in a new task and returns a Host Binding Receipt.
 
-### Level 2 — Persisted Governance
+If safe automatic rollback is impossible because concurrent content now occupies the approved target, ForgeRail keeps the original binding as a same-directory `.forgerail-<random>.bak` file and includes its project-relative path in the error. Compare that file with the current target, restore only the intended content through a new reviewed operation, and delete the recovery file only after confirming recovery. ForgeRail never treats the retained file as a successful write.
 
-This level is reserved for evidence that cannot be represented coherently through existing workspace sources: machine-consumed configuration, CI enforcement, or repeated cross-host conflicts. ForgeRail alpha.1 neither creates nor proposes `.forgerail/` state. A future design must define ownership, precedence, migration, and deletion semantics before enabling it.
+### Subset plans and received plans
 
-## Host Support
+Only selected hosts enter strict write planning. Other registered bindings are inspected through the same bounded, no-follow reader used by diagnosis: known managed bindings contribute to the observed current level and are listed as retained; unreadable entries are explicitly unknown and never block the selected-host plan. `currentLevel` describes readable workspace evidence, while `proposedLevel` and writes apply only to the selection. A `no-change` proposal does not remove an unselected binding. Selecting a subset does not consolidate other hosts' rules; review the coexistence warning before approving a new shared contract.
 
-| Host | Native target | Alpha.1 status | Verification |
+Before approving or applying **any** write from a received plan, validate the complete plan with `validateContract("adoption-plan", plan)`. Per-write approval digests do not replace that check. The runtime rejects case-folded duplicates, ancestor/descendant write targets and Host targets conflicting with reserved `FORGERAIL.md`; JSON Schema alone cannot compare arbitrary paths across entries. Thin-reference templates must name the exact shared `FORGERAIL.md` inside their managed block. This is a structural reference check, not proof that an Agent obeyed the instruction.
+
+## Level 2 — Persisted Governance
+
+Persisted machine-consumed ForgeRail state is deferred in the current alpha. It should be considered only when important evidence cannot be represented coherently through existing project sources, such as repeated cross-host conflicts or genuinely machine-enforced policy.
+
+ForgeRail does not create `.forgerail/` at this level today. A future design must define ownership, precedence, migration, recovery, and deletion before enabling it.
+
+## Host support
+
+| Host | Native target | Alpha.4 status | Verification boundary |
 | --- | --- | --- | --- |
-| Codex | `AGENTS.md` | `supported` | Start a new Codex task, verify the binding is in scope, and discover the three main Plugin Skills. |
-| Claude Code | `CLAUDE.md` | `profile-only` | The target and thin binding are modeled, but end-to-end activation is not claimed until host-specific verification exists. |
-| Cursor | `.cursor/rules/forgerail.mdc` | `profile-only` | The Rules target is modeled, but Skill discovery and end-to-end activation are not claimed. |
+| Codex | `AGENTS.md` | `supported` | New Codex task discovers all four main Skills and the approved binding is in scope |
+| Claude Code | `CLAUDE.md` | `profile-only` | Target and thin binding are modeled; end-to-end activation is not claimed |
+| Cursor | `.cursor/rules/forgerail.mdc` | `profile-only` | Target is modeled; Skill discovery and end-to-end activation are not claimed |
+
+Unknown hosts need a reviewed Host Adapter before ForgeRail can generate a binding. Every adapter provides a thin-reference projection so `all-detected` and `all-available` can always compose through the shared contract; adapters may additionally provide a managed-block projection for a single explicit Host. Registry validation limits target, detection and template locators to an ASCII-safe portable path alphabet, rejects trailing-dot aliases and Windows device basenames, then case-folds the remaining identities. Binding targets are prefix-free and cannot conflict with reserved `FORGERAIL.md`; every template contains exactly one ordered adapter-owned marker boundary. A Host Adapter projects ForgeRail into a host; it is not ForgeRail Core or a second policy source.
+
+## Capability Packs stay separate
 
-Unknown hosts require a reviewed Host Adapter before ForgeRail can generate a binding. A Host Adapter is a projection boundary, not the ForgeRail Core or a second policy source.
+Do not add a Capability Pack to project instructions simply because it is installed. Recommend one only when project evidence calls for that capability. Packs keep independent authentication, approval, validation, rollback, and lifecycle boundaries.
 
-## Optional Cross-Workspace Orchestration
+Cross-Workspace Orchestration is for genuine multi-owner, multi-repository, or multi-release coordination with safe dependency waves. It is not a reason to split an ordinary repository into artificial tasks. RelayPact can transport a bounded delegation and EchoPath can support recovery/context; neither is a ForgeRail runtime dependency.
 
-Do not promote the orchestration Pack into a workspace binding merely because it is installed. Recommend it only after observing multiple independent owner/repository/release boundaries and a safe parallel dependency wave. Keep ordinary single-repository work on ForgeRail Core.
+## Completion and removal
 
-If the project repeatedly uses this pattern, record the choice through its existing OpenSpec, Spec Kit, ADR, Markdown, issue, or instruction habit after exact durable-write confirmation. Do not create a new orchestration state directory. Task creation and every durable, remote, release, or lifecycle operation retain their own authorization.
+A Lightweight Adoption is complete only when:
 
-## Verification And Removal
+1. the applied file digest matches the approved plan;
+2. supported-host discovery is verified in a new task or equivalent fresh check;
+3. deviations are empty or explicitly accepted;
+4. the receipt records exactly what changed and did not change.
 
-An adoption is complete only when the applied file digest matches the approved plan, supported-host discovery is verified in a new task or equivalent supported check, deviations are empty, and non-mutations are recorded. Profile-only hosts remain unverified until their own host check passes.
+Uninstalling the Plugin does not silently remove adopted instructions. Revise or remove managed blocks through another exact, reviewed plan so unrelated project content is preserved.
 
-Removing ForgeRail does not silently remove adopted project instructions. Uninstall the Plugin separately; remove or revise managed blocks through another reviewed plan so unrelated project content is preserved.
+For normal use, begin with the [installation guide](installation.md) and stay at Plugin Only until a real project need appears.