frontend-project-context 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
-## 1.0.0 — release candidate
+## 1.2.0 — unreleased
+
+- 新增未初始化和已初始化项目均可使用的只读 `capabilities`，公开 package、exchange protocol、schema、command、八类 action 和永久边界。
+- 新增 Action Plan schema 1 和只读 `preflight`，把 AI 建议规范化为带三个 snapshot、action 专属 baseline、精确 impact 与 blocker 的短生命周期输入。
+- 新增 Review Bundle schema 1，稳定分组 current/proposed、item/source/path/projection 影响与结构化 `{ command, args }` invocation；invocation 不含 `--write` 或 `--by`。
+- 发布 capabilities、Assist Bundle、Action Plan 与 Review Bundle 四份 JSON schema，并把 `schemas/` 加入 npm 白名单；动态项目状态继续排除。
+- 八类 action 均复用现有 register/propose/review/accept/revise/deprecate/approve/publish 预检语义；不新增 `apply-plan`、Provider、Agent Runtime、Git、网络、依赖安装、自动批准或业务代码执行。
+- A-56 至 A-63 与全部回归共 69/69 项本地验收通过；公共发布尚未授权。
+
+## 1.1.0 — unreleased
+
+- 新增 `setup`，在未初始化或已初始化项目中复用现有 discovery，输出不含自动批准的 Assist Bundle；显式写入只创建三个 store 和 create-only proposal。
+- 新增永远只读的 `sync`，一次聚合来源漂移、精确 item 影响、调用方 changed path、投影路径、finding、read target 和稳定 work unit。
+- Assist Bundle schema 1 默认不含来源正文和无关合同值；超过 100 个受影响 item 时保留全部 ID 与基本元数据、省略完整值并显式标记，不静默截断。
+- 补齐 pending-review、projection-review、setup proposal artifact receipt 和目录型 file source 的后代 changed-path 映射。
+- 保持人类为唯一批准者，不增加 Provider、Agent Runtime、网络、Git、依赖、后台服务、自动接受或自动发布能力。
+- A-01 至 A-55、B0-01/B0-02、CLI 和发布工件共 61 项本地验收通过；公共发布尚未授权。
+
+## 1.0.1 — release candidate
+
+- 把 npm README 重写为面向使用者的中英双语安装、快速上手、工作流和命令入口。
+- 修正 `bin` 路径规范化警告，补充真实 npm 主页和检索关键词。
+- 从发布白名单移除仓库动态状态文件，避免包内固化发布前状态。
+- 未修改产品运行逻辑、Contract、CLI 命令或兼容面。
+
+## 1.0.0 — 2026-09-08
 
 - 冻结 model-neutral Project Contract、来源追溯、scope compiler、Context Bundle 和受管投影边界。
 - 提供通用来源登记、四类 item、三类 scope、显式批准和知识维护闭环。
@@ -11,4 +36,4 @@
 - 以 `Copyright 2026 Fushan` 采用 Apache License 2.0，并把 LICENSE/NOTICE 纳入发布包。
 - A-01 至 A-45、B0-01/B0-02 与 CLI 共 49 项本地验收通过。
 
-公开 npm 发布已获授权并固定为 public access；npmjs.org CLI 身份已验证，当前进入最终发布。
+已由 `fushanyx1` 发布到官方公共 npm；远端 `v1.0.0` 标签对应发布提交，registry tarball 完整性已独立核验。

package/README.md

@@ -1,148 +1,413 @@
 # Frontend Project Context
 
-Frontend Project Context 是位于前端项目与 AI 编程工具之间的模型无关上下文层。
+Keep AI coding guidance consistent with one human-approved, source-traceable project contract.
 
-[产品宪法](./docs/00-PRODUCT-CONSTITUTION.md)是产品身份、边界、完成条件和变更规则的唯一规范真源。
+用一份经过人工批准、来源可追溯的项目合同，让不同 AI 编程工具获得一致且不过期的项目上下文。
 
-它把分散在设计资料、文档、配置、代码和团队约定中的项目知识，整理成一份有来源、有人负责批准的 `Project Contract`，再为不同 Coding Agent 生成一致的项目上下文，并检查规则漂移。
+[English](#english) · [中文](#中文)
 
-```text
-项目事实与人工规范
-→ Project Contract（唯一真源）
-→ Context Compiler
-→ AGENTS.md / Ruler / Kiro / 其他 Agent
-→ Drift Check
+## English
+
+### Why use it?
+
+AI coding tools often read only part of a repository. Important conventions may be scattered across documentation, configuration, source code, and team decisions. Frontend Project Context turns those explicit sources into a project-local `Project Contract`, then:
+
+- selects the approved guidance that applies to a file or directory;
+- renders focused context for existing coding agents;
+- exposes versioned machine capabilities and schemas for model-neutral hosts;
+- converts AI suggestions into authority-free Action Plans and read-only Review Bundles;
+- publishes managed Markdown, AGENTS, or Ruler-compatible projections;
+- reports source, contract, and projection drift;
+- keeps every persistent write and approval under explicit human control.
+
+It does **not** call an AI provider, edit business code, manage Git, install dependencies automatically, or approve rules on its own.
+
+### Requirements
+
+- Node.js 18 or newer
+- A project whose context should live in the repository
+
+### Install
+
+Pin it as a development dependency so local users and CI run the same version:
+
+```bash
+npm install --save-dev frontend-project-context@1.2.0
+```
+
+The package has zero runtime dependencies.
+
+`1.2.0` is the locally verified source version in this repository. The latest independently verified public npm version remains `1.0.1` until separate release authorization and publication.
+
+### Quick start
+
+Let an existing Coding Agent prepare deterministic onboarding candidates:
+
+```bash
+npx project-context setup \
+  --project . \
+  --id my-project \
+  --name "My Project" \
+  --write \
+  --json
+```
+
+`setup` creates only the three stores and a create-only proposal. It does not approve candidates or publish Agent files. Its JSON `artifacts` receipt reports the exact proposal path and whether it was previewed, created, or already unchanged. Read `summary`, `workUnits`, and `readTargets`, then review the exact proposed IDs.
+
+Register an explicit source:
+
+```bash
+npx project-context register \
+  --project . \
+  --id source.package \
+  --kind file \
+  --path package.json \
+  --write
+```
+
+Propose a scoped contract item. This creates a reviewable proposal; it does not approve it:
+
+```bash
+npx project-context propose \
+  --project . \
+  --id policy.ui-copy \
+  --kind policy \
+  --subject ui.visible-copy \
+  --value required \
+  --statement "Use the approved visible-copy convention." \
+  --sources source.package \
+  --scope path-prefix \
+  --scope-path src \
+  --output .project-context/policy.ui-copy.proposal.json \
+  --write
+```
+
+Approve only the item you reviewed:
+
+```bash
+npx project-context approve \
+  --project . \
+  --proposal .project-context/policy.ui-copy.proposal.json \
+  --ids policy.ui-copy \
+  --by YOUR_NAME \
+  --write
+```
+
+Compile context for a target and check for drift:
+
+```bash
+npx project-context context --project . --path src --locale en
+npx project-context check --project .
+```
+
+After project sources or implementation paths change, create one read-only reconciliation work unit:
+
+```bash
+npx project-context sync \
+  --project . \
+  --changed-path src/example.ts \
+  --json
+```
+
+`sync` reports changed sources, affected item IDs, pending-item review, path-scoped guidance, projection-only findings, and exact work units. It contains no source bodies and cannot accept, revise, approve, deprecate, or publish anything. A Coding Agent may prepare the existing safe commands, but a human must approve the displayed IDs and paths before writes occur.
+
+Discover the exchange contract without initializing the project:
+
+```bash
+npx project-context capabilities --project . --json
 ```
 
-## 产品核心
+An external AI host can create an Action Plan schema 1 using the returned project snapshots and one of the eight advertised action kinds. Save that short-lived plan inside the project, then produce a read-only Review Bundle:
 
-- **Register / Discover**：登记项目明确提供的来源；自动发现只负责保守地提出接入候选，不尝试理解所有前端技术。
-- **Govern**：人类确认哪些内容是事实、规范或参考样例；AI 不能自行批准长期规则。
-- **Compile**：按目录范围和任务目标生成最小、可追溯的 Context Bundle。
-- **Project**：把同一合同投影到现有 AI 工具，而不是为每个模型维护一套手写规则。
-- **Check**：发现来源变化、合同冲突和生成文件漂移。
+```bash
+npx project-context preflight \
+  --project . \
+  --plan .project-context/action-plan.json \
+  --json
+```
 
-## 与现成工具的关系
+`preflight` validates the project ID, all three snapshot digests, action-specific baselines, exact impacts, blockers, and projection ownership. It returns structured `{ command, args }` invocations without `--write` or `--by`. The plan and Review Bundle grant no authority: after a human approves exact action IDs and paths, the host must add the required identity and write flags to the existing fine-grained command. Any intervening write invalidates the remaining review and requires a fresh `sync` and `preflight`.
 
-- [Ruler](https://github.com/intellectronica/ruler) 和 [Rulesync](https://github.com/dyoshikawa/rulesync) 已经覆盖多 Agent 规则分发，本项目不重建完整适配矩阵。
-- [Kiro Steering](https://kiro.dev/docs/steering/) 已经展示项目知识、规则和 Specs 的完整产品体验，本项目保持 Runtime 和模型中立。
-- [GitHub Spec Kit](https://github.com/github/spec-kit) 与 [OpenSpec](https://openspec.dev/) 负责规格驱动的功能开发流程，可以消费本项目上下文，但不属于本项目内核。
+The package publishes `schemas/capabilities.schema.json`, `schemas/assist-bundle.schema.json`, `schemas/action-plan.schema.json`, and `schemas/review-bundle.schema.json`.
 
-本项目只在现有工具前面补一层：**从真实设计和代码中形成有来源、可审查、可按作用域编译的项目合同，并持续检查漂移。**
+Generate the read-only governance dashboard:
 
-## 明确不做
+```bash
+npx project-context dashboard --project . > project-context-dashboard.html
+```
 
-- 不调用模型 Provider，也不实现 Coding Agent Runtime。
-- 不执行真实开发任务或自动修复代码。
-- 不管理 Git 分支、commit、merge、push、PR 或部署。
-- 不自动安装依赖或访问外部系统。
-- 不保存 candidate、DecisionRecord 或 DeliveryRecord。
-- 不复制 Kiro、Spec Kit、Ruler 等工具已有的能力。
+The dashboard is a self-contained offline HTML file. The command writes only to stdout and does not open a browser or change the contract.
 
-## 当前状态
+### What is created?
+
+Initialization creates:
+
+```text
+.project-context/
+├── contract.json
+├── sources.lock.json
+└── projections.lock.json
+```
+
+Commit these three stores. Also commit any managed projection your team intentionally publishes. Proposal files, temporary context output, dashboard HTML, caches, and tarballs should normally remain uncommitted.
+
+### Core workflow
 
 ```text
-1.0.0-public-npm-release-ready
+Explicit project sources
+→ reviewable proposals
+→ human-approved Project Contract
+→ scoped Context Bundle
+→ AGENTS / Markdown / Ruler projections
+→ existing AI tool
+→ authority-free Action Plan
+→ read-only Review Bundle
+→ exact human approval
+→ existing fine-grained write command
+→ drift check
 ```
 
-核心引擎、通用 authoring、knowledge maintenance、只读治理看板和来源生命周期闭环均已完成本地、零第三方依赖实现。`0.9.0` 在不扩大产品边界的前提下加固路径/合同安全，并压缩 Context、CLI JSON、Dashboard 和启动上下文的重复内容。团队维护验收已在隔离 fixture 完整走通来源变化、接受、修订、废弃、重新批准、重新投影和最终检查；加上 A-39 与 A-40 至 A-45，A-01 至 A-45、2 项 B0 回归和 CLI 端到端测试共 49 项均已通过。
+All commands are read-only unless that command explicitly includes `--write`. Source changes invalidate affected approvals; they are never accepted or reapproved automatically.
+
+### Common commands
+
+| Command | Purpose |
+| --- | --- |
+| `setup` | Aggregate safe initialization, conservative discovery, and an Assist Bundle |
+| `capabilities` | Discover protocol versions, schemas, action kinds, initialization, and permanent boundaries |
+| `init` | Create an empty project contract safely |
+| `register` | Register a file, path, JSON pointer, or human decision |
+| `discover` | Conservatively propose bootstrap candidates |
+| `propose` | Author a fact, policy, reference, or validation description |
+| `approve` | Explicitly approve selected proposal IDs |
+| `context` | Compile approved context for one or more paths |
+| `publish` | Write an owned AGENTS, Markdown, or Ruler projection |
+| `check` | Detect stale sources, contracts, and projections |
+| `sync` | Aggregate source drift, item impact, changed paths, and reconciliation work units |
+| `preflight` | Validate an Action Plan and return a read-only grouped Review Bundle |
+| `dashboard` | Render the read-only governance dashboard |
+| `review-source` | Review a changed source and its exact impact set |
+| `accept-source-change` | Accept a pinned source digest and revoke affected approvals |
+| `revise` / `deprecate` | Maintain contract items explicitly |
+| `deprecate-source` | Retire an unreferenced source with an audit record |
+
+Run `npx project-context --help` for the complete command syntax.
+
+### Documentation
+
+- [Product constitution](./docs/00-PRODUCT-CONSTITUTION.md)
+- [Program and CLI design](./docs/04-PROGRAM-DESIGN.md)
+- [Acceptance contract](./docs/05-ACCEPTANCE-CONTRACT.md)
+- [Installation and distribution](./docs/08-INSTALLATION-AND-DISTRIBUTION.md)
+- [Knowledge maintenance](./docs/12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)
+- [Read-only governance dashboard](./docs/13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md)
+- [Source lifecycle](./docs/15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md)
+- [Guided onboarding and AI-assisted reconciliation](./docs/16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md)
+- [AI Exchange Boundary design](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
+- [Upgrade notes](./UPGRADING.md)
+
+## 中文
 
-正式发布准备已经把上述能力冻结为 `frontend-project-context@1.0.0` 候选包，公共稳定面为 `project-context` CLI。后续重大调整审查发现并已关闭一个发布前缺口：已登记来源被删除、搬迁或永久退役时，现在可用稳定 CLI 完成替代、修订、重新批准、旧来源废弃、重新投影和 clean check，无需手改内部 JSON。
+### 它解决什么问题？
 
-[Source Lifecycle Closure 设计与实现记录](./docs/15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md) 已按冻结范围落地 Contract schema 2 的 active/deprecated source、显式 `deprecate-source` 命令和 A-40 至 A-45。schema 1 项目继续原样可读，只有首次成功废弃来源时才延迟升级。公开 npm 发布已经获得授权并固定到 `https://registry.npmjs.org/`，发布者 CLI 身份已验证，当前处于最终发布就态。
+AI 编程工具通常只读取仓库的一部分，而项目约定分散在文档、配置、源码和团队决定中。Frontend Project Context 把这些明确来源治理成项目内的 `Project Contract`，然后：
 
-## 许可证
+- 按文件或目录选择真正生效的已批准规则；
+- 为现有 Coding Agent 生成精简且可追溯的上下文；
+- 向模型无关宿主公开版本化 capability 与机器 schema；
+- 把 AI 建议收敛为无权限 Action Plan 和只读 Review Bundle；
+- 从同一合同生成受管 Markdown、AGENTS 或 Ruler 兼容投影；
+- 检测来源、合同和投影是否过期；
+- 所有持久写入与批准都必须由人显式触发。
 
-本项目采用 [Apache License 2.0](./LICENSE)，版权声明见 [NOTICE](./NOTICE)：`Copyright 2026 Fushan`。
+它**不会**调用大模型、修改业务代码、管理 Git、自动安装依赖，也不会替人批准规则。
 
-本仓库已经使用同一 CLI 初始化 `.project-context/` 自托管真源。收录本次实现后，22 个精确来源和 20 个治理项均经显式批准，`check` 零 finding。根 `AGENTS.md` 继续由人维护，没有被生成投影接管。
+### 环境要求
 
-只读治理看板仍提供总览、知识、来源、scope、投影、finding 六个视图；默认输出确定性、自包含的离线 HTML，`--json` 输出短生命周期 View Model schema 3，并能双语解释 deprecated source 的负责人、时间与理由。HTML 只包含渲染所需内容，不再重复嵌入整份 View Model。
+- Node.js 18 或更高版本
+- 希望把 AI 项目上下文随仓库共同维护的项目
 
-`0.7.0 — Knowledge Maintenance Closure` 已实现来源变化 review/accept、影响集撤销旧批准、同 ID revision、deprecation、pending reapproval、projection stale 和并发失败封闭。两个真实项目 B0 仍只作为既有证据；本次实现没有访问真实项目。
+### 安装
 
-## 本地使用
+建议固定为开发依赖，让本地与 CI 使用同一版本：
 
 ```bash
-node bin/project-context.mjs init --project /path/to/project --id project-id --name "Project Name" --write
-node bin/project-context.mjs register --project /path/to/project --id source-package --kind file --path package.json --write
-node bin/project-context.mjs register --project /path/to/project --id source-src --kind path --path src --write
-node bin/project-context.mjs register --project /path/to/project --id source-team --kind human-decision --reference "decision:team" --write
-node bin/project-context.mjs propose --project /path/to/project --id policy-visible-copy --kind policy --subject ui.visible-copy --value required --statement "Use the approved visible-copy convention." --sources source-team --scope path-prefix --scope-path src --output .project-context/policy-visible-copy.proposal.json --write
-node bin/project-context.mjs approve --project /path/to/project --proposal .project-context/policy-visible-copy.proposal.json --ids policy-visible-copy --by NAME --write
-node bin/project-context.mjs discover --project /path/to/project
-node bin/project-context.mjs context --project /path/to/project --path src --locale zh-CN
-node bin/project-context.mjs publish --project /path/to/project --target agents --output AGENTS.md --write
-node bin/project-context.mjs check --project /path/to/project
-node bin/project-context.mjs dashboard --project /path/to/project > project-context-dashboard.html
-node bin/project-context.mjs dashboard --project /path/to/project --json
+npm install --save-dev frontend-project-context@1.2.0
 ```
 
-知识来源发生变化后的维护流程：
+本包没有运行时第三方依赖。
+
+`1.2.0` 是本仓库当前已经完成本地验收的源码版本。在获得单独发布授权并完成发布前，公共 npm 已独立核验的最新版本仍为 `1.0.1`。
+
+### 快速开始
+
+让现有 Coding Agent 生成确定性的首次接入候选：
 
 ```bash
-node bin/project-context.mjs review-source --project /path/to/project --id source-package --json
-node bin/project-context.mjs accept-source-change --project /path/to/project --id source-package --expected-digest SHA256_FROM_REVIEW --affected-items ITEM_ID... --write
-node bin/project-context.mjs revise --project /path/to/project --id ITEM_ID --kind policy --subject SUBJECT --value NEW_VALUE --statement "NEW STATEMENT" --sources source-package --scope project --json
-node bin/project-context.mjs revise --project /path/to/project --id ITEM_ID --expected-item-digest SHA256_FROM_PREVIEW --kind policy --subject SUBJECT --value NEW_VALUE --statement "NEW STATEMENT" --sources source-package --scope project --write
-node bin/project-context.mjs approve --project /path/to/project --pending --ids ITEM_ID... --by NAME --write
-node bin/project-context.mjs publish --project /path/to/project --target agents --output AGENTS.md --write
-node bin/project-context.mjs check --project /path/to/project
+npx project-context setup \
+  --project . \
+  --id my-project \
+  --name "My Project" \
+  --write \
+  --json
 ```
 
-来源已经搬迁或永久退役时，先登记替代 source、用 `revise` 和 `approve --pending` 移走全部当前引用，再执行：
+`setup` 只创建三个 store 和一份 create-only proposal，不会批准候选或发布 Agent 文件。JSON 中的 `artifacts` receipt 会返回精确 proposal 路径，以及 preview、create 或 unchanged 结果。先读取 `summary`、`workUnits` 和 `readTargets`，再审查具体 proposal ID。
+
+登记一个明确来源：
 
 ```bash
-node bin/project-context.mjs deprecate-source --project /path/to/project --id source-old --by NAME --rationale "Replaced by source-new." --json
-node bin/project-context.mjs deprecate-source --project /path/to/project --id source-old --expected-source-digest SHA256_FROM_PREVIEW --by NAME --rationale "Replaced by source-new." --write
-node bin/project-context.mjs publish --project /path/to/project --target agents --output AGENTS.md --write
-node bin/project-context.mjs check --project /path/to/project
+npx project-context register \
+  --project . \
+  --id source.package \
+  --kind file \
+  --path package.json \
+  --write
 ```
 
-preview 中若 `blockingItems` 非空，必须先处理这些 proposed/approved 引用；命令不会级联改 item 或自动批准。需要退役 item 时，先运行 `deprecate` preview 取得 current item digest，再以同一命令增加 `--expected-item-digest ... --by NAME --rationale TEXT --write`。所有命令默认只读；`init`、`register`、保存 proposal、`accept-source-change`、`revise`、`deprecate`、`deprecate-source`、`approve` 和 `publish` 只有在自身显式包含 `--write` 时才会写文件。
+提出一条带作用域的合同项。这里只生成待审 proposal，不会自动批准：
 
-`context` 默认从 `[zh-CN] ...\n[en] ...` statement 中只选择中文主解释；可用 `--locale en` 选择英文，或 `--locale all` 保留双语原文。多条 `--path` 若得到相同知识集，只渲染一个 Targets 分组。`approve --json` 默认返回 digest 和 ID 摘要；只有确实需要完整 next Contract 时才使用 `--full-json`。
+```bash
+npx project-context propose \
+  --project . \
+  --id policy.ui-copy \
+  --kind policy \
+  --subject ui.visible-copy \
+  --value required \
+  --statement "使用团队已经批准的界面文案约定。" \
+  --sources source.package \
+  --scope path-prefix \
+  --scope-path src \
+  --output .project-context/policy.ui-copy.proposal.json \
+  --write
+```
 
-验证：
+人工审查后，只批准明确选中的 item：
 
 ```bash
-npm test
-npm run check
+npx project-context approve \
+  --project . \
+  --proposal .project-context/policy.ui-copy.proposal.json \
+  --ids policy.ui-copy \
+  --by YOUR_NAME \
+  --write
 ```
 
-发布候选与升级资料：
+为目标目录生成上下文，并检查漂移：
 
-- [正式发布准备](./docs/14-FORMAL-RELEASE-READINESS.md)
-- [变更记录](./CHANGELOG.md)
-- [升级说明](./UPGRADING.md)
-- [最小团队接入示例](./examples/README.md)
+```bash
+npx project-context context --project . --path src --locale zh-CN
+npx project-context check --project .
+```
 
-检查或读取本仓库自身治理上下文：
+项目来源或实现路径变化后，可一次生成只读的增量维护工作单元：
 
 ```bash
-node bin/project-context.mjs check --project .
-node bin/project-context.mjs context --project . --path . --path src/project-context --path docs --locale zh-CN
-node bin/project-context.mjs dashboard --project . > /tmp/frontend-project-context-dashboard.html
+npx project-context sync \
+  --project . \
+  --changed-path src/example.ts \
+  --json
 ```
 
-现行文档按以下顺序阅读：
+`sync` 汇总变化来源、受影响 item ID、pending item 审查、路径适用规则、仅投影 finding 和精确 work unit。它不携带来源正文，也不能接受、修订、批准、废弃或发布任何内容。Coding Agent 可以准备既有安全命令，但只有人在看到明确 ID 和路径后才能授权写入。
 
-1. [产品宪法](./docs/00-PRODUCT-CONSTITUTION.md)
-2. [当前状态](./PROJECT_STATE.json)
-3. [产品核心](./docs/01-PRODUCT-CORE.md)
-4. [市场与自研边界](./docs/02-MARKET-BOUNDARY.md)
-5. [最终产品方案](./docs/03-FINAL-SOLUTION.md)
-6. [v1 程序设计](./docs/04-PROGRAM-DESIGN.md)
-7. [验收合同](./docs/05-ACCEPTANCE-CONTRACT.md)
-8. [v1 authoring closure 设计与实现结果](./docs/11-V1-AUTHORING-CLOSURE-DESIGN.md)
-9. [0.7.0 Knowledge Maintenance Closure 冻结设计与实现记录](./docs/12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)
-10. [0.8.0 Read-only Governance Dashboard 冻结设计与实现记录](./docs/13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md)
-11. [1.0.0 正式发布准备](./docs/14-FORMAL-RELEASE-READINESS.md)
-12. [1.0.0 Source Lifecycle Closure 设计与实现记录](./docs/15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md)
+无需初始化项目即可查询双向交换协议：
+
+```bash
+npx project-context capabilities --project . --json
+```
+
+外部 AI 宿主可使用返回的三个项目 snapshot 和八类 action 生成 Action Plan schema 1。把这份短生命周期计划保存在项目内，再生成只读 Review Bundle：
+
+```bash
+npx project-context preflight \
+  --project . \
+  --plan .project-context/action-plan.json \
+  --json
+```
+
+`preflight` 会验证 project ID、三个 snapshot digest、action 专属 baseline、精确影响集、blocker 和投影所有权，并返回不含 `--write`、`--by` 的结构化 `{ command, args }` invocation。Action Plan 和 Review Bundle 都不授予权限；只有人批准明确 action ID 与路径后，宿主才能为既有细粒度命令补入身份和写入参数。期间任何写入都会使余下 review 失效，必须重新 `sync` 和 `preflight`。
+
+npm 包公开 `schemas/capabilities.schema.json`、`schemas/assist-bundle.schema.json`、`schemas/action-plan.schema.json` 和 `schemas/review-bundle.schema.json`。
+
+生成只读治理看板：
+
+```bash
+npx project-context dashboard --project . > project-context-dashboard.html
+```
+
+看板是一个可离线打开的自包含 HTML。命令只输出到 stdout，不会自动打开浏览器，也不会修改合同。
+
+### 会生成什么？
+
+初始化只创建：
+
+```text
+.project-context/
+├── contract.json
+├── sources.lock.json
+└── projections.lock.json
+```
+
+这三个 store 应提交到仓库；团队明确生成的受管投影也应提交。proposal、临时上下文、看板 HTML、缓存和 tarball 通常不提交。
+
+### 核心流程
+
+```text
+项目明确提供的来源
+→ 可审查 proposal
+→ 人工批准的 Project Contract
+→ 按作用域编译的 Context Bundle
+→ AGENTS / Markdown / Ruler 投影
+→ 现有 AI 工具
+→ 无权限 Action Plan
+→ 只读 Review Bundle
+→ 人对明确 action 的批准
+→ 既有细粒度写命令
+→ 漂移检查
+```
+
+所有命令默认只读，只有当前命令显式包含 `--write` 才会持久写入。来源变化后，受影响的批准会失效，但工具不会自动接受变化或重新批准。
+
+### 常用命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `setup` | 聚合安全初始化、保守 discovery 和 Assist Bundle |
+| `capabilities` | 查询协议版本、schema、action kind、初始化状态和永久边界 |
+| `init` | 安全创建空项目合同 |
+| `register` | 登记文件、路径、JSON Pointer 或人工决定 |
+| `discover` | 保守提出首次接入候选 |
+| `propose` | 创建 fact、policy、reference 或 validation-description |
+| `approve` | 显式批准选中的 proposal ID |
+| `context` | 为一个或多个路径编译已批准上下文 |
+| `publish` | 写入仍归工具所有的 AGENTS、Markdown 或 Ruler 投影 |
+| `check` | 检测来源、合同和投影漂移 |
+| `sync` | 聚合来源漂移、item 影响、变化路径和维护工作单元 |
+| `preflight` | 验证 Action Plan 并返回只读分组 Review Bundle |
+| `dashboard` | 生成只读治理看板 |
+| `review-source` | 查看来源变化及精确影响集 |
+| `accept-source-change` | 接受固定摘要并撤销受影响批准 |
+| `revise` / `deprecate` | 显式维护合同项 |
+| `deprecate-source` | 用审计记录退役已无引用的来源 |
+
+运行 `npx project-context --help` 查看完整命令语法。
+
+### 深入文档
+
+- [产品宪法](./docs/00-PRODUCT-CONSTITUTION.md)
+- [程序与 CLI 设计](./docs/04-PROGRAM-DESIGN.md)
+- [验收合同](./docs/05-ACCEPTANCE-CONTRACT.md)
+- [安装与分发](./docs/08-INSTALLATION-AND-DISTRIBUTION.md)
+- [知识维护闭环](./docs/12-KNOWLEDGE-MAINTENANCE-CLOSURE-ROADMAP.md)
+- [只读治理看板](./docs/13-READ-ONLY-GOVERNANCE-DASHBOARD-DESIGN.md)
+- [来源生命周期](./docs/15-SOURCE-LIFECYCLE-CLOSURE-DESIGN.md)
+- [引导式接入与 AI 辅助维护](./docs/16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md)
+- [AI 双向交换边界设计](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
+- [升级说明](./UPGRADING.md)
 
-历史任务执行 Harness 的结论和第一次真实业务任务只作为反例与证据保留：
+## License / 许可证
 
-- [历史原型](./docs/06-HISTORICAL-PROTOTYPE.md)
-- [真实任务证据](./docs/07-REAL-TASK-EVIDENCE.md)
+Apache License 2.0 · `Copyright 2026 Fushan`
 
-当前实现不调用 Provider、网络、shell 或 Git，不执行项目验证，也不修改业务代码。历史 Harness 的源码、入口、测试和任务模板已从工作树清理，可通过 Git 历史追溯。真实项目报告只作为既有能力证据，不能自动产生新的内核需求。
+See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/UPGRADING.md

@@ -1,4 +1,38 @@
-# 升级到 1.0.0
+# 升级说明
+
+## `1.1.0 → 1.2.0`
+
+`1.2.0` 完成模型无关双向 AI Exchange Boundary：新增只读 `capabilities`、Action Plan schema 1、只读 `preflight`、Review Bundle schema 1 和四份公开机器 schema。Contract、proposal、source lock、projection lock、renderer 与 Dashboard View Model 均未升级，旧项目无需迁移 `.project-context/`。
+
+升级后建议：
+
+1. 运行 `project-context capabilities --project . --json`，由宿主读取版本、schema、action kind、初始化状态和永久边界。
+2. 继续使用 `setup`/`sync` 获取项目到 AI 的 Assist Bundle；外部 AI 只生成符合 `schemas/action-plan.schema.json` 的无权限计划。
+3. 运行 `project-context preflight --project . --plan FILE --json`，集中审查 current/proposed、baseline、影响集、blocker、分组与 structured invocation。
+4. 人明确批准具体 action ID 与路径后，宿主才可给 Review Bundle 中的既有细粒度命令补入所需 `--by` 和 `--write`。
+5. 任一写入后，未执行的旧 Review Bundle 与 invocation 全部作废；重新运行 `sync` 和 `preflight`。
+
+Action Plan 和 Review Bundle 都不是 store、Contract 或 approval receipt。升级不会执行 plan、自动批准、自动修复、修改业务代码、读取 Git、访问网络、调用 Provider 或安装依赖。
+
+## `1.0.1 → 1.1.0`
+
+`1.1.0` 新增 `setup`、只读 `sync` 和短生命周期 Assist Bundle schema 1，它们是双向 AI Exchange Boundary 的首个模型无关内核基础；Codex、Claude、MCP 或其他宿主触发仍属可选适配器。Contract reader 仍兼容 schema 1/2，proposal、source lock、projection lock、renderer 3 和 Dashboard View Model 3 均未变化，因此无需迁移 `.project-context/`。
+
+升级后可以继续使用所有原命令，也可以逐步采用：
+
+1. 新项目通过 `project-context setup --project . --id ID --name NAME --json` 先预览；只有明确需要创建三个 store 和 proposal 时才加 `--write`。
+2. 已初始化项目运行 `project-context sync --project . --json`，一次查看全部来源漂移、影响 item、pending review 和仅投影 finding。
+3. 外部 Agent 或 CI 可以把变化路径通过重复的 `--changed-path` 传入；产品本身不读取 Git。
+4. AI 只根据 `readTargets` 和 `workUnits` 渐进读取，准备既有 accept/revise/deprecate/approve/publish 命令。
+5. 人工明确批准具体 ID 和路径后才能执行相应写命令，最后运行 `check`。
+
+升级不会自动创建 proposal、批准规则、接受来源 digest、重发投影、访问网络、运行 Provider、安装依赖或修改业务代码。
+
+## `1.0.0 → 1.0.1`
+
+`1.0.1` 只修复 npm README、元数据和包文件白名单，不修改 CLI、Contract、lock、projection 或 Dashboard schema。更新依赖版本后无需迁移 `.project-context/`。
+
+## `0.9.0 → 1.0.0`
 
 从本地 `0.9.0` 升级到 `1.0.0` 不需要预先迁移 Project Contract、proposal、source lock 或 projection lock。Contract reader 同时接受 schema 1/2；既有 schema 1 项目保持原字节，只有首次成功执行 `deprecate-source --write` 时才把所有来源显式标为 active、目标标为 deprecated 并写成 schema 2。proposal、source lock 和 projection lock 继续使用 schema 1。Dashboard JSON 使用 schema 3，projection renderer 使用 3。