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

package/docs/control-authority-validation-contracts.zh-CN.md

@@ -0,0 +1,36 @@
+# Control Authority 与 Validation 合同
+
+ForgeRail 新增八个版本化 Control System 合同，不改变 alpha 合同、task-control 合同或任何 Host Adapter profile。
+
+| 合同 | Schema 版本 | 文件 |
+| --- | --- | --- |
+| Review Authority Requirement | 1.0 | `contracts/review-authority-requirement-v1.schema.json` |
+| Authority Evidence | 1.0 | `contracts/authority-evidence-v1.schema.json` |
+| Validation Topology | 1.0 | `contracts/validation-topology-v1.schema.json` |
+| Validation Result | 1.0 | `contracts/validation-result-v1.schema.json` |
+| Execution Context Identity | 1.0 | `contracts/execution-context-identity-v1.schema.json` |
+| Host Adapter Observation | 1.0 | `contracts/host-adapter-observation-v1.schema.json` |
+| Provider Adapter Observation | 1.0 | `contracts/provider-adapter-observation-v1.schema.json` |
+| Limited Reason | 1.0 | `contracts/limited-reason-v1.schema.json` |
+
+这些合同建立以下首批边界：
+
+- Review Authority 与 Operation Authority、Operation Grant 相互独立。Requirement 绑定 authority class、exact subject/scope、accepted evidence、quorum、actor exclusion、owner coverage、freshness、默认不可替代和有界 waiver policy。
+- Authority Evidence 引用 Evidence Identity，并区分 `current`、`stale`、`revoked`、`dismissed`、`expired`、`superseded`；已经失效的 evidence 不能继续声明 current。
+- Validation Topology 连接 changed surface、owner、consumer、selected requirement、governance dependency edge、accepted trust class、expected result、entrypoint 与 evidence locator。
+- Validation Result 保留七种状态：`passed`、`failed`、`blocked`、`unavailable`、`not_applicable`、`not_selected`、`waived`。passed 必须有 evidence；waiver 必须绑定 current authority、exact requirement、subject、scope 与 expiry。
+- Execution Context Identity 记录权威 entrypoint、invocation root、executor/runner、trust class、tool、provider 与 sanitized external dependency。入口消费外部依赖不代表该依赖成为治理来源。
+- Host/Provider Adapter observation 按 capability 报告状态。安装、认证、激活或 mutation capability 均不能 mint authority；observation 的 `authorizationClaim` 固定为 `false`。
+- Limited Reason 使用有界 code、长度受限且 sanitized 的摘要、evidence pointer 与 sanitized locator。新合同使用该结构，但不修改已经版本化的 Profile 或 Task 合同。
+
+本任务只定义 schema 与 deterministic validation contract。Authority、Topology、Execution Context、Adapter evaluator 仍属于后续任务。版本兼容的 Pack composition schema 已定义在 [Cross-Workspace Pack Composition 合同](cross-workspace-pack-composition-contract.zh-CN.md)；pre-evaluator invalid boundary 已记录在 [Control System Fixture Matrix](control-system-fixture-matrix.zh-CN.md)。canonical serialization、digest 与 version negotiation 仍属于 task 2.10。
+
+运行聚焦校验：
+
+```bash
+node scripts/forgerail.mjs validate
+node scripts/forgerail.mjs validate-fixtures
+node scripts/forgerail.mjs validate-contract --type review-authority-requirement --file scripts/fixtures/contracts/review-authority-requirement.valid.json
+node scripts/forgerail.mjs validate-contract --type validation-result --file scripts/fixtures/contracts/validation-result.valid.json
+node scripts/forgerail.mjs validate-contract --type provider-adapter-observation --file scripts/fixtures/contracts/provider-adapter-observation.valid.json
+```

package/docs/control-profile-contracts.md

@@ -0,0 +1,35 @@
+# Control Profile Contracts
+
+ForgeRail keeps the alpha contracts intact while introducing the first versioned Control System contracts inside the same package.
+
+| Contract | Schema version | File |
+| --- | --- | --- |
+| Workspace Identity | 1.0 | `contracts/workspace-identity-v1.schema.json` |
+| Workspace Relationship | 1.0 | `contracts/workspace-relationship-v1.schema.json` |
+| Governance Source | 1.0 | `contracts/governance-source-v1.schema.json` |
+| Source Dependency Edge | 1.0 | `contracts/source-dependency-edge-v1.schema.json` |
+| Rule Claim | 1.0 | `contracts/rule-claim-v1.schema.json` |
+| Effective Profile | 2.0 | `contracts/effective-profile-v2.schema.json` |
+| Profile Explanation | 1.0 | `contracts/profile-explanation-v1.schema.json` |
+
+`effective-profile-v2` is intentionally separate from the frozen alpha `effective-profile-v1` contract. It binds claims and dependency edges to one exact Workspace Identity and makes `complete`, `degraded`, and `unresolved` explicit without changing the alpha resolver or user entry.
+
+The contracts enforce these initial invariants:
+
+- filesystem nesting does not transfer authority;
+- only confirmed or provider-declared relationships may apply scoped governance;
+- inferred claims cannot be enforceable;
+- unavailable, ambiguous, or unverified sources and dependencies carry a limited reason;
+- a required unavailable dependency, unresolved claim, or conflict cannot appear in a complete Profile;
+- Profile Explanation contains identities, dispositions, reason codes, confirmation needs, and limited reasons rather than private rule bodies.
+
+Task Envelope, Operation Grant, Control Revision, Evidence Identity, Return Receipt, and rollback lineage are defined in [Control Task Contracts](control-task-contracts.md). Review Authority lifecycle, Validation Topology, Execution Context, and Adapter observations are defined in [Control Authority And Validation Contracts](control-authority-validation-contracts.md). Pack bundles remain later work.
+
+Run the focused catalog and fixture checks with:
+
+```bash
+node scripts/forgerail.mjs validate
+node scripts/forgerail.mjs validate-fixtures
+node scripts/forgerail.mjs validate-contract --type workspace-identity --file scripts/fixtures/contracts/workspace-identity.valid.json
+node scripts/forgerail.mjs validate-contract --type effective-profile-v2 --file scripts/fixtures/contracts/effective-profile-v2.valid.json
+```

package/docs/control-profile-contracts.zh-CN.md

@@ -0,0 +1,35 @@
+# Control Profile 合同
+
+ForgeRail 在同一个 package 内增加首批版本化 Control System 合同，同时保持现有 alpha 合同不变。
+
+| 合同 | Schema 版本 | 文件 |
+| --- | --- | --- |
+| Workspace Identity | 1.0 | `contracts/workspace-identity-v1.schema.json` |
+| Workspace Relationship | 1.0 | `contracts/workspace-relationship-v1.schema.json` |
+| Governance Source | 1.0 | `contracts/governance-source-v1.schema.json` |
+| Source Dependency Edge | 1.0 | `contracts/source-dependency-edge-v1.schema.json` |
+| Rule Claim | 1.0 | `contracts/rule-claim-v1.schema.json` |
+| Effective Profile | 2.0 | `contracts/effective-profile-v2.schema.json` |
+| Profile Explanation | 1.0 | `contracts/profile-explanation-v1.schema.json` |
+
+`effective-profile-v2` 与冻结的 alpha `effective-profile-v1` 明确分开。新合同把 claims 和 dependency edges 绑定到一个精确 Workspace Identity，并显式区分 `complete`、`degraded` 与 `unresolved`，但不改变 alpha resolver 或用户入口。
+
+首批合同固定以下不变量：
+
+- 目录物理嵌套不转移 authority；
+- 只有 confirmed 或 provider-declared relationship 才能让 scoped governance 生效；
+- inferred claim 不能直接 enforce；
+- unavailable、ambiguous 或 unverified source/dependency 必须携带 limited reason；
+- required dependency 不可用、claim unresolved 或存在 conflict 时，Profile 不能声明 complete；
+- Profile Explanation 只携带 identity、disposition、reason code、confirmation need 和 limited reason，不复制私有规则正文。
+
+Task Envelope、Operation Grant、Control Revision、Evidence Identity、Return Receipt 与 rollback lineage 已定义在 [Control Task 合同](control-task-contracts.zh-CN.md)中。Review Authority lifecycle、Validation Topology、Execution Context 与 Adapter observation 已定义在 [Control Authority 与 Validation 合同](control-authority-validation-contracts.zh-CN.md)中。Pack bundle 仍属于后续工作。
+
+运行聚焦校验：
+
+```bash
+node scripts/forgerail.mjs validate
+node scripts/forgerail.mjs validate-fixtures
+node scripts/forgerail.mjs validate-contract --type workspace-identity --file scripts/fixtures/contracts/workspace-identity.valid.json
+node scripts/forgerail.mjs validate-contract --type effective-profile-v2 --file scripts/fixtures/contracts/effective-profile-v2.valid.json
+```

package/docs/control-system-fixture-matrix.md

@@ -0,0 +1,30 @@
+# Control System Fixture Matrix
+
+ForgeRail's pre-evaluator fixture gate covers every registered contract schema with at least one schema-valid and one schema-invalid focused fixture. The deterministic `validate-fixture-matrix` command checks all 35 registered contract types, verifies every referenced fixture through its existing dependency-free contract validator, and requires the ten task 2.9 invalid boundaries exactly once.
+
+The required invalid boundaries are:
+
+- missing Workspace Identity;
+- stale Profile Change Candidate base digest;
+- forged Operation Grant digest;
+- ineligible Operation Grant issuer;
+- duplicate actor used for a distinct-actor quorum;
+- revoked approval evidence;
+- validation evidence from the wrong trust class;
+- dangling governance dependency;
+- Return Receipt bound to a changed subject;
+- cross-workspace authority, Operation Grant, or Receipt collapse.
+
+## Validation Layers
+
+`schema` cases contain at least one structurally invalid contract and are rejected by the current hand-validator. `cross-contract` cases intentionally keep every component schema-valid and declare the observations that a later evaluator must compare. The fixture checker validates coverage, references, component schema validity, expected rejection labels, and the explicit `evaluatorImplemented: false` boundary; it does not make transition, quorum, issuer, trust, freshness, subject, or dependency decisions.
+
+The alpha Profile Change Candidate does not contain a base-digest field, and canonical Grant digest computation is not defined yet. Their task 2.9 cases therefore preserve mismatching comparison inputs in fixture metadata without modifying the existing contract or implementing task 2.10 serialization/digest rules. The future Profile Change Candidate successor and evaluators must consume these fixtures when their separately gated tasks begin.
+
+Run the focused and full checks with:
+
+```bash
+node scripts/forgerail.mjs validate-fixture-matrix
+node scripts/forgerail.mjs validate-fixtures
+npm test
+```

package/docs/control-system-fixture-matrix.zh-CN.md

@@ -0,0 +1,30 @@
+# Control System Fixture Matrix
+
+ForgeRail 的 pre-evaluator fixture gate 为每个已注册 contract schema 至少提供一个 schema-valid 与一个 schema-invalid focused fixture。确定性的 `validate-fixture-matrix` 命令检查全部 35 个已注册 contract type，用既有 dependency-free contract validator 验证每个引用 fixture，并要求 task 2.9 的十类 invalid boundary 各出现且只出现一次。
+
+必须覆盖的 invalid boundary 包括：
+
+- 缺失 Workspace Identity；
+- Profile Change Candidate 的 base digest 已 stale；
+- Operation Grant digest forged；
+- Operation Grant issuer 不具备资格；
+- distinct-actor quorum 重复使用同一 actor；
+- approval evidence 已 revoked；
+- validation evidence 的 trust class 错误；
+- governance dependency dangling；
+- Return Receipt 绑定了已经变化的 subject；
+- 跨 workspace 折叠 authority、Operation Grant 或 Receipt。
+
+## Validation layer
+
+`schema` case 至少包含一个结构无效的 contract，并由当前 hand-validator 拒绝。`cross-contract` case 刻意保持所有 component schema-valid，只声明未来 evaluator 必须比较的 observation。fixture checker 只验证覆盖率、引用、component schema validity、预期拒绝标签与显式 `evaluatorImplemented: false` 边界；它不做 transition、quorum、issuer、trust、freshness、subject 或 dependency 决策。
+
+alpha Profile Change Candidate 尚无 base-digest 字段，canonical Grant digest 计算也尚未定义。因此 task 2.9 fixture 只在 metadata 中保留不一致的 comparison input，不修改既有合同，也不实现 task 2.10 serialization/digest 规则。未来的 Profile Change Candidate successor 与 evaluator 必须在各自独立 gate 获批后消费这些 fixture。
+
+运行 focused 与 full check：
+
+```bash
+node scripts/forgerail.mjs validate-fixture-matrix
+node scripts/forgerail.mjs validate-fixtures
+npm test
+```

package/docs/control-task-contracts.md

@@ -0,0 +1,39 @@
+# Control Task Contracts
+
+ForgeRail keeps the alpha Task Envelope and Return Receipt intact while adding versioned Control System task contracts in the same package.
+
+| Contract | Schema version | File |
+| --- | --- | --- |
+| Task Envelope | 2.0 | `contracts/task-envelope-v2.schema.json` |
+| Operation Authority Requirement | 1.0 | `contracts/operation-authority-requirement-v1.schema.json` |
+| Operation Grant | 1.0 | `contracts/operation-grant-v1.schema.json` |
+| Task Control Revision | 1.0 | `contracts/task-control-revision-v1.schema.json` |
+| Entry Mode | 1.0 | `contracts/entry-mode-v1.schema.json` |
+| Phase/Slice Correlation | 1.0 | `contracts/phase-slice-correlation-v1.schema.json` |
+| Gate Result | 1.0 | `contracts/gate-result-v1.schema.json` |
+| Evidence Identity | 1.0 | `contracts/evidence-identity-v1.schema.json` |
+| Return Receipt | 2.0 | `contracts/return-receipt-v2.schema.json` |
+| Rollback Envelope Lineage | 1.0 | `contracts/rollback-envelope-lineage-v1.schema.json` |
+
+These contracts establish the task-control identity boundary without implementing the evaluator:
+
+- every Envelope, revision, gate, evidence item, and Receipt binds one exact Workspace Identity and subject;
+- `new`, `resumed`, and `imported` entry modes remain explicit, and resumed/imported work requires source evidence;
+- Core closure stays on one exact owner phase/slice and never claims aggregate closure;
+- an Operation Grant binds one executor, operation, exact target/ref/environment, subject, scope, authority requirement, issuer evidence, and validity window;
+- review or validation evidence does not mint an Operation Grant;
+- task-control revisions and Receipts are immutable identity-bearing claims; changed subjects or evidence require successors;
+- a Host receipt is not complete until receipt verification is satisfied and unresolved deviations are absent;
+- rollback uses a new Envelope revision, rollback-specific grants, validation, and Receipt; forward grants cannot be reused.
+
+The alpha `task-envelope-v1` and `return-receipt-v1` schemas and their runtime paths are unchanged. Review-authority lifecycle, validation topology/result, Execution Context, adapter observations, and bounded limited reasons are defined in [Control Authority And Validation Contracts](control-authority-validation-contracts.md). The Workspace Receipt Bundle is defined by the [Cross-Workspace Pack Composition Contract](cross-workspace-pack-composition-contract.md), and its pre-evaluator invalid boundaries are included in the [Control System Fixture Matrix](control-system-fixture-matrix.md). Canonical serialization, digest calculation, and version negotiation remain later work.
+
+Run the focused checks with:
+
+```bash
+node scripts/forgerail.mjs validate
+node scripts/forgerail.mjs validate-fixtures
+node scripts/forgerail.mjs validate-contract --type task-envelope-v2 --file scripts/fixtures/contracts/task-envelope-v2.valid.json
+node scripts/forgerail.mjs validate-contract --type operation-grant --file scripts/fixtures/contracts/operation-grant.valid.json
+node scripts/forgerail.mjs validate-contract --type return-receipt-v2 --file scripts/fixtures/contracts/return-receipt-v2.valid.json
+```

package/docs/control-task-contracts.zh-CN.md

@@ -0,0 +1,39 @@
+# Control Task 合同
+
+ForgeRail 在同一个 package 内增加版本化 Control System 任务合同，同时保持 alpha Task Envelope 与 Return Receipt 不变。
+
+| 合同 | Schema 版本 | 文件 |
+| --- | --- | --- |
+| Task Envelope | 2.0 | `contracts/task-envelope-v2.schema.json` |
+| Operation Authority Requirement | 1.0 | `contracts/operation-authority-requirement-v1.schema.json` |
+| Operation Grant | 1.0 | `contracts/operation-grant-v1.schema.json` |
+| Task Control Revision | 1.0 | `contracts/task-control-revision-v1.schema.json` |
+| Entry Mode | 1.0 | `contracts/entry-mode-v1.schema.json` |
+| Phase/Slice Correlation | 1.0 | `contracts/phase-slice-correlation-v1.schema.json` |
+| Gate Result | 1.0 | `contracts/gate-result-v1.schema.json` |
+| Evidence Identity | 1.0 | `contracts/evidence-identity-v1.schema.json` |
+| Return Receipt | 2.0 | `contracts/return-receipt-v2.schema.json` |
+| Rollback Envelope Lineage | 1.0 | `contracts/rollback-envelope-lineage-v1.schema.json` |
+
+这些合同只固定任务控制的身份与边界，不实现 evaluator：
+
+- 每个 Envelope、revision、gate、evidence 与 Receipt 都绑定一个精确 Workspace Identity 和 subject；
+- `new`、`resumed`、`imported` entry mode 保持显式，resumed/imported 必须携带来源证据；
+- Core closure 只覆盖一个精确 owner phase/slice，不能声明 aggregate closure；
+- Operation Grant 精确绑定 executor、operation、target/ref/environment、subject、scope、authority requirement、issuer evidence 与有效期；
+- review 或 validation evidence 不能 mint Operation Grant；
+- task-control revision 与 Receipt 是带 identity 的不可变 claim；subject 或 evidence 变化时必须产生 successor；
+- Host receipt 在 receipt verification 满足且没有未解决 deviation 前不能 complete；
+- rollback 必须使用新 Envelope revision、rollback-specific grant、validation 与 Receipt，禁止复用 forward grant。
+
+冻结的 alpha `task-envelope-v1`、`return-receipt-v1` schema 与 runtime path 均不改变。Review Authority lifecycle、Validation Topology/result、Execution Context、Adapter observation 与 bounded limited reason 已定义在 [Control Authority 与 Validation 合同](control-authority-validation-contracts.zh-CN.md)中。Workspace Receipt Bundle 已由 [Cross-Workspace Pack Composition 合同](cross-workspace-pack-composition-contract.zh-CN.md)定义，其 pre-evaluator invalid boundary 已纳入 [Control System Fixture Matrix](control-system-fixture-matrix.zh-CN.md)。canonical serialization、digest 计算与 version negotiation 仍属于后续任务。
+
+运行聚焦校验：
+
+```bash
+node scripts/forgerail.mjs validate
+node scripts/forgerail.mjs validate-fixtures
+node scripts/forgerail.mjs validate-contract --type task-envelope-v2 --file scripts/fixtures/contracts/task-envelope-v2.valid.json
+node scripts/forgerail.mjs validate-contract --type operation-grant --file scripts/fixtures/contracts/operation-grant.valid.json
+node scripts/forgerail.mjs validate-contract --type return-receipt-v2 --file scripts/fixtures/contracts/return-receipt-v2.valid.json
+```

package/docs/cross-workspace-pack-composition-contract.md

@@ -0,0 +1,31 @@
+# Cross-Workspace Pack Composition Contract
+
+ForgeRail defines one versioned `cross-workspace-pack-composition-v1` contract for an optional Cross-Workspace Orchestration Pack. The Pack composes independent Core-governed workspaces; it does not introduce a second state model, authority system, grant mechanism, or receipt-verification path.
+
+The contract binds these composition surfaces:
+
+- `coreCompatibility` declares the supported Workspace Identity, Task Envelope, Return Receipt, and Phase/Slice Correlation schema versions, plus the Evidence Identities that support the compatibility claim.
+- `workspaceSet` identifies at least two independent owner workspaces, the optional coordinator workspace, the aggregate writer, and the governing relationships.
+- every node keeps one owner Workspace Identity, one writer identity, one `task-envelope-v2` reference, one `phase-slice-correlation-v1` reference, and at most one `return-receipt-v2` reference;
+- dependency edges remain directional and may unlock only from a Core-verified Receipt that the coordinator independently accepts;
+- phase aggregation partitions every required node into accepted, pending, failed, blocked, or stale state; aggregate closure is permitted only when all required nodes are accepted;
+- the immutable Workspace Receipt Bundle binds the composition, Workspace Set, phases, accepted Core Receipts, dependency status, unresolved nodes, deviations, and next eligible nodes.
+
+## Kernel Boundaries
+
+The Pack cannot redefine Core or weaken Kernel invariants. Its invariant flags are fixed to `false`: no state-model redefinition, Operation Grant minting, authority substitution, waiver or freshness broadening, receipt-verification bypass, or treating transport as acceptance.
+
+Receipt delivery, Core verification, and coordinator acceptance remain independent claims. A delivered Receipt is not necessarily verified or accepted. A node cannot become accepted, unlock a required successor, or enter an accepted bundle until its Core Receipt is verified and coordinator acceptance carries Evidence Identity references.
+
+Writer identity is explicit. Concurrent nodes cannot share a writer unless a dependency edge orders them. Dependency edges never transfer authority, Operation Grants, or Receipts between workspaces.
+
+This contract defines only the schema, deterministic hand-validation, schema-native assertions, and focused fixtures. The pre-evaluator authority-collapse and other invalid boundaries are recorded in the [Control System Fixture Matrix](control-system-fixture-matrix.md); canonical serialization, digest computation, and version negotiation remain task 2.10. No Pack runtime, evaluator, adapter expansion, or alpha contract migration is implemented here.
+
+Run the focused checks with:
+
+```bash
+node scripts/forgerail.mjs validate
+node scripts/forgerail.mjs validate-fixtures
+node scripts/forgerail.mjs validate-contract --type cross-workspace-pack-composition --file scripts/fixtures/contracts/cross-workspace-pack-composition.valid.json
+node scripts/forgerail.mjs validate-contract --type cross-workspace-pack-composition --file scripts/fixtures/contracts/cross-workspace-pack-composition.false-closure.invalid.json
+```

package/docs/cross-workspace-pack-composition-contract.zh-CN.md

@@ -0,0 +1,31 @@
+# Cross-Workspace Pack Composition 合同
+
+ForgeRail 为可选的 Cross-Workspace Orchestration Pack 定义一个版本化 `cross-workspace-pack-composition-v1` 合同。Pack 只组合多个独立的 Core-governed workspace；它不引入第二套状态模型、authority system、grant mechanism 或 receipt-verification path。
+
+合同绑定以下 composition surface：
+
+- `coreCompatibility` 声明支持的 Workspace Identity、Task Envelope、Return Receipt 与 Phase/Slice Correlation schema 版本，以及支撑兼容性声明的 Evidence Identity；
+- `workspaceSet` 标识至少两个独立 owner workspace、可选 coordinator workspace、aggregate writer 与治理 relationship；
+- 每个 node 保留一个 owner Workspace Identity、一个 writer identity、一个 `task-envelope-v2` 引用、一个 `phase-slice-correlation-v1` 引用，并且最多引用一个 `return-receipt-v2`；
+- dependency edge 保持有向，只能由 Core 已验证且 coordinator 独立接受的 Receipt 解锁；
+- phase aggregation 把每个 required node 精确归入 accepted、pending、failed、blocked 或 stale；只有全部 required node 都 accepted 时才能声明 aggregate closure；
+- 不可变 Workspace Receipt Bundle 绑定 composition、Workspace Set、phase、已接受的 Core Receipt、dependency status、未解决 node、deviation 与 next eligible node。
+
+## Kernel 边界
+
+Pack 不能重定义 Core，也不能弱化 Kernel invariant。合同中的 invariant flag 全部固定为 `false`：禁止重定义状态模型、mint Operation Grant、authority substitution、扩大 waiver/freshness、绕过 receipt verification，或把 transport 当作 acceptance。
+
+Receipt delivery、Core verification 与 coordinator acceptance 是相互独立的 claim。delivered Receipt 不必然 verified 或 accepted。在 Core Receipt 完成验证且 coordinator acceptance 携带 Evidence Identity 引用之前，node 不能成为 accepted、不能解锁 required successor，也不能进入 accepted bundle。
+
+writer identity 必须显式记录。并发 node 不能共享 writer，除非 dependency edge 已经为它们建立顺序。dependency edge 永远不能在 workspace 之间转移 authority、Operation Grant 或 Receipt。
+
+本合同只定义 schema、deterministic hand-validation、schema-native assertion 与 focused fixture。pre-evaluator authority-collapse 及其他 invalid boundary 已记录在 [Control System Fixture Matrix](control-system-fixture-matrix.zh-CN.md)；canonical serialization、digest 计算与 version negotiation 属于 task 2.10。本任务不实现 Pack runtime、evaluator、adapter expansion 或 alpha contract migration。
+
+运行聚焦校验：
+
+```bash
+node scripts/forgerail.mjs validate
+node scripts/forgerail.mjs validate-fixtures
+node scripts/forgerail.mjs validate-contract --type cross-workspace-pack-composition --file scripts/fixtures/contracts/cross-workspace-pack-composition.valid.json
+node scripts/forgerail.mjs validate-contract --type cross-workspace-pack-composition --file scripts/fixtures/contracts/cross-workspace-pack-composition.false-closure.invalid.json
+```

package/docs/installation.md

@@ -2,9 +2,13 @@
 
 ForgeRail is primarily an Agent Plugin. The npm package is an optional deterministic CLI and compatibility payload.
 
+The canonical source currently proposes `@echopath-labs/forgerail@0.1.0-alpha.2` / `v0.1.0-alpha.2`, but that candidate is not yet remotely integrated or released. Do not construct an installation command from a local version proposal. The commands below remain bound to the currently released alpha.1 until a separately approved alpha.2 release completes.
+
 ## Install
 
-After `v0.1.0-alpha.1` is published, register the immutable Marketplace snapshot and install the main Plugin:
+The intended default human route is the Universal Plugins Directory in ChatGPT or Codex. ForgeRail is **not currently available there**: the local Skills-only candidate still needs separately approved submission, OpenAI review, and developer publication. When a verified ForgeRail listing becomes available, use that interface and confirm the publisher and requested capabilities before installation.
+
+The current available Agent Plugin route is the immutable `v0.1.0-alpha.1` EchoPath Labs Marketplace snapshot:
 
 ```bash
 codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.1
@@ -17,6 +21,8 @@ Start a new Codex task after installation so discovery uses the installed snapsh
 - `$forgerail-workspace-diagnosis`;
 - `$workspace-health-review`.
 
+This Agent Plugin route does not require the target project to have Node.js, `package.json`, `node_modules`, or the optional npm CLI.
+
 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
@@ -83,6 +89,6 @@ Re-register the last validated Marketplace tag and reinstall the selected Plugin
 
 ## 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.
+Creating or submitting a Universal Plugins Directory draft, publishing a reviewed listing, publishing npm, moving `latest`, pushing a public candidate, tagging, creating a GitHub Release, or changing AGW lifecycle requires its own exact approval and receipt.
 
-See [ForgeRail 0.1.0-alpha.1 Release Runbook](release.md) for the project-owned gate order and rollback boundary.
+See the historical [ForgeRail 0.1.0-alpha.1 Release Runbook](release.md) for the current release and the [ForgeRail 0.1.0-alpha.2 Candidate Runbook](release-alpha2.md) for the proposed source-first gate order. Neither document grants execution authority.

package/docs/installation.zh-CN.md

@@ -2,7 +2,11 @@
 
 ForgeRail 的主要形态是 Agent Plugin；npm 包是可选的确定性 CLI 与兼容载荷。
 
-在 `v0.1.0-alpha.1` 发布后，注册不可变的 Marketplace 快照并安装主插件：
+canonical source 当前拟议 `@echopath-labs/forgerail@0.1.0-alpha.2` / `v0.1.0-alpha.2`，但该候选尚未远端集成或发布。不要根据本地版本提案自行拼装安装命令。以下命令继续绑定当前已发布 alpha.1，直到另行批准的 alpha.2 发布完成。
+
+面向人的目标默认入口是 ChatGPT 或 Codex 中的 Universal Plugins Directory。ForgeRail **当前尚未在该目录上线**：本地 Skills-only 候选仍需独立提交审批、OpenAI 审查和开发者发布。以后只有在核对真实 ForgeRail listing、publisher 和能力请求后，才应从界面安装。
+
+当前可用的 Agent Plugin 路径是不可变的 EchoPath Labs Marketplace `v0.1.0-alpha.1` 快照：
 
 ```bash
 codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.1
@@ -11,6 +15,8 @@ codex plugin add forgerail@echopath-labs
 
 安装后启动一个新的 Codex 任务，使插件发现基于已安装快照。新任务必须发现 `$forgerail`、`$forgerail-workspace-diagnosis` 和 `$workspace-health-review`。需要可复现安装时，不要用可变分支替代精确 tag。
 
+通过该 Agent Plugin 路径使用 ForgeRail，不要求目标项目安装 Node.js，也不要求存在 `package.json`、`node_modules` 或可选 npm CLI。
+
 GitHub Rulesets、Release Safety 与 Thread Closure 是单独插件，只按项目需要安装：
 
 ```bash
@@ -55,6 +61,6 @@ 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 生命周期变更都属于独立审批门。
+创建或提交 Universal Plugins Directory draft、发布已审查 listing、npm 发布、移动 `latest`、推送公共候选、tag、GitHub Release 和 AGW 生命周期变更都属于各自独立的精确审批门。
 
-项目专属门序与回滚边界见 [ForgeRail 0.1.0-alpha.1 发布 Runbook](release.zh-CN.md)。
+当前发布的历史门序见 [ForgeRail 0.1.0-alpha.1 发布 Runbook](release.zh-CN.md)，拟议 source-first 门序见 [ForgeRail 0.1.0-alpha.2 候选 Runbook](release-alpha2.zh-CN.md)。两份文档都不授予执行权限。

package/docs/release-alpha2.md

@@ -0,0 +1,21 @@
+# ForgeRail 0.1.0-alpha.2 Candidate Runbook
+
+This source-first runbook governs the proposed `@echopath-labs/forgerail@0.1.0-alpha.2`, tag `v0.1.0-alpha.2`, and matching Agent Plugin projection. It does not grant `remote_integration_approval`, `release_approval`, `submission_approval`, or `lifecycle_change_approval`. The unscoped `forgerail@0.0.0-reserved.0` remains a reservation and must never receive product code or serve as an install or rollback source.
+
+## Candidate integration
+
+The public candidate is an ordinary child of the observed remote `main`. A future exact `remote_integration_approval` may push only the signed commit to `codex/forgerail-alpha2-scoped`, create one Draft PR, and observe Node.js 22 and 24 Plugin Contracts CI. The Draft PR base and publication comparison baseline remain bound to the observed remote `main`.
+
+Any correction is an ordinary source-first successor commit. Do not force push, rewrite the candidate, transition the PR to Ready, merge, tag, publish, or create a release under remote-integration authority. Install and discover each external Capability Pack separately; availability never implies authentication, enablement, or mutation authority.
+
+## Separate release gate
+
+Only a later exact `release_approval` can authorize Ready/merge, scoped npm publication, dist-tags, annotated tag, GitHub prerelease, and disposable consumer verification. The merged public `main` tree must equal the final signed projection tree before release validation begins.
+
+Run Node.js 22 and 24 checks for Core, contracts, external Packs, frozen AGW behavior coverage, release source, Directory readiness, disposable consumer lifecycle, pack metadata, and audit. Verify GitHub API/SSH/npm identity as `chasechou007` without exposing credentials. Preserve Apache-2.0, the unscoped reservation, and the immutable alpha.1 package/tag.
+
+Do not unpublish or move an immutable version or Git tag. A shipped defect requires a forward version. Installation and diagnosis must leave project files unchanged unless the user separately approves an exact managed binding; return a Host Binding Receipt and confirm no implicit `.forgerail/` state.
+
+## Independent Directory and lifecycle gates
+
+Universal Plugins Directory draft, submission, review publication, verified publisher identity, Apps Management Write, portal regions and assets remain under a separate `submission_approval` or publication gate. AGW deprecation, redirect, archive, or deletion requires `lifecycle_change_approval`. No approval is transitive.

package/docs/release-alpha2.zh-CN.md

@@ -0,0 +1,21 @@
+# ForgeRail 0.1.0-alpha.2 候选 Runbook
+
+本 source-first runbook 约束拟议的 `@echopath-labs/forgerail@0.1.0-alpha.2`、tag `v0.1.0-alpha.2` 与对应 Agent Plugin 投影。文档本身不授予 `remote_integration_approval`、`release_approval`、`submission_approval` 或 `lifecycle_change_approval`。未作用域 `forgerail@0.0.0-reserved.0` 继续只作占位，不得接收产品代码，也不是安装或回滚来源。
+
+## 候选集成
+
+公共候选是已观测远端 `main` 的普通子 commit。未来精确 `remote_integration_approval` 只能把签名 commit 推到 `codex/forgerail-alpha2-scoped`，创建一个 Draft PR，并观察 Node.js 22 and 24 Plugin Contracts CI。Draft PR base 与 publication comparison baseline 继续绑定已观测远端 `main`。
+
+任何修正都必须形成普通的 source-first successor commit。remote integration 权限不允许 force push、历史重写、转 Ready、merge、tag、publish 或创建 Release。每个外部 Capability Pack 分别安装与发现；可用不等于认证、启用或获得 mutation authority。
+
+## 独立发布门
+
+只有后续精确 `release_approval` 才能授权 Ready/merge、scoped npm 发布、dist-tag、annotated tag、GitHub prerelease 与一次性消费者验证。发布验证开始前，合并后的公共 `main` tree 必须等于最终签名 projection tree。
+
+在 Node.js 22 和 24 上运行 Core、contracts、external Packs、冻结 AGW 行为覆盖、release source、Directory readiness、一次性 consumer、pack metadata 与 audit。不得暴露凭据地确认 GitHub API/SSH/npm 身份为 `chasechou007`。保持 Apache-2.0、未作用域占位和不可变 alpha.1 package/tag。
+
+Do not unpublish 或移动不可变 version/tag。已发布缺陷使用前向版本修复。安装和诊断默认不修改项目；只有用户另行批准精确 managed binding 后才写入，并返回 Host Binding Receipt，确认没有隐式 `.forgerail/` 状态。
+
+## 独立 Directory 与生命周期门
+
+Universal Plugins Directory draft、submit、review publication、verified publisher identity、Apps Management Write、portal regions/assets 继续属于独立 `submission_approval` 或 publication gate。AGW deprecation、redirect、archive 或 deletion 需要 `lifecycle_change_approval`。任何审批都不传递。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@echopath-labs/forgerail",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Deterministic validation and diagnosis CLI for the ForgeRail Agent Plugin.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,9 +9,11 @@
   },
   "files": [
     ".codex-plugin/",
+    "assets/",
     "adapters/",
     "contracts/",
     "docs/",
+    "directory/",
     "marketplace/",
     "packs/",
     "scripts/",
@@ -22,9 +24,11 @@
     "LICENSE",
     "NOTICE",
     "PLUGIN.md",
+    "PRIVACY.md",
     "README.md",
     "README.zh-CN.md",
-    "SECURITY.md"
+    "SECURITY.md",
+    "TERMS.md"
   ],
   "engines": {
     "node": ">=22"
@@ -34,8 +38,10 @@
     "test:consumer": "node scripts/disposable-consumer.mjs",
     "test:release": "node scripts/validate-release.mjs",
     "test:shadow": "node scripts/shadow-comparison.mjs",
+    "test:directory": "node scripts/validate-universal-directory.mjs",
+    "build:directory-candidate": "node scripts/build-universal-directory-candidate.mjs",
     "diagnose:fixture": "node scripts/forgerail.mjs diagnose --workspace scripts/fixtures/workspaces/markdown-existing",
-    "prepublishOnly": "npm test && npm run test:shadow && npm run test:release && npm run test:consumer"
+    "prepublishOnly": "npm test && npm run test:shadow && npm run test:release && npm run test:consumer && npm run test:directory"
   },
   "repository": {
     "type": "git",

package/packs/architecture-convergence-audit.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "1.0",
+  "id": "architecture-convergence-audit",
+  "purpose": "Trace capability ownership and return the smallest evidence-backed implementation boundary without changing the workspace.",
+  "entry": "skills/architecture-convergence-audit/SKILL.md",
+  "risk": "medium",
+  "states": ["available", "recommended", "enabled", "required", "blocked", "disabled"],
+  "triggers": [
+    "explicit architecture convergence request",
+    "mature capability appears rebuilt in a new context",
+    "duplicate identity state recovery parser or schema ownership signal"
+  ],
+  "inputs": [
+    "requested outcomes and non-goals",
+    "reproducible baseline and freshness",
+    "governance source inventory",
+    "effective profile and task envelope",
+    "implementation callers persistence lifecycle and validation evidence"
+  ],
+  "dependencies": [],
+  "conflicts": [],
+  "approvals": [],
+  "validation": [
+    "analysis remains read-only and labels inference",
+    "ownership map traces durable facts and current consumers",
+    "deletion recommendations preserve required invariants and failure coverage",
+    "no profile task ledger receipt state or external tracker is created"
+  ],
+  "receiptExtensions": ["convergenceStatus", "ownershipMap", "remainingBoundary"]
+}

package/scripts/build-universal-directory-candidate.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const include = [
+  ".codex-plugin/plugin.json",
+  "CHANGELOG.md",
+  "PRIVACY.md",
+  "README.md",
+  "README.zh-CN.md",
+  "TERMS.md",
+  "assets",
+  "directory",
+  "docs/installation.md",
+  "docs/installation.zh-CN.md",
+  "scripts/build-universal-directory-candidate.mjs",
+  "scripts/fixtures/workspaces/no-node-project",
+  "scripts/validate-universal-directory.mjs",
+  "skills"
+];
+
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function filesAt(path) {
+  if (!existsSync(path)) throw new Error(`candidate source does not exist: ${path}`);
+  if (statSync(path).isFile()) return [path];
+  return readdirSync(path, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((entry) => filesAt(resolve(path, entry.name)));
+}
+
+const paths = [...new Set(include.flatMap((entry) => filesAt(resolve(pluginRoot, entry))))]
+  .sort((a, b) => a.localeCompare(b));
+const inventory = paths.map((path) => {
+  const content = readFileSync(path);
+  return {
+    path: relative(pluginRoot, path).split(sep).join("/"),
+    bytes: content.length,
+    sha256: sha256(content)
+  };
+});
+const manifest = JSON.parse(readFileSync(resolve(pluginRoot, ".codex-plugin/plugin.json"), "utf8"));
+const candidate = JSON.parse(readFileSync(resolve(pluginRoot, "directory/submission-candidate.json"), "utf8"));
+const result = {
+  schemaVersion: "1.0",
+  candidateType: "openai-universal-plugin-directory-skills-only",
+  status: "local_candidate",
+  approvalStatus: candidate.approval.status,
+  product: manifest.name,
+  pluginVersion: manifest.version,
+  privateBaseline: "59c7bb52f16cda2d47a8a49bb43860517f9bd7eb",
+  sourceDate: "2026-08-30",
+  inventory,
+  contentDigest: sha256(JSON.stringify(inventory)),
+  unresolvedGates: candidate.unresolvedGates,
+  nonMutations: candidate.confirmedNonMutations
+};
+
+const outputFlag = process.argv.indexOf("--output");
+const serialized = `${JSON.stringify(result, null, 2)}\n`;
+if (outputFlag >= 0) {
+  const output = process.argv[outputFlag + 1];
+  if (!output) throw new Error("--output requires a path");
+  writeFileSync(resolve(process.cwd(), output), serialized);
+}
+process.stdout.write(serialized);

package/scripts/disposable-consumer.mjs

@@ -128,7 +128,7 @@ const result = {
   adoptionPlan: adoptionPlan.strategy === "single-host-managed-block" && adoptionPlan.requiredConfirmation && adoptionPlan.mutations.length === 0 && proposed.path === "AGENTS.md",
   targetUnchangedByPlanner: after === afterPlan,
   explicitApprovedWrite: approvedDigest === sha256(approvedContent) && approvedContent.includes("forgerail:binding:codex:v1:start"),
-  equivalentNewTaskDiscovery: bindingReceipt.activationVerification.verified && discoveredSkills.length === 3,
+  equivalentNewTaskDiscovery: bindingReceipt.activationVerification.verified && discoveredSkills.length === 4,
   bindingReceipt: receiptValidation.valid,
   noPersistedGovernance: !existsSync(resolve(target, ".forgerail")),
   launch: launch.valid && launch.launch.executionOwner === "host-agent",

package/scripts/fixtures/contracts/authority-evidence.revoked-without-invalidation.invalid.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "1.0",
+  "authorityEvidenceId": "authority-evidence:owner-review-a",
+  "evidenceIdentityId": "evidence:provider-review-a",
+  "requirementId": "review:req-ownership",
+  "workspaceIdentityId": "workspace:forgerail",
+  "operation": "merge",
+  "authorityClass": "ownership_approval",
+  "subjectId": "subject:commit-a",
+  "actorId": "actor:owner-a",
+  "actorRelations": ["surface-owner"],
+  "scope": ["plugins/forgerail/contracts"],
+  "coveredSurfaceIds": ["surface:contracts"],
+  "lifecycle": "revoked",
+  "observedAt": "2026-08-18T15:30:00Z",
+  "effectiveAt": "2026-08-18T15:20:00Z",
+  "expiresAt": "2026-08-18T16:20:00Z",
+  "invalidatedAt": null,
+  "invalidationEvidenceIdentityId": null,
+  "supersededByAuthorityEvidenceId": null,
+  "limitedReason": null
+}