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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "forgerail",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "Engineering guidance and governance for coding agents, with workspace diagnosis and composable capability packs.",
   "author": {
     "name": "EchoPath Labs",

package/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 No shipping changes yet.
 
+## 0.1.0-alpha.4 - 2026-09-01
+
+- Make contract identifiers, calendar values and portable paths fail closed and align the CLI with the published schemas.
+- Reject duplicate Profile, Pack and cross-workspace identities; bind Launch Contracts to the validated Effective Profile and every required active Pack.
+- Harden Adoption and source-repository projection construction against symlink traversal, sensitive files, unsupported file types, partial output and non-deterministic inventory modes.
+- Restore failed Adoption replacements with one atomic rename, reject sensitive projection filenames case-insensitively, and reserve projection outputs without replacing concurrent directories.
+- Materialize every projection descendant through retained no-follow output-directory identities, and represent requested Launch Contract Packs as a schema-native identity-to-manifest-digest map.
+- Bind each approved Adoption write to its canonical workspace and complete executable metadata using one immutable apply-time snapshot, atomically replace an existing managed binding without a missing-target window, and preserve literal four-digit years including `0000` through `0099`.
+- Reject existing Adoption targets unless both managed-block boundary markers occur exactly once, preventing a replacement from preserving duplicate closing or opening markers.
+- Reject non-canonical Adoption paths and mixed-workspace write sets, preserve Task Envelope inputs during Launch construction, encode Effective Profile Packs as identity-keyed objects, and apply projection directory deny lists case-insensitively.
+- Make Shadow comparison independent from its expected phrases and fail non-zero when coverage is missing.
+- Reject unknown orchestration operations, dependencies and conflicting terminal events; handle malformed receipts and package metadata without crashes or private absolute paths.
+- Add complete Node.js 22 and 24 integrity, Core, shadow, release, consumer, Directory and external Pack gates while preserving Skills-only installation, no project Node.js requirement, no implicit `.forgerail/` state and Apache-2.0.
+
 ## 0.1.0-alpha.3 - 2026-08-31
 
 - Keep the main Agent Plugin within Codex's maximum of three `defaultPrompt` entries while preserving discovery and direct invocation for all four ForgeRail Skills.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,34 @@
+# Code of Conduct
+
+## Our commitment
+
+We want the ForgeRail community to be a respectful place for people with different backgrounds, experience levels, languages, identities, and perspectives. Participation should make technical disagreement safer and the project better.
+
+## Expected behavior
+
+- Be respectful, specific, and constructive.
+- Critique ideas, evidence, and changes rather than people.
+- State uncertainty and correct mistakes openly.
+- Respect privacy, confidentiality, attribution, and consent.
+- Help newcomers understand project boundaries without gatekeeping.
+- Accept maintainer decisions about scope while remaining free to propose alternatives.
+
+## Unacceptable behavior
+
+- Harassment, threats, discrimination, sexualized attention, or personal attacks;
+- deliberate intimidation, disruption, or repeated bad-faith argument;
+- publishing another person's private information without permission;
+- sharing credentials, private project data, customer information, or security details that should remain confidential;
+- using project channels to promote unrelated products or services repeatedly.
+
+## Scope and enforcement
+
+This policy applies in ForgeRail repositories, issues, pull requests, reviews, discussions, release channels, and public spaces where someone represents the project.
+
+Report conduct concerns privately through the repository's private security/advisory contact route and label the report as a conduct concern. If that route is unavailable, open a minimal public issue asking for a private maintainer contact without describing sensitive details.
+
+Maintainers may edit or remove content, issue a warning, temporarily restrict participation, or permanently ban a participant when necessary. They will seek to minimize disclosure and conflicts of interest. Good-faith reports will not be retaliated against.
+
+## Attribution
+
+This policy is informed by the Contributor Covenant and common open-source community practice, adapted to ForgeRail's privacy and agent-governance boundaries.

package/CONTRIBUTING.md

@@ -1,7 +1,71 @@
-# Contributing
+# Contributing to ForgeRail
 
-Contributions should preserve ForgeRail's non-executor boundary, existing-habits-first diagnosis, progressive loading, explicit approvals, and deterministic receipts.
+Thank you for helping make agent-assisted engineering more understandable, bounded, and verifiable.
 
-Start domain-specific behavior as a Capability Pack. Keep project facts and private release procedures in the owning workspace. Add positive and fail-closed fixtures for contract changes, run the Plugin and Skill validators, and document migration impact.
+ForgeRail is not a general automation framework. Contributions should preserve its core boundary: **the Agent performs the engineering work, ForgeRail guides scope and evidence, and a human retains meaningful decisions.**
 
-Contributions are accepted under Apache-2.0.
+## Before opening work
+
+Use a GitHub issue when the change affects product behavior, contracts, adoption semantics, supported hosts, Capability Packs, security boundaries, or release compatibility. Small documentation corrections may go directly to a pull request.
+
+Search existing issues first. Do not include credentials, private project memory, customer data, production configuration, private repository paths, or unredacted receipts.
+
+## Development setup
+
+ForgeRail's public package uses Node.js 22 or newer for deterministic validation and fixtures:
+
+```bash
+npm ci
+npm test
+```
+
+Plugin users do not need project-local Node.js; this development requirement applies only to contributors and optional CLI users.
+
+Useful focused checks include:
+
+```bash
+npm run test:docs
+npm run test:shadow
+npm run test:consumer
+npm run test:directory
+npm run test:release
+```
+
+Run the official Plugin and Skill validators when changing manifests, Skills, or Plugin discovery. Keep all tests deterministic and network-free unless a separately reviewed integration test explicitly requires otherwise.
+
+## Design principles
+
+- Follow the project's existing governance sources before proposing ForgeRail-specific state.
+- Prefer Plugin Only; recommend Lightweight Adoption only with evidence.
+- Keep persisted `.forgerail/` governance deferred until ownership, precedence, migration, recovery, and deletion are designed.
+- Keep Capability Packs independent when authentication, permissions, side effects, or lifecycle differ.
+- Treat installation, adoption, task authorization, remote integration, release, and lifecycle as separate decisions.
+- Preserve explicit non-actions and fail closed when identity, authority, scope, or evidence is uncertain.
+- Do not turn ForgeRail into an executor, a second OpenSpec/ADR system, or a promise of security correctness.
+
+## Pull requests
+
+Keep each pull request focused and explain:
+
+1. the user problem and owning capability;
+2. what changed and what deliberately did not change;
+3. validation evidence, including positive and fail-closed fixtures;
+4. compatibility, migration, security, and rollback impact;
+5. documentation or release-note updates.
+
+Contract changes need corresponding fixtures. Capability behavior normally belongs in a Pack instead of the Core. Host-specific behavior needs an explicit Host Adapter and must not imply support beyond observed verification.
+
+Use the repository pull-request template. A maintainer may request a smaller scope, additional evidence, or an OpenSpec/ADR before merging a structural change.
+
+## Commit and generated-file hygiene
+
+- Do not commit secrets, local absolute paths, caches, temporary projections, package tarballs, or private governance evidence.
+- Preserve generated-file provenance and use the documented builder rather than hand-editing public projections.
+- Do not rewrite published tags, npm versions, receipts, or release evidence; defects move forward in a new version.
+- Keep formatting changes separate from behavioral changes when practical.
+
+## Community and license
+
+Be respectful and follow the [Code of Conduct](CODE_OF_CONDUCT.md). Usage questions belong in the route described by [SUPPORT.md](SUPPORT.md); vulnerabilities must follow [SECURITY.md](SECURITY.md).
+
+Unless stated otherwise, contributions are accepted under the [Apache License 2.0](LICENSE).

package/README.md

@@ -1,77 +1,154 @@
-# ForgeRail
+<p align="center">
+  <img src="assets/forgerail-logo.svg" alt="ForgeRail" width="520">
+</p>
 
-ForgeRail is an engineering guidance and governance framework for Coding Agents.
+<h1 align="center">ForgeRail</h1>
 
-This canonical source is preparing the local `0.1.0-alpha.3` / `v0.1.0-alpha.3` forward-fix candidate. It is not yet remotely integrated, released, or listed in the Universal Plugins Directory; the currently installable public version remains alpha.2.
+<p align="center"><strong>Engineering guidance and governance for coding agents, without replacing the agent or your project's existing workflow.</strong></p>
 
-It observes a workspace, recommends improvements only when evidence warrants them, composes applicable rules, launches the host Agent with explicit scope and approval boundaries, and verifies observable results. It does not replace the Agent or force a new specification system onto the project.
+<p align="center">
+  <a href="README.zh-CN.md">简体中文</a> ·
+  <a href="docs/installation.md">Installation</a> ·
+  <a href="docs/adoption.md">Adoption</a> ·
+  <a href="https://github.com/echopath-labs/forgerail/issues">Issues</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
 
-## First Alpha Shape
+> **Status:** `0.1.0-alpha.4` is the current public prerelease. Codex is the verified host. Interfaces and guidance can change before a stable release.
 
-- `$forgerail`: task-level guidance and guardrails.
-- `$forgerail-workspace-diagnosis`: bounded read-only diagnosis that follows existing workspace habits first.
-- `$workspace-health-review`: independently invokable workspace governance health pack.
-- `$architecture-convergence-audit`: independently invoked, medium-risk, read-only capability-owner and minimal-boundary audit.
+## Why ForgeRail?
 
-The Architecture Convergence Pack is a post-alpha source candidate. It remains
-available rather than automatically enabled, does not require ForgeRail Core to
-run first, and creates no Profile, task ledger, Receipt, `.forgerail/` state, or
-external issue.
+Coding agents are good at doing work. The hard part is keeping that work aligned with the real project:
 
-GitHub Rulesets, Release Safety, and Thread Closure are separately distributed Capability Packs because they have independent authentication, risk, lifecycle, and release boundaries.
+- Which repository and task actually own this change?
+- What existing instructions, specifications, decisions, and CI checks already apply?
+- What may the agent read or change, and what still needs a human decision?
+- What evidence proves the result, and where should the next agent resume?
 
-Cross-Workspace Orchestration is also separately distributed and explicit-use. It applies only when a master task coordinates multiple genuine owner/repository/release boundaries with safe parallel dependency stages; it is not a general multi-agent mode for one repository.
+ForgeRail helps the agent answer those questions before it expands scope. It observes the workspace, follows existing project habits first, recommends the smallest useful governance level, and verifies observable evidence. **The agent does the work, ForgeRail guides the work, and the human decides.**
 
-The EchoPath Labs Marketplace candidate includes `forgerail-github-rulesets`, `forgerail-release-safety`, `forgerail-thread-closure`, and `forgerail-cross-workspace-orchestration` as separate, explicitly installed Plugins with `ON_USE` policy. They are not installed or activated merely because the main ForgeRail Plugin is selected.
+ForgeRail is not an autonomous executor, a replacement for OpenSpec or `AGENTS.md`, a security guarantee, or a reason to add process to a simple project.
 
-## Architecture
+## Five-minute quickstart
 
-ForgeRail composes four layers:
+### 1. Install the exact Codex Plugin release
 
-1. Core governance;
-2. optional Capability Packs;
-3. an effective Workspace Profile resolved from existing sources;
-4. a temporary Task Envelope.
-
-The Profile is computed by default. ForgeRail does not create `.forgerail/profile.yaml`, edit `AGENTS.md`, or install OpenSpec merely because it was invoked.
+```bash
+codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.4
+codex plugin add forgerail@echopath-labs
+```
 
-The Control System migration now includes versioned Workspace/Profile, Task Control, Review Authority, Validation Topology, Execution Context, Adapter Observation, and Cross-Workspace Pack composition contracts while preserving the alpha v1 contracts. See [Control Profile Contracts](docs/control-profile-contracts.md), [Control Task Contracts](docs/control-task-contracts.md), [Control Authority And Validation Contracts](docs/control-authority-validation-contracts.md), [Cross-Workspace Pack Composition Contract](docs/cross-workspace-pack-composition-contract.md), and the pre-evaluator [Control System Fixture Matrix](docs/control-system-fixture-matrix.md).
+Start a **new Codex task** in the project you want to review. Plugin Only usage does not require Node.js, `package.json`, `node_modules`, or `.forgerail/` in that project.
 
-Workspace adoption is progressive: Plugin Only by default; user-confirmed lightweight bindings when durable guidance is valuable; persisted `.forgerail/` governance only for future evidence-backed machine configuration or repeated conflicts. Host-specific instruction files are adapters, not ForgeRail Core. Codex is supported for alpha.1; Claude Code and Cursor profiles are explicit but unverified.
+### 2. Try it read-only
 
-## Local Validation
+Send this request to Codex:
 
-```bash
-node scripts/forgerail.mjs validate
-node scripts/forgerail.mjs validate-fixtures
-node scripts/forgerail.mjs validate-adoption
-node scripts/validate-release.mjs
-node scripts/forgerail.mjs diagnose --workspace scripts/fixtures/workspaces/markdown-existing
-node scripts/forgerail.mjs adoption-plan --workspace scripts/fixtures/workspaces/markdown-existing --host codex
+```text
+Use $forgerail to assess this project read-only. Follow its existing AGENTS.md,
+specification, ADR, CI, and documentation habits first. Do not modify files or
+perform remote actions. Recommend Plugin Only or Lightweight Adoption, show the
+evidence and uncertainties, and wait for my confirmation before any write.
 ```
 
-The optional official npm package is `@echopath-labs/forgerail`; it exposes the same deterministic CLI through the short `forgerail` binary shim. The unscoped `forgerail` package remains a reservation and is not the product install path.
+### 3. Review the result
 
-```bash
-npm install --global @echopath-labs/forgerail@0.1.0-alpha.2
-forgerail validate
-forgerail diagnose --workspace .
-forgerail adoption-plan --workspace . --host codex
-```
+ForgeRail should return:
+
+- the workspace and task boundary it could actually verify;
+- applicable existing governance sources and unresolved conflicts;
+- the smallest recommended adoption level;
+- validation evidence and explicit non-actions;
+- at most the next decision that needs human confirmation.
+
+If it writes files, creates `.forgerail/`, performs a remote action, or treats installation as approval, report a bug.
+
+## What is included?
+
+| Skill | Use it when | Default effect |
+| --- | --- | --- |
+| `$forgerail` | Starting or governing a non-trivial engineering task | Guidance, scope, approval, and verification boundaries |
+| `$forgerail-workspace-diagnosis` | You need a bounded picture of the current workspace | Read-only diagnosis that follows existing habits first |
+| `$workspace-health-review` | You want to review recovery, ownership, and governance debt | Independent read-only health review |
+| `$architecture-convergence-audit` | You suspect duplicated capabilities or competing owners | Independent read-only ownership and minimal-boundary audit |
+
+Use the exact namespaced Skill name shown by Codex if another installed Plugin defines a Skill with the same short name.
+
+### Optional Capability Pack Plugins
+
+These are separate Plugins because they have different authentication, risk, and lifecycle boundaries:
+
+- `forgerail-github-rulesets`
+- `forgerail-release-safety`
+- `forgerail-thread-closure`
+- `forgerail-cross-workspace-orchestration`
+
+Installing the main ForgeRail Plugin does not install, enable, authenticate, invoke, or approve them. See [External Capability Packs](docs/external-capability-packs.md).
+
+## Progressive adoption
 
-## Install The Prerelease
+ForgeRail separates **availability** from **project adoption**:
 
-The intended future default is the Universal Plugins Directory UI, but ForgeRail is not listed there yet. Until a separate submission, review, and publication complete, install the released exact ForgeRail Marketplace snapshot:
+| Level | What changes in the project? | When to use it |
+| --- | --- | --- |
+| Plugin Only | Nothing | Default; occasional guidance and diagnosis |
+| Lightweight Adoption | One reviewed managed instruction block or `FORGERAIL.md` binding | Repeated use where durable guidance adds value |
+| Persisted Governance | Deferred in the current alpha | Only after machine-consumed configuration has evidence-backed ownership and migration rules |
+
+ForgeRail never applies a Lightweight Adoption plan by itself. The agent must show exact paths and content, obtain confirmation, preserve unrelated content, verify the result in a new task, and return a receipt. Read [Progressive Adoption](docs/adoption.md) for details.
+
+## How it works
+
+ForgeRail composes four layers without making each project persist all four:
+
+1. **Core governance** — portable rules for scope, authority, evidence, validation, and closure.
+2. **Capability Packs** — independent domain capabilities selected only when relevant.
+3. **Effective Workspace Profile** — computed from the project's existing sources by default.
+4. **Temporary Task Envelope** — the bounded task, allowed scope, approvals, checks, and return contract for the current work.
+
+Host instruction files are adapters, not ForgeRail Core. OpenSpec, ADRs, project docs, CI, and code retain their own authority. See [Control Profile Contracts](docs/control-profile-contracts.md), [Task Contracts](docs/control-task-contracts.md), and [Authority and Validation Contracts](docs/control-authority-validation-contracts.md).
+
+## Optional CLI
+
+The npm package exposes deterministic validation and diagnosis for maintainers and CI. It is **not** required for the Agent Plugin or target project.
 
 ```bash
-codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.2
-codex plugin add forgerail@echopath-labs
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 validate
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 diagnose --workspace .
 ```
 
-Start a new Codex task after installation. Install high-risk Capability Packs separately and only when the project needs them. See [Installation And Adoption](docs/installation.md) and [Progressive Adoption](docs/adoption.md) for exact commands, adoption levels, Host Adapter status, upgrade, rollback, and uninstall boundaries.
+The official package is scoped. The unscoped `forgerail` package is only a reservation and is not an install source.
+
+## Documentation
+
+- [Installation, verification, upgrade, and troubleshooting](docs/installation.md)
+- [Progressive project adoption](docs/adoption.md)
+- [Capability Pack boundaries](docs/external-capability-packs.md)
+- [Pack authoring](docs/pack-authoring.md)
+- [Migration from Agent Workflow Governance](docs/migration-from-agw.md)
+- [Architecture acceptance](docs/architecture-acceptance.md)
+- [Alpha.4 release notes and runbook](docs/release-alpha4.md)
+
+## Project status
+
+ForgeRail is usable for real Codex projects through Plugin Only and reviewed Lightweight Adoption, but it remains alpha software:
+
+- Codex is verified; Claude Code and Cursor profiles remain `profile-only`, not verified integrations.
+- Persisted `.forgerail/` governance is deferred.
+- External Capability Packs remain separately installed and explicitly invoked.
+- Universal Plugins Directory publication is paused; exact-tag Marketplace installation is the supported route.
+- Defects are fixed forward in a new version; published tags and packages are not rewritten.
+
+See the [alpha.4 prerelease](https://github.com/echopath-labs/forgerail/releases/tag/v0.1.0-alpha.4) and [changelog](CHANGELOG.md).
+
+## Contributing and support
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Use the repository issue forms for reproducible bugs, product proposals, and documentation problems. Usage questions and troubleshooting start in [SUPPORT.md](SUPPORT.md).
+
+Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md). Never put credentials, private project memory, production configuration, customer data, or unredacted receipts in an issue.
 
-The Agent Plugin does not require Node.js or `package.json` in the target project. npm/npx remains optional maintainer and validation tooling.
+Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
 
-## Status
+## License
 
-The immutable public alpha.2 remains the current install source. Alpha.3 is a local source-first forward fix that limits the main Plugin to three starter prompts while keeping all four Skills independently discoverable and invokable. Its proposed version and tag do not authorize public projection application, remote integration, release, or Directory submission/publication.
+ForgeRail is licensed under [Apache License 2.0](LICENSE). See [NOTICE](NOTICE) for attribution information.

package/README.zh-CN.md

@@ -1,50 +1,153 @@
-# ForgeRail
+<p align="center">
+  <img src="assets/forgerail-logo.svg" alt="ForgeRail" width="520">
+</p>
 
-ForgeRail 是面向 Coding Agent 的工程引航与治理框架。
+<h1 align="center">ForgeRail</h1>
 
-当前 canonical source 正在准备本地 `0.1.0-alpha.3` / `v0.1.0-alpha.3` forward-fix 候选。该候选尚未完成远端集成、发布或 Universal Plugins Directory 上线；当前可安装的公开版本仍是 alpha.2。
+<p align="center"><strong>面向 Coding Agent 的工程引航与治理框架：不替代 Agent，也不替代项目已有工作方式。</strong></p>
 
-它观察工作区，在证据表明存在缺口时提出建议，组装适用规约，以明确的范围和审批边界发起宿主 Agent 工作，并核验可观察结果。它不替代 Agent，也不强迫项目采用新的规格系统。
+<p align="center">
+  <a href="README.md">English</a> ·
+  <a href="docs/installation.zh-CN.md">安装</a> ·
+  <a href="docs/adoption.zh-CN.md">采用</a> ·
+  <a href="https://github.com/echopath-labs/forgerail/issues">Issues</a> ·
+  <a href="CHANGELOG.md">变更记录</a>
+</p>
 
-## 首个 Alpha 形态
+> **当前状态：** `0.1.0-alpha.4` 是当前公开预发布版本。Codex 是已经验证的宿主；稳定版之前，接口与引导方式仍可能变化。
 
-- `$forgerail`：任务级引航与围栏；
-- `$forgerail-workspace-diagnosis`：优先沿用现有习惯的有界只读诊断；
-- `$workspace-health-review`：可独立触发的工作区治理健康能力包。
-- `$architecture-convergence-audit`：可独立触发、中风险、Analyze First 的只读能力 owner 与最小边界审计。
+## 为什么需要 ForgeRail？
 
-Architecture Convergence 是 alpha.1 之后的私有 source candidate。安装只令其
-`available`，不会自动启用；它不要求先运行 ForgeRail Core，也不会创建 Profile、
-task ledger、Receipt、`.forgerail/` 状态或外部 issue。
+Coding Agent 很擅长执行任务，真正困难的是让执行始终忠于真实项目：
 
-GitHub Rulesets、Release Safety 与 Thread Closure 由于具有独立身份、权限、风险与生命周期边界，作为单独分发、按需安装和显式触发的 Capability Packs。主插件被安装不代表这些能力包已安装、启用、认证或获批执行。
+- 这个变更究竟属于哪个仓库、哪个任务？
+- 项目已有的 instructions、规格、决策和 CI 规则有哪些？
+- Agent 可以读取或修改什么，哪些事情仍需人类决定？
+- 哪些证据足以证明结果，下一个 Agent 应该从哪里恢复？
 
-Cross-Workspace Orchestration 同样单独分发并显式使用。它只适用于主控任务协调多个真实独立 owner/repository/release 边界，且依赖关系允许安全并行的场景；它不是单仓通用的多 Agent 开关。
+ForgeRail 帮助 Agent 在扩大范围前回答这些问题。它观察工作区，优先沿用项目已有习惯，只在有证据时建议最小治理层级，并核验可观察结果。**Agent 负责做事，ForgeRail 负责引航，人类负责判断。**
 
-ForgeRail 默认动态计算有效 Workspace Profile，不会因为被调用就创建 `.forgerail/profile.yaml`、修改 `AGENTS.md` 或安装 OpenSpec。
+ForgeRail 不是自动执行器，不替代 OpenSpec 或 `AGENTS.md`，不提供安全保证，也不会要求简单项目为了治理而增加不必要流程。
 
-Control System 迁移现已加入版本化 Workspace/Profile、Task Control、Review Authority、Validation Topology、Execution Context、Adapter Observation 与 Cross-Workspace Pack composition 合同，同时保留 alpha v1 合同。详情见 [Control Profile 合同](docs/control-profile-contracts.zh-CN.md)、[Control Task 合同](docs/control-task-contracts.zh-CN.md)、[Control Authority 与 Validation 合同](docs/control-authority-validation-contracts.zh-CN.md)、[Cross-Workspace Pack Composition 合同](docs/cross-workspace-pack-composition-contract.zh-CN.md)与 pre-evaluator [Control System Fixture Matrix](docs/control-system-fixture-matrix.zh-CN.md)。
+## 五分钟快速开始
 
-工作区采用遵循渐进式三级模型：默认 Plugin Only；只有用户确认后才使用轻量绑定；未来只有机器配置或反复冲突等证据充分时，才考虑持久化 `.forgerail/` 治理。宿主 instruction 文件只是 Adapter，不是 ForgeRail Core。alpha.1 支持 Codex；Claude Code 与 Cursor profile 会明确发布，但仍标记为未验证。
-
-可选官方 npm 包为 `@echopath-labs/forgerail`，安装后仍提供简短的 `forgerail` 命令入口，用于离线校验、只读诊断和合同闭环；Agent Plugin 本身不依赖该 CLI 才能使用。未作用域 `forgerail` 只保留名称占位，不是正式安装入口。
+### 1. 安装精确版本的 Codex Plugin
 
 ```bash
-npm install --global @echopath-labs/forgerail@0.1.0-alpha.2
-forgerail validate
+codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.4
+codex plugin add forgerail@echopath-labs
+```
+
+然后在目标项目中启动一个**新的 Codex 任务**。Plugin Only 不要求目标项目安装 Node.js，也不要求存在 `package.json`、`node_modules` 或 `.forgerail/`。
+
+### 2. 先只读试用
+
+把下面这段话发给 Codex：
+
+```text
+使用 $forgerail 对当前项目进行只读评估。优先沿用已有的 AGENTS.md、规格、
+ADR、CI 和文档习惯。不要修改文件，也不要执行远端操作。建议使用 Plugin Only
+还是 Lightweight Adoption，展示依据和不确定项，并在任何写入前等待我确认。
 ```
 
-## 安装预发布版
+### 3. 判断结果
+
+ForgeRail 应该返回：
+
+- 它能够验证的工作区与任务边界；
+- 当前适用的治理来源和仍未解决的冲突；
+- 最小的建议采用层级；
+- 验证依据以及明确没有执行的动作；
+- 最多一个当前需要人类确认的下一项决定。
+
+如果它直接写入文件、创建 `.forgerail/`、执行远端动作，或把“已经安装”误当成“已经批准”，请提交 bug。
+
+## 包含哪些能力？
+
+| Skill | 适用场景 | 默认效果 |
+| --- | --- | --- |
+| `$forgerail` | 启动或治理一个非简单工程任务 | 给出任务、范围、审批和验证边界 |
+| `$forgerail-workspace-diagnosis` | 需要快速理解当前工作区 | 优先沿用已有习惯的有界只读诊断 |
+| `$workspace-health-review` | 复核恢复、所有权和治理债务 | 独立的只读工作区健康复核 |
+| `$architecture-convergence-audit` | 怀疑能力重复或存在多个 owner | 独立的只读 owner 与最小边界审计 |
+
+如果其他已安装 Plugin 定义了同名短 Skill，请使用 Codex 显示的完整 namespaced Skill 名称。
+
+### 可选 Capability Pack Plugins
+
+以下能力具有不同的认证、风险和生命周期边界，因此独立分发：
+
+- `forgerail-github-rulesets`
+- `forgerail-release-safety`
+- `forgerail-thread-closure`
+- `forgerail-cross-workspace-orchestration`
+
+安装 ForgeRail 主 Plugin 不会自动安装、启用、认证、调用或批准它们。详情见[外部 Capability Packs](docs/external-capability-packs.md)。
+
+## 渐进式采用
+
+ForgeRail 将“能力可用”和“项目采用”分开：
 
-未来面向人的默认入口是 Universal Plugins Directory 界面，但 ForgeRail 当前尚未在该目录上线。在独立提交、审查与发布完成前，请安装已经发布的精确 ForgeRail Marketplace 快照：
+| 层级 | 会修改项目什么？ | 适用场景 |
+| --- | --- | --- |
+| Plugin Only | 什么都不修改 | 默认方式；偶尔使用引导或诊断 |
+| Lightweight Adoption | 一个经过评审的 managed instruction block，或 `FORGERAIL.md` 绑定 | 反复使用且长期指导确有价值 |
+| Persisted Governance | 当前 alpha 延期 | 只有机器配置具有明确 owner、迁移和删除规则后才考虑 |
+
+ForgeRail 不会自行应用 Lightweight Adoption。Agent 必须展示精确路径与内容、取得确认、保护无关内容、在新任务中验证结果并返回 Receipt。详情见[渐进式采用](docs/adoption.zh-CN.md)。
+
+## 工作方式
+
+ForgeRail 组合四层能力，但不会要求每个项目都持久化这些层：
+
+1. **Core governance**：可移植的范围、权限、证据、验证和收口规则；
+2. **Capability Packs**：只有相关时才选择的独立领域能力；
+3. **Effective Workspace Profile**：默认从项目已有来源动态计算；
+4. **Temporary Task Envelope**：当前任务的边界、允许范围、审批、检查和回传契约。
+
+宿主 instructions 文件只是 Adapter，不是 ForgeRail Core。OpenSpec、ADR、项目文档、CI 和代码继续拥有各自事实。深入说明见 [Control Profile 合同](docs/control-profile-contracts.zh-CN.md)、[Task 合同](docs/control-task-contracts.zh-CN.md)和[权限与验证合同](docs/control-authority-validation-contracts.zh-CN.md)。
+
+## 可选 CLI
+
+npm 包为维护者和 CI 提供确定性校验与诊断，**不是** Agent Plugin 或目标项目的必需条件。
 
 ```bash
-codex plugin marketplace add echopath-labs/forgerail --ref v0.1.0-alpha.2
-codex plugin add forgerail@echopath-labs
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 validate
+npx --yes @echopath-labs/forgerail@0.1.0-alpha.4 diagnose --workspace .
 ```
 
-安装后请启动一个新的 Codex 任务。GitHub Rulesets、Release Safety 与 Thread Closure 必须按项目实际需要单独安装；精确命令、三级采用模型、Host Adapter 状态、升级、回滚和卸载边界见[安装与采用](docs/installation.zh-CN.md)及[渐进式采用](docs/adoption.zh-CN.md)。
+正式包是带组织 scope 的 `@echopath-labs/forgerail`。不带 scope 的 `forgerail` 只是名称占位，不是安装来源。
+
+## 文档
+
+- [安装、验证、升级与排错](docs/installation.zh-CN.md)
+- [渐进式项目采用](docs/adoption.zh-CN.md)
+- [Capability Pack 边界](docs/external-capability-packs.md)
+- [Pack 开发](docs/pack-authoring.md)
+- [从 Agent Workflow Governance 迁移](docs/migration-from-agw.md)
+- [架构验收](docs/architecture-acceptance.md)
+- [alpha.4 发布说明与 Runbook](docs/release-alpha4.zh-CN.md)
+
+## 项目状态
+
+ForgeRail 已经可以通过 Plugin Only 和经过评审的 Lightweight Adoption 用于真实 Codex 项目，但仍是 alpha：
+
+- Codex 已验证；Claude Code 和 Cursor 仍是 `profile-only`，不是已验证集成；
+- 持久化 `.forgerail/` 治理仍延期；
+- 外部 Capability Packs 继续独立安装、显式调用；
+- Universal Plugins Directory 上架暂停，当前支持精确 tag Marketplace 安装；
+- 缺陷通过新版本 forward fix，不改写已发布 tag 或 package。
+
+参见 [alpha.4 prerelease](https://github.com/echopath-labs/forgerail/releases/tag/v0.1.0-alpha.4)和[变更记录](CHANGELOG.md)。
+
+## 贡献与支持
+
+提交 PR 前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。可复现 bug、产品建议和文档问题使用仓库 Issue 表单；使用问题和排错从 [SUPPORT.md](SUPPORT.md) 开始。
+
+安全漏洞请按 [SECURITY.md](SECURITY.md) 私下报告。不要在 Issue 中提交凭据、私有项目记忆、生产配置、客户数据或未脱敏 Receipt。
+
+社区参与遵守 [Code of Conduct](CODE_OF_CONDUCT.md)。
 
-Agent Plugin 不要求目标项目安装 Node.js 或存在 `package.json`；npm/npx 始终只是可选维护与验证工具。
+## 许可证
 
-不可变 public alpha.2 仍是当前安装来源。Alpha.3 是本地 source-first forward fix：主 Plugin 收敛为三条 starter prompts，同时四个 Skills 继续独立发现与调用。拟议版本/tag 不授权应用公开投影、远端集成、发布或 Directory submit/publish。
+ForgeRail 使用 [Apache License 2.0](LICENSE)，署名信息见 [NOTICE](NOTICE)。

package/SECURITY.md

@@ -1,7 +1,51 @@
-# Security
+# Security Policy
 
-Report suspected ForgeRail vulnerabilities privately to the EchoPath Labs maintainers before public disclosure.
+ForgeRail guides Agents around project context, scope, authority, evidence, and validation. It does not provide a security guarantee, replace code review, or authorize external effects.
 
-ForgeRail workspace diagnosis is read-only by default and must not inspect secrets, credentials, broad private archives, or unrelated child repositories. Capability Packs that access remote systems must declare identity, permissions, approval, validation, and rollback boundaries.
+## Supported versions
 
-Do not include credentials, private project memory, production configuration, or customer data in issues, fixtures, receipts, or public bundles.
+| Version | Security support |
+| --- | --- |
+| `0.1.0-alpha.4` | Current public prerelease; fixes move forward |
+| Earlier alpha releases | Upgrade to the current prerelease before reporting unless the issue is version-specific |
+
+Published npm versions and Git tags are immutable. Security fixes are released as a new version; maintainers do not overwrite packages or move published tags.
+
+## Report a vulnerability privately
+
+Use GitHub's private vulnerability reporting surface:
+
+https://github.com/echopath-labs/forgerail/security/advisories/new
+
+Include only what is needed to reproduce and assess the issue:
+
+- affected version, host, and Skill or Capability Pack;
+- expected versus observed behavior;
+- minimal reproduction with secrets and private data removed;
+- security impact and preconditions;
+- whether the issue has been disclosed elsewhere.
+
+If private vulnerability reporting is unavailable, open a minimal public issue asking the maintainers to establish a private channel. Do **not** include exploit details, credentials, tokens, customer data, private repository content, production configuration, or unredacted receipts in that issue.
+
+## Scope
+
+Security reports may include:
+
+- unintended writes or remote effects during documented read-only use;
+- scope escape, path traversal, unsafe projection, or inclusion of denied/private files;
+- credential exposure or cross-identity confusion;
+- approval, authority, validation, or rollback boundaries that fail open;
+- malicious or unsafe Plugin/Skill/Pack packaging behavior;
+- dependency or release-integrity problems in the official scoped package.
+
+General product limitations, governance disagreements, support questions, and findings that require an already-compromised host without increasing impact may be routed to normal issues.
+
+## Security boundaries for users
+
+- Workspace diagnosis is read-only by default and should not inspect secrets, broad private archives, or unrelated repositories.
+- Installation never grants login, repository administration, publishing, deployment, or lifecycle authority.
+- Capability Packs with remote access must declare identity, permissions, approval, validation, rollback, and cleanup boundaries.
+- Use exact tags and the scoped `@echopath-labs/forgerail` package; the unscoped package is only a reservation.
+- Review Agent output and project diffs. ForgeRail guidance is not a substitute for least privilege, secure configuration, CI, or human review.
+
+Maintainers will acknowledge a usable private report when possible, coordinate validation and remediation, and credit reporters who want attribution. Timelines depend on severity, reproducibility, and release risk; no service-level agreement is promised.