@echopath-labs/forgerail 0.1.0-alpha.1

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

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgerail.dev/schemas/host-binding-receipt-v1.json",
+  "title": "ForgeRail Host Binding Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "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._:-]+$" },
+    "workspace": { "type": "string", "minLength": 1 },
+    "adoptionLevel": { "enum": ["plugin-only", "lightweight-adoption", "persisted-governance"] },
+    "contractPath": { "type": ["string", "null"] },
+    "hosts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["adapterId", "target", "baseSha256", "appliedSha256", "status", "verification"],
+        "properties": {
+          "adapterId": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" },
+          "target": { "type": "string", "minLength": 1 },
+          "baseSha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$" },
+          "appliedSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+          "status": { "enum": ["verified", "unverified", "failed"] },
+          "verification": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true }
+        }
+      }
+    },
+    "changedFiles": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "validationEvidence": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
+    "discoveredSkills": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" }, "uniqueItems": true },
+    "activationVerification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "verified"],
+      "properties": {
+        "mode": { "enum": ["new-task", "equivalent-supported-discovery", "host-specific"] },
+        "verified": { "type": "boolean" }
+      }
+    },
+    "confirmedNonMutations": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
+    "deviations": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "closeout": { "enum": ["complete", "incomplete", "blocked"] }
+  }
+}

package/contracts/launch-contract.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgerail.dev/schemas/launch-contract-v1.json",
+  "title": "ForgeRail Launch Contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "envelope", "effectiveRuleSources", "hostAgent", "executionOwner"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "envelope": { "$ref": "task-envelope.schema.json" },
+    "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

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgerail.dev/schemas/profile-change-candidate-v1.json",
+  "title": "ForgeRail Profile Change Candidate",
+  "type": "object",
+  "additionalProperties": false,
+  "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._:-]+$" },
+    "workspace": { "type": "string", "minLength": 1 },
+    "ruleId": { "type": "string", "pattern": "^[a-z][a-z0-9.-]+$" },
+    "proposedValue": {},
+    "evidence": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
+    "targetOwner": { "type": "string", "minLength": 1 },
+    "targetSource": { "type": "string", "minLength": 1 },
+    "reason": { "type": "string", "minLength": 1 },
+    "requiresConfirmation": { "const": true },
+    "status": { "const": "candidate" }
+  }
+}

package/contracts/return-receipt.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgerail.dev/schemas/return-receipt-v1.json",
+  "title": "ForgeRail Return Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "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._:-]+$" },
+    "ownerWorkspace": { "type": "string", "minLength": 1 },
+    "branch": { "type": ["string", "null"] },
+    "commit": { "type": ["string", "null"], "pattern": "^[0-9a-f]{40}$" },
+    "changedScope": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "validationEvidence": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+    "externalSideEffects": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "confirmedNonMutations": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "residualRisks": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "rollbackOrRecovery": { "type": "string", "minLength": 1 },
+    "deviations": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "closeout": { "enum": ["complete", "incomplete", "blocked"] }
+  }
+}

package/contracts/task-envelope.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgerail.dev/schemas/task-envelope-v1.json",
+  "title": "ForgeRail Task Envelope",
+  "type": "object",
+  "additionalProperties": false,
+  "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._:-]+$" },
+    "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": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" }, "uniqueItems": true },
+    "approvalGates": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]+$" }, "uniqueItems": true },
+    "validation": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "returnContract": { "type": "string", "const": "forgerail-return-receipt-v1" }
+  }
+}

package/docs/adoption.md

@@ -0,0 +1,51 @@
+# 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.
+
+## Three Levels
+
+### Level 0 — Plugin Only
+
+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 1 — Lightweight Adoption
+
+Use this only after an Agent shows an exact Adoption Plan and the user confirms its writes.
+
+- 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.
+
+The planner is read-only:
+
+```bash
+forgerail adoption-plan --workspace . --host codex
+forgerail adoption-plan --workspace . --host codex --host claude-code --host cursor
+```
+
+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.
+
+### Level 2 — Persisted Governance
+
+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.
+
+## Host Support
+
+| Host | Native target | Alpha.1 status | Verification |
+| --- | --- | --- | --- |
+| 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. |
+
+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.
+
+## Optional Cross-Workspace Orchestration
+
+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.
+
+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.
+
+## Verification And Removal
+
+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.
+
+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.

package/docs/adoption.zh-CN.md

@@ -0,0 +1,51 @@
+# 渐进式采用
+
+ForgeRail 将“能力可用”与“项目采用”明确分开。安装 Agent Plugin 或可选 CLI，只让能力可用；不会修改工作区 instructions、创建持久化状态、启用 Capability Pack，也不会授权任何外部副作用。
+
+## 三级模型
+
+### Level 0 — Plugin Only
+
+这是默认级别。宿主 Agent 可以发现 Skills，但工作区保持不变。偶尔显式调用或依靠 Agent 按描述判断触发已经足够时，应停留在此级别。
+
+### Level 1 — Lightweight Adoption
+
+只有在 Agent 展示精确 Adoption Plan、用户确认其中写入后才采用：
+
+- 单宿主且原则简短时，只向宿主原生 instruction 入口提出一个带版本 managed block；
+- 多宿主时，提出 `FORGERAIL.md` 作为可移植 Adoption Contract，各宿主只保留指向它的薄绑定。
+
+planner 永远只读：
+
+```bash
+forgerail adoption-plan --workspace . --host codex
+forgerail adoption-plan --workspace . --host codex --host claude-code --host cursor
+```
+
+计划会给出当前/目标级别、精确路径与内容、基线 SHA-256、必需确认、验证步骤、宿主支持状态和明确非变更项。ForgeRail 刻意不提供 `apply-adoption` 命令；宿主 Agent 必须先展示候选或 diff，等待确认，只执行获批写入，再返回 Host Binding Receipt。
+
+### Level 2 — Persisted Governance
+
+只有现有工作区来源无法清楚承载的证据才可能需要此级别，例如机器读取配置、CI 强制或反复出现的跨宿主冲突。ForgeRail alpha.1 不创建也不提出 `.forgerail/` 状态；未来必须先定义 owner、优先级、迁移与删除语义。
+
+## 宿主支持
+
+| 宿主 | 原生入口 | alpha.1 状态 | 验证 |
+| --- | --- | --- | --- |
+| Codex | `AGENTS.md` | `supported` | 在采用范围内启动新的 Codex 任务，确认绑定生效并发现三个主插件 Skills。 |
+| Claude Code | `CLAUDE.md` | `profile-only` | 已建模目标和薄绑定，但在宿主专项验证完成前不声称端到端激活。 |
+| Cursor | `.cursor/rules/forgerail.mdc` | `profile-only` | 已建模 Rules 入口，但不声称 Skill 发现和端到端激活已验证。 |
+
+未知宿主必须先有经过审查的 Host Adapter 才能生成绑定。Host Adapter 是投影边界，不是 ForgeRail Core，也不是第二套规则源。
+
+## 可选跨工作区编排
+
+不要因为安装了 orchestration Pack 就把它写进工作区 binding。只有观察到多个独立 owner/repository/release 边界和一个安全并行依赖波次后才建议采用；普通单仓工作继续使用 ForgeRail Core。
+
+如果项目反复使用该模式，在取得精确 durable-write 确认后，沿用现有 OpenSpec、Spec Kit、ADR、Markdown、issue 或 instruction 习惯记录，不创建新的编排状态目录。创建任务以及每类 durable、远端、发布或 lifecycle 操作仍保留各自授权。
+
+## 核验与移除
+
+只有 applied digest 与获批 plan 一致、支持宿主在新任务或等价支持检查中完成发现、deviations 为空且非变更项已记录，采用才能 close 为 complete。`profile-only` 宿主在完成自身专项检查前仍保持未验证。
+
+卸载 ForgeRail 不会静默删除项目已经采用的 instructions。插件卸载与项目绑定移除是两件事；修改或移除 managed block 也要经过新的审查计划，以保护无关项目内容。

package/docs/agw-coverage-baseline.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": "1.0",
+  "source": "docs/agw-frozen-baseline.json",
+  "allowedDispositions": ["forgerail-core", "workspace-diagnosis", "workspace-profile", "task-envelope", "return-receipt", "capability-pack", "source-reference", "unresolved"],
+  "items": [
+    { "id": "owner-workspace", "target": "forgerail-core", "status": "mapped" },
+    { "id": "preserve-user-changes", "target": "forgerail-core", "status": "mapped" },
+    { "id": "durable-record-decision", "target": "workspace-diagnosis", "status": "mapped" },
+    { "id": "git-lifecycle", "target": "source-reference", "status": "mapped" },
+    { "id": "validation-and-impact", "target": "task-envelope", "status": "mapped" },
+    { "id": "independent-approval-gates", "target": "forgerail-core", "status": "mapped" },
+    { "id": "machine-readable-closeout", "target": "return-receipt", "status": "mapped" },
+    { "id": "workspace-health-review", "target": "capability-pack", "status": "mapped" },
+    { "id": "release-safety", "target": "capability-pack", "status": "mapped" },
+    { "id": "thread-closure", "target": "capability-pack", "status": "mapped" },
+    { "id": "github-rulesets", "target": "capability-pack", "status": "mapped" }
+  ],
+  "behaviorCoverageReady": true,
+  "migrationReady": false,
+  "migrationBlockers": ["usable ForgeRail prerelease is not published", "real compatibility-period canaries are incomplete", "AGW lifecycle change is not approved"]
+}

package/docs/agw-coverage-baseline.md

@@ -0,0 +1,21 @@
+# AGW To ForgeRail Coverage Baseline
+
+This is the initial deterministic owner map. Behavioral equivalence still requires shadow tasks.
+
+| AGW/WHR behavior | ForgeRail owner | State |
+| --- | --- | --- |
+| smallest owner workspace | Core | mapped |
+| preserve user changes and inspect Git state | Core | mapped |
+| durable record decision using existing systems | Workspace Diagnosis + Profile | mapped |
+| Git branch lifecycle | Profile/source reference | mapped; detailed baseline remains in AGW during compatibility |
+| validation and impact evidence | Core + Task Envelope | mapped |
+| independent approval gates | Core + Task Envelope | mapped |
+| risk and context guardrails | Core + applicable pack | mapped |
+| machine-readable closeout | Return Receipt | mapped |
+| optional EchoPath integration | optional ecosystem contract | mapped conceptually; runtime integration pending |
+| Workspace Health Review | built-in `workspace-health-review` pack | mapped; full historical signal parity pending |
+| release and shared-environment safety | external `forgerail-release-safety` Plugin | mapped; project runbook and separate approval remain required |
+| thread closure governance | external `forgerail-thread-closure` Plugin | mapped; durable write and lifecycle gates remain independent |
+| GitHub Rulesets governance | external `forgerail-github-rulesets` Plugin | mapped; remote execution remains separately approved host-Agent work |
+
+The local behavior map is complete, but migration is not ready merely because the map is complete. Remote integration/CI, a usable prerelease, canary evidence, and a separate AGW lifecycle approval remain independent gates.

package/docs/agw-frozen-baseline.json

@@ -0,0 +1,51 @@
+{
+  "schemaVersion": "1.0",
+  "canonicalSource": {
+    "repository": "echopath-private",
+    "commit": "d16f306d58841c575125d7ea53f3f9dbb715562f",
+    "pluginPath": "plugins/agent-workflow-governance",
+    "pluginVersion": "0.2.0",
+    "skills": [
+      {
+        "name": "agent-workflow-governance",
+        "entryBlob": "3bd3087aeab4de33638125980a7a48b83ee2c231"
+      },
+      {
+        "name": "workspace-health-review",
+        "entryBlob": "acc042419c3a9f383c0e3cc52c1c84d23a600d1e"
+      }
+    ],
+    "behaviorSources": [
+      {
+        "path": "plugins/agent-workflow-governance/skills/agent-workflow-governance/SKILL.md",
+        "blob": "3bd3087aeab4de33638125980a7a48b83ee2c231"
+      },
+      {
+        "path": "plugins/agent-workflow-governance/skills/agent-workflow-governance/references/durable-record-decision.md",
+        "blob": "8987f030f8b89eeb304d4f3d6b4495f70ba463a2"
+      },
+      {
+        "path": "plugins/agent-workflow-governance/skills/workspace-health-review/SKILL.md",
+        "blob": "acc042419c3a9f383c0e3cc52c1c84d23a600d1e"
+      }
+    ]
+  },
+  "publicEvidence": {
+    "repository": "echopath-labs/agent-workflow-governance",
+    "draftPullRequest": "https://github.com/echopath-labs/agent-workflow-governance/pull/2",
+    "candidateCommit": "94c01a8c2b1b7af54e30a565d87d2f55fe0f5fc1",
+    "statusAtFreeze": "release-approval-not-inherited-by-forgerail-work"
+  },
+  "installEntries": ["agent-workflow-governance", "workspace-health-review"],
+  "behaviorAssertions": {
+    "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"]
+  },
+  "rollback": "Disable ForgeRail as core owner and restore the exact validated AGW Plugin candidate or last published AGW version without modifying project records.",
+  "lifecycle": "compatibility-baseline"
+}

package/docs/architecture-acceptance.md

@@ -0,0 +1,38 @@
+# First Alpha Architecture Acceptance
+
+Accepted on 2026-08-12:
+
+- Core + Workspace Diagnosis + Workspace Health Review ship in the main Agent Plugin.
+- GitHub Rulesets, Release Safety, and Thread Closure begin as external Capability Packs.
+- Workspace Profile is computed from existing sources; no `.forgerail/profile.yaml` is created by default.
+- A lightweight npm/npx CLI is approved for deterministic diagnosis, contract validation, installation inspection, and bundle construction; it is not a prerequisite for using the Agent Plugin.
+- Adoption is progressive: Plugin Only by default, explicitly confirmed Lightweight Adoption through Host Adapters, and evidence-gated Persisted Governance deferred beyond alpha.1.
+- Host instruction entries are projections of one portable Adoption Contract. Codex is supported; Claude Code and Cursor remain profile-only until host-specific activation is verified.
+
+## Measurable Acceptance
+
+The first usable prerelease must prove:
+
+1. official Plugin and Skill validators accept the payload;
+2. clean discovery of exactly three main-Plugin Skills;
+3. bounded diagnosis inherits an existing Markdown/ADR practice without recommending OpenSpec;
+4. a workspace with no observed record practice receives recommendations but no file mutation;
+5. installed Workspace Health remains `available` unless enabled, required, or explicitly invoked;
+6. conflicting allowed/prohibited operations fail validation;
+7. a Return Receipt with unresolved deviations cannot close as complete;
+8. deterministic bundle inventory and digest are reproducible;
+9. disposable install, diagnosis, Launch/Receipt, upgrade, rollback, and uninstall smoke pass before public release;
+10. adoption planning is read-only, exposes exact base/content digests, and cannot generate `.forgerail/` state;
+11. a disposable Codex adoption candidate is explicitly applied by the consumer harness, verified through an equivalent supported discovery check, and closed with a valid Host Binding Receipt;
+12. AGW remains the rollback baseline until shadow comparison and an explicitly approved migration gate complete.
+
+## Representative Shadow Tasks
+
+- normal feature work with branch and durable-record handling;
+- bug fix with dirty-worktree preservation;
+- documentation-only task using existing Markdown decisions;
+- shared-environment release preparation requiring a project runbook;
+- GitHub Rulesets assessment where no remote mutation is authorized;
+- completed task requiring a workspace health or closure recommendation.
+
+The compatibility period cannot end until all mapped AGW/WHR behaviors have owners, disposable and real canaries show no uncovered P0/P1 behavior, rollback is proven, and lifecycle change receives separate approval.

package/docs/context-cost.md

@@ -0,0 +1,13 @@
+# Context Cost And Progressive Loading
+
+ForgeRail's default task entry is `skills/forgerail/SKILL.md`. Workspace Diagnosis and Workspace Health are separate Skills and do not load merely because the main Plugin is installed.
+
+At the first alpha implementation point:
+
+- Core `SKILL.md`: measured from the canonical file during validation;
+- Workspace Diagnosis `SKILL.md`: separate entry, loaded for first-use, explicit, drift, or conflict diagnosis;
+- Workspace Health `SKILL.md`: installed as `available` and independently invoked or enabled;
+- Core references load only for Task Envelope/Receipt or Profile conflict work;
+- external GitHub Rulesets, Release Safety, and Thread Closure packs are absent from the main runtime payload and use separate, non-implicit Skill entrypoints.
+
+The fixture `profile-input.available-pack.json` proves that an installed Workspace Health pack in `available` state does not enter `activePacks`. The inactive-pack Launch fixture proves a task cannot request that pack until it is enabled or required.

package/docs/external-capability-packs.md

@@ -0,0 +1,25 @@
+# External Capability Packs
+
+ForgeRail's first main Plugin keeps remote and release mutation domains outside its runtime payload.
+
+## Cross-Workspace Orchestration
+
+The `forgerail-cross-workspace-orchestration` Plugin is for a master task coordinating at least two genuinely independent owner workspaces, repositories, or release identities with safe parallel dependency stages. It governs owner assignment, waves, single-writer identities, independent approvals, stable handoff review, and recovery. Do not install or invoke it merely because one repository has several folders, packages, or agents.
+
+It is read/plan/recommend by default. Host task creation, inspection, wait, messaging, and resume are Host Adapter capabilities; hosts without verified task APIs degrade to user-created sessions, stable handoffs, or serial work. RelayPact may carry delegation and returns, and EchoPath may provide authorized recovery context, but neither is required or owns ForgeRail acceptance.
+
+## GitHub Rulesets
+
+The `forgerail-github-rulesets` Plugin diagnoses applicability, inspects current rules and required checks, prepares an exact approval package, and verifies a returned GitHub receipt. Installation does not change Rulesets, branch protection, repository settings, or default branches.
+
+## Release Safety
+
+The `forgerail-release-safety` Plugin activates only for release, rollback, registry, image, CI/CD, or shared-environment work. It requires the project's own runbook and does not invent generic production procedures or contain release commands.
+
+## Thread Closure
+
+The `forgerail-thread-closure` Plugin activates only after implementation, validation, and task evidence are ready for closeout. It verifies ownership, durable-record status, recovery entry, Profile candidates, and context debt without implementing follow-up work or writing durable changes without confirmation.
+
+These packs retain separate authentication, release cadence, risk, and rollback boundaries while using the same ForgeRail Profile, Task Envelope, and Return Receipt contracts.
+
+All four are separately installed and explicitly invoked. Being present in the Marketplace means available, not recommended, enabled, required, authenticated, or authorized.

package/docs/installation.md

@@ -0,0 +1,88 @@
+# Installation And Adoption
+
+ForgeRail is primarily an Agent Plugin. The npm package is an optional deterministic CLI and compatibility payload.
+
+## Install
+
+After `v0.1.0-alpha.1` is published, register the immutable Marketplace snapshot and install the main Plugin:
+
+```bash
+codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.1
+codex plugin add forgerail@echopath-labs
+```
+
+Start a new Codex task after installation so discovery uses the installed snapshot. The new task must discover:
+
+- `$forgerail`;
+- `$forgerail-workspace-diagnosis`;
+- `$workspace-health-review`.
+
+The versioned Marketplace registration is the Plugin release identity; do not replace the tag with a mutable branch when reproducibility matters. For local canonical testing, build a disposable bundle or npm tarball; do not point production workspaces at an uncommitted source tree.
+
+## Optional Capability Pack Plugins
+
+Install only the packs the project needs. Installation makes a pack available; it does not authenticate, activate, require, or approve its external effects.
+
+```bash
+codex plugin add forgerail-github-rulesets@echopath-labs
+codex plugin add forgerail-release-safety@echopath-labs
+codex plugin add forgerail-thread-closure@echopath-labs
+codex plugin add forgerail-cross-workspace-orchestration@echopath-labs
+```
+
+The Rulesets and Release Safety packs remain read-first. Ruleset mutations, repository protection changes, publishing, deployment, and lifecycle changes require their own exact approvals.
+
+Install Cross-Workspace Orchestration only when a master task must coordinate multiple genuine owner/repository/release boundaries and dependency evidence exposes safe parallel stages. It is not for an ordinary single repository or monorepo folder split. Installation leaves it `available`; invoke it explicitly, or adopt it through existing project instructions only after review. It does not create tasks or durable records, and remote integration, release, and lifecycle approvals remain independent.
+
+Host task/thread APIs are not portable. Codex, Claude Code, Cursor, and other hosts must provide verified create/inspect/wait/message/resume capabilities through a Host Adapter; otherwise use user-created sessions, stable handoffs, or serial execution. RelayPact is an optional delegation transport and EchoPath is an optional recovery/context source, not runtime dependencies.
+
+## Optional npm CLI
+
+The npm package is not required by the Agent Plugin. The official package is organization-scoped as `@echopath-labs/forgerail`; the unscoped `forgerail` package remains a reservation and is not an install or rollback source. After registry publication, use an exact scoped prerelease when validating or diagnosing a workspace:
+
+```bash
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.1 validate
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.1 diagnose --workspace .
+```
+
+For a persistent CLI shim:
+
+```bash
+npm install --global @echopath-labs/forgerail@0.1.0-alpha.1
+forgerail validate
+```
+
+## Adoption
+
+Installation makes capabilities available. It does not edit a project's `AGENTS.md`, create `.forgerail/`, install OpenSpec, or make Workspace Health mandatory. Project adoption is a separate, explicit decision.
+
+ForgeRail uses progressive adoption:
+
+1. **Plugin Only** is the default and leaves the workspace unchanged.
+2. **Lightweight Adoption** requires an exact read-only plan and user confirmation. One host gets a versioned managed block; multiple hosts may share `FORGERAIL.md` through thin bindings.
+3. **Persisted Governance** is evidence-gated and deferred in alpha.1; the CLI will not generate `.forgerail/` state.
+
+The optional CLI can prepare, but never apply, a candidate:
+
+```bash
+forgerail adoption-plan --workspace . --host codex
+forgerail adoption-plan --workspace . --host codex --host claude-code --host cursor
+```
+
+Codex is the only `supported` Host Adapter in alpha.1. Claude Code and Cursor are published as `profile-only` boundaries so their target files and limitations are explicit without claiming verified activation. The host Agent must show the exact proposal, obtain confirmation, preserve unrelated content, write only the approved paths, then verify discovery in a new task or equivalent supported check and return a Host Binding Receipt.
+
+See [Progressive Adoption](adoption.md) for the full model, support matrix, verification, and removal semantics.
+
+## Upgrade And Reinstall
+
+Register the new exact Marketplace tag, reinstall the selected Plugin names from `echopath-labs`, then start a new Codex task. Repeat Skill discovery and a bounded read-only diagnosis smoke. Upgrade only between exact `@echopath-labs/forgerail` versions. Reinstall must preserve project files and Profile sources.
+
+## Rollback And Uninstall
+
+Re-register the last validated Marketplace tag and reinstall the selected Plugin names, or return to the frozen AGW version. Remove ForgeRail Plugins with the Codex plugin command surface and remove the optional CLI with `npm uninstall --global @echopath-labs/forgerail`; do not delete project records, Agent instructions, or Git history. AGW remains the compatibility rollback until the migration gate is separately approved.
+
+## Release Boundary
+
+Publishing npm, moving `latest`, pushing a public candidate, tagging, creating a GitHub Release, or changing AGW lifecycle requires separate approval and exact release receipts.
+
+See [ForgeRail 0.1.0-alpha.1 Release Runbook](release.md) for the project-owned gate order and rollback boundary.

package/docs/installation.zh-CN.md

@@ -0,0 +1,60 @@
+# 安装与采用
+
+ForgeRail 的主要形态是 Agent Plugin；npm 包是可选的确定性 CLI 与兼容载荷。
+
+在 `v0.1.0-alpha.1` 发布后，注册不可变的 Marketplace 快照并安装主插件：
+
+```bash
+codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.1
+codex plugin add forgerail@echopath-labs
+```
+
+安装后启动一个新的 Codex 任务，使插件发现基于已安装快照。新任务必须发现 `$forgerail`、`$forgerail-workspace-diagnosis` 和 `$workspace-health-review`。需要可复现安装时，不要用可变分支替代精确 tag。
+
+GitHub Rulesets、Release Safety 与 Thread Closure 是单独插件，只按项目需要安装：
+
+```bash
+codex plugin add forgerail-github-rulesets@echopath-labs
+codex plugin add forgerail-release-safety@echopath-labs
+codex plugin add forgerail-thread-closure@echopath-labs
+codex plugin add forgerail-cross-workspace-orchestration@echopath-labs
+```
+
+安装只让能力可用，不等于认证、启用、要求或批准外部副作用。Ruleset、仓库保护、发布、部署和生命周期变更仍需各自的精确审批。
+
+只有当主控任务需要协调多个真正独立的 owner workspace、repository 或 release identity，且依赖证据表明存在安全并行阶段时，才安装 Cross-Workspace Orchestration。普通单仓任务或 monorepo 目录拆分不适用。安装后状态仍是 `available`；必须显式调用，或在审查后沿用项目已有 instructions 采用。它不会自动创建任务或 durable record，远端集成、发布和 lifecycle 审批仍相互独立。
+
+不同宿主不共享同一套 task/thread API。Codex、Claude Code、Cursor 等必须由 Host Adapter 明确声明并验证 create/inspect/wait/message/resume 能力；缺失时降级为用户创建的独立会话、稳定 handoff 或串行执行。RelayPact 只是可选委派 transport，EchoPath 只是可选恢复/上下文来源，均非运行时硬依赖。
+
+安装只代表能力可用，不会修改项目 `AGENTS.md`、创建 `.forgerail/`、安装 OpenSpec 或要求项目启用 Workspace Health。项目采用、能力启用和长期规约变更都需要单独确认。
+
+ForgeRail 采用渐进式三级模型：
+
+1. **Plugin Only** 是默认状态，工作区零修改；
+2. **Lightweight Adoption** 必须先生成精确只读计划并经用户确认；单宿主使用带版本 managed block，多宿主可使用 `FORGERAIL.md` 加薄绑定；
+3. **Persisted Governance** 只在真实证据支持时考虑，alpha.1 延期且 CLI 不会生成 `.forgerail/` 状态。
+
+可选 CLI 只生成候选，不会应用：
+
+```bash
+forgerail adoption-plan --workspace . --host codex
+forgerail adoption-plan --workspace . --host codex --host claude-code --host cursor
+```
+
+alpha.1 只有 Codex Host Adapter 是 `supported`；Claude Code 与 Cursor 以 `profile-only` 发布，明确目标入口与限制，但不声称已验证激活。宿主 Agent 必须展示精确候选、取得确认、保护无关内容、只写获批路径，再在新任务或等价支持检查中验证发现并返回 Host Binding Receipt。
+
+完整模型、支持矩阵、验证与移除语义见[渐进式采用](adoption.zh-CN.md)。
+
+Agent Plugin 不依赖 npm CLI。官方包名为 `@echopath-labs/forgerail`；未作用域 `forgerail` 只保留名称占位，不是安装或回滚来源。registry 发布后，可用精确 scoped 版本执行离线校验和只读诊断：
+
+```bash
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.1 validate
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.1 diagnose --workspace .
+npm install --global @echopath-labs/forgerail@0.1.0-alpha.1
+```
+
+升级时注册新的精确 Marketplace tag，重新安装已选择的插件，再启动新的 Codex 任务验证 Skill 发现与只读诊断；npm CLI 只能在精确 `@echopath-labs/forgerail` 版本之间升级。回滚时重新注册最近已验证 tag，或退回冻结的 AGW 版本；卸载可选 CLI 使用 `npm uninstall --global @echopath-labs/forgerail`，不得删除项目记录、Agent instructions 或 Git 历史。
+
+npm 发布、移动 `latest`、推送公共候选、tag、GitHub Release 和 AGW 生命周期变更都属于独立审批门。
+
+项目专属门序与回滚边界见 [ForgeRail 0.1.0-alpha.1 发布 Runbook](release.zh-CN.md)。

package/docs/migration-from-agw.md

@@ -0,0 +1,12 @@
+# Migration From Agent Workflow Governance
+
+ForgeRail does not rename AGW in place.
+
+1. Freeze the exact AGW/WHR source, installation, behavior, docs, and rollback baseline.
+2. Map every in-scope behavior to ForgeRail Core, a Capability Pack, Profile, source reference, Task Envelope, or unresolved status.
+3. Run representative tasks in shadow without changing activation.
+4. Canary ForgeRail with one explicit core owner and immediate AGW rollback.
+5. Publish versioned upgrade, coexistence, rollback, and uninstall guidance.
+6. Decide AGW repository and entrypoint lifecycle only through a separate approval.
+
+Current rollback baseline is the existing Agent Workflow Governance Plugin at its validated `0.2.0` candidate source. Exact public release identity must be reverified before a ForgeRail release approval package is issued.

package/docs/pack-authoring.md

@@ -0,0 +1,17 @@
+# Capability Pack Authoring
+
+A pack must provide a manifest that validates against `contracts/capability-pack.schema.json` and declare purpose, triggers, inputs, dependencies, conflicts, risk, approvals, validation, and receipt extensions.
+
+Use an independent Skill inside the main Plugin only when context cost, authentication, risk, and release cadence remain coupled to Core. Use a separately distributed Plugin for high-risk remote operations or independent authentication.
+
+Never interpret installation as enablement. Recommendations remain candidates; durable `enabled` or `required` state needs project authority or user confirmation.
+
+The optional CLI composes a separately distributed pack only when its exact manifest is supplied:
+
+```bash
+forgerail resolve-profile \
+  --file profile-input.json \
+  --pack-manifest /path/to/pack.json
+```
+
+The manifest is validated before composition. Missing dependencies, declared conflicts, duplicate capability owners, or enabled packs without a supplied manifest fail closed.