frontend-project-context 1.3.1 → 1.7.0

package/CHANGELOG.md

@@ -1,13 +1,62 @@
 # Changelog
 
-## 1.3.1 — unreleased
+## 1.7.0 - Unreleased
+
+- Generate human-readable AI Entry and discovery statements in Chinese while preserving English machine IDs, subjects, commands, markers, JSON fields, and enums; AI Entry renderer 3 also fixes the cross-platform offline project-local CLI invocation, while existing renderer 1/2 regions require an explicit owned republish instead of being silently rewritten.
+- Pin README, examples, and release acceptance to `frontend-project-context@1.7.0`; install the exact development dependency before persistent setup, fail closed when the local CLI is absent, and document fresh reinitialization without losing human-authored rules.
+- Complete the reviewed docs/26 local repair: Context Query, Adaptive Context Bundle, Routing Index, Truth Reconciliation Input, and Truth Reconciliation Review Bundle are schema 2; selector, capabilities, and Exchange Protocol are version 2/7/7.
+- Bind adaptive delivery to effective scope, task lineage, audited delivery items, monotonic expansion, and separate audit/delivery/read-target budgets; withhold all model content whenever task delivery is not ready.
+- Add a task-only renderer that deduplicates shared items and omits source locators while leaving persistent renderer 3 and managed projection bytes unchanged.
+- Add previous-Review-bound truth resolution contracts, structured human/external-fix paths, stable finding digests, and recomputed open/deferred/resolved/rejected outcomes without adding write authority.
+- Pass A-130D-01 through A-130D-31, A-130T-01 through A-130T-10, and all existing regressions: 194/194 locally. Provider revalidation and release remain unauthorized.
+- Initially add strict Host Promotion Evidence, Truth Reconciliation Input, and Truth Reconciliation Review Bundle schema 1 plus read-only `reconcile-truth` for current-baseline branch/source/item/subject collision review.
+- Bind QA/preproduction evidence to Host-asserted code, source, artifact, acceptance-suite, and Project Context digests; separate reusable local evidence from required integration verification.
+- Give every finding exact affected source/item/subject/scope sets, task-vs-existing-delivery blocking, human roles, deterministic preview invocations, and finite recomputation paths.
+- Verify truth-reconciliation current source/item views against the live stores, block stale candidate snapshots, bind promotion evidence to the current acceptance suite and Project Context snapshots, and publish an exact Review Bundle schema.
+- The initial truth-reconciliation slice upgraded capabilities and Exchange Protocol to 6 without changing stores or Action Plan/Review Bundle schemas; it passed A-131 through A-143, four protocol regressions, A-130R, and all then-existing regressions, 153/153 total.
+- Add read-only `context-query` and `coverage-audit`, plus preview-by-default `index-context` whose only explicit write is a disposable derived Routing Index.
+- Add Context Query, Adaptive Context Bundle, Routing Index, and Coverage Audit schema 1; upgrade capabilities and Exchange Protocol to 5 while existing store and Action/Review schemas remain unchanged.
+- Hydrate all applicable policy/validation items, route fact/reference items by original task text/topics after scope narrowing, preserve provenance/conflict closures, and fail closed at hard UTF-8/read-target budgets.
+- Separate registration coverage, Contract coverage, freshness, task health, and global health; reject stale indexes and digest-bind incremental expansion without resending prior bodies.
+- Reuse source digest/body reads within one command and share the adaptive selector with `stage-context` without adding Provider, Agent Runtime, Git, network, dependency, business-code write, or automatic approval behavior.
+- Establish the initial A-115 through A-129 local baseline at 135/135 before the later A-130R and truth-reconciliation expansion to 153/153.
+- Repair the known A-130 input-envelope difference locally with a digest-bound `context-query --prompt` projection and deterministic complete-context fallback whenever the complete prompt is no larger than the review envelope. The authorized real Host/Provider revalidation reduced the adaptive first prompt to 5,283 bytes but still scored 7/8 against the full arm's 8/8; further remediation is required and release remains blocked.
+
+## 1.6.0 - 2026-09-11
+
+- Add read-only `upgrade-check` and `upgrade-plan`, plus preview-by-default `upgrade-apply` with explicit `--write` for one compiled product-owned migration unit.
+- Add strict, self-digested Migration Manifest schema 2 and Upgrade Assessment, Migration Plan, and Upgrade Result Bundle schema 1.
+- Bind every plan to manifest, assessment, store snapshots, and managed target byte digests; stale baselines and ownership conflicts fail closed.
+- Reuse existing managed AI Entry/projection CAS, atomic replacement, and conditional recovery primitives; healthy baselines converge through zero-write `verify-complete`.
+- Upgrade capabilities and exchange protocol to version 4 while Action Plan and Review Bundle remain schema 2.
+- Keep package-manager, Git, network, project tests, business writes, automatic approval/upgrade/rollback, and overall-upgrade claims outside the product boundary.
+- Pass A-101 through A-114 plus all existing regressions, 120/120 total.
+
+## 1.5.0 - Unreleased
+
+- Add read-only `evidence` for deterministic, project-local Evidence Bundle schema 1 output.
+- Add strict Evidence Input schema 1, canonical 32 KiB input and 48 KiB output budgets, self-verifying digests, and structural privacy minimization.
+- Sample uninitialized, partial, invalid, attention, conflict, and clean Project Context health without writing or conflating observation result with governance health.
+- Upgrade capabilities and exchange protocol to version 3, publish both evidence schemas, and declare `automaticEvidenceUpload: false`.
+- Keep all transfer states human-review-required; add no upload, telemetry, Provider, Agent Runtime, Git, network, store migration, or automatic product-decision path.
+- Pass A-91 through A-100 plus all existing regressions, 106/106 total.
+
+## 1.4.0 - Unreleased
+
+- Add read-only project `status` with deterministic health and next-action references.
+- Add managed-region `publish-entry` and `remove-entry` with byte ownership, CAS, and conditional lock recovery.
+- Read Projection Lock schemas 1/2 and lazily write schema 2 on the first AI Entry write.
+- Upgrade capabilities, Action Plan, Review Bundle, and exchange protocol to version 2 while retaining schema-1 Action Plan input.
+- Publish project-status, projection-lock, and migration-manifest schemas plus the minimal `1.3.1` to `1.4.0` migration manifest.
+
+## 1.3.1 — 2026-09-10
 
 - `stage-context` 与 `integration-review` 新增可重复 `--receipt-bundle` 输入，按 Stage identity 将每份 receipt 与其输入 Stage Context Bundle 精确配对。
 - 新增严格 Stage Context Bundle schema 1 运行时验证、自身 digest/规范 UTF-8 字节核对，并按 plan 依赖顺序用已验证前序 receipt 确定性重建 Bundle。
 - 缺失、重复、多余、错配、篡改、过期 snapshot、completed receipt 绑定 blocked bundle，以及不完整或绕过的多级依赖链全部以稳定 finding 失败封闭。
 - README 中英文安装 pin、`examples/package.json`、package version 与发布验收统一为 `1.3.1`。
 - Task Context Plan、Stage Receipt、Stage Context Bundle、Integration Review Bundle 与所有 store schema 保持原版本；没有新增 Provider、Agent Runtime、Git/网络、任务执行或第三方依赖。
-- A-74 至 A-76 与全部旧回归共 82/82 项本地通过；Git commit、tag、push、npm 认证与公开发布仍未授权。
+- A-74 至 A-76 与全部旧回归共 82/82 项通过；候选包与官方 registry tarball 逐字节一致，并已完成独立安装冒烟验证。
 
 ## 1.3.0 — 2026-09-10
 

package/README.md

@@ -14,7 +14,7 @@ AI coding tools often read only part of a repository. Important conventions may
 
 - 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;
+- exposes versioned machine capabilities, schemas, and human-reviewed evidence bundles 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;
@@ -32,19 +32,37 @@ It does **not** call an AI provider, edit business code, manage Git, install dep
 Pin it as a development dependency so local users and CI run the same version:
 
 ```bash
-npm install --save-dev frontend-project-context@1.3.1
+npm install --save-dev frontend-project-context@1.7.0
 ```
 
 The package has zero runtime dependencies.
 
-`1.3.1` is the current local implementation version. Public npm `latest` remains the independently verified `1.3.0` until a separately authorized release.
+`1.7.0` is the package release candidate in this source tree. It includes the cumulative `1.4.0` status/takeover, `1.5.0` evidence, `1.6.0` target-upgrade, Adaptive Bounded Task Context, truth-resolution repair, and Chinese human-readable project semantics. The candidate has passed all 194 local regressions; public release still requires the separately governed Host/Provider and release gates.
 
 ### Quick start
 
+Every host can begin with one read-only status command, including before initialization:
+
+```bash
+npm exec --offline -- project-context status --project . --json
+```
+
+All `npm exec --offline -- project-context` commands below require the exact development dependency installed above. `--offline` makes a missing local binary fail closed instead of downloading the unrelated `project-context` package from a configured registry.
+
+`status` classifies uninitialized, partial, invalid, attention, clean, and ownership-conflict states without reading business source bodies or writing project files. After initialization, publish a fixed startup route into a managed region of root `AGENTS.md` while preserving all human content outside that region:
+
+```bash
+npm exec --offline -- project-context publish-entry --project . --output AGENTS.md --write --json
+```
+
+The `1.7.0` AI Entry renderer 3 writes human-readable project guidance in Chinese and invokes only the offline project-local CLI while keeping commands, markers, IDs, JSON fields, and enums stable in English. Existing renderer-1/2 entries remain readable but become stale and require an explicit owned republish; no entry is rewritten automatically.
+
+Use `remove-entry` with the same output to remove only a trusted managed region. Plans and previews never include `--write`; human approval of the exact path remains required.
+
 Let an existing Coding Agent prepare deterministic onboarding candidates:
 
 ```bash
-npx project-context setup \
+npm exec --offline -- project-context setup \
   --project . \
   --id my-project \
   --name "My Project" \
@@ -54,10 +72,12 @@ npx project-context setup \
 
 `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.
 
+`setup` is idempotent for an initialized project; it does not reset stores or translate already approved statements. Before an explicitly authorized fresh reinitialization, preserve every human-authored policy, validation description, manual source, and approval decision. Remove only a trusted managed AI Entry, clean up the exact disposable Project Context files externally, rerun setup from the installed package, then re-author and reapprove the preserved rules.
+
 Register an explicit source:
 
 ```bash
-npx project-context register \
+npm exec --offline -- project-context register \
   --project . \
   --id source.package \
   --kind file \
@@ -68,7 +88,7 @@ npx project-context register \
 Propose a scoped contract item. This creates a reviewable proposal; it does not approve it:
 
 ```bash
-npx project-context propose \
+npm exec --offline -- project-context propose \
   --project . \
   --id policy.ui-copy \
   --kind policy \
@@ -85,7 +105,7 @@ npx project-context propose \
 Approve only the item you reviewed:
 
 ```bash
-npx project-context approve \
+npm exec --offline -- project-context approve \
   --project . \
   --proposal .project-context/policy.ui-copy.proposal.json \
   --ids policy.ui-copy \
@@ -96,14 +116,25 @@ npx project-context approve \
 Compile context for a target and check for drift:
 
 ```bash
-npx project-context context --project . --path src --locale en
-npx project-context check --project .
+npm exec --offline -- project-context context --project . --path src --locale en
+npm exec --offline -- project-context check --project .
 ```
 
+For task-sensitive routing, save a schema-1 Context Query with the current snapshots and run:
+
+```bash
+npm exec --offline -- project-context context-query --project . --input .project-context/context-query.json --json
+npm exec --offline -- project-context context-query --project . --input .project-context/context-query.json --prompt
+npm exec --offline -- project-context coverage-audit --project . --json
+npm exec --offline -- project-context index-context --project . --json
+```
+
+`context-query --json` returns the auditable machine bundle. `--prompt` returns its digest-bound, model-facing Markdown projection without the deferred/review envelope. When the complete applicable Context is no larger than the machine review bundle, the projection deterministically falls back to the complete Context; otherwise it uses the selected evidence closure. `index-context` is read-only unless `--write` is explicit; its persisted output is disposable derived data.
+
 After project sources or implementation paths change, create one read-only reconciliation work unit:
 
 ```bash
-npx project-context sync \
+npm exec --offline -- project-context sync \
   --project . \
   --changed-path src/example.ts \
   --json
@@ -114,13 +145,13 @@ npx project-context sync \
 Discover the exchange contract without initializing the project:
 
 ```bash
-npx project-context capabilities --project . --json
+npm exec --offline -- 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:
+An external AI host can create an Action Plan schema 2 using the returned project snapshots and one of the ten advertised action kinds. Schema-1 plans remain readable. Save that short-lived plan inside the project, then produce a read-only Review Bundle:
 
 ```bash
-npx project-context preflight \
+npm exec --offline -- project-context preflight \
   --project . \
   --plan .project-context/action-plan.json \
   --json
@@ -131,7 +162,7 @@ npx project-context preflight \
 For multi-stage feature work, a host can provide a Task Context Plan, prior Stage Receipts, and explicit changed-path signals. Compile only the requested stage:
 
 ```bash
-npx project-context stage-context \
+npm exec --offline -- project-context stage-context \
   --project . \
   --plan task-context-plan.json \
   --stage stage-render \
@@ -144,7 +175,7 @@ npx project-context stage-context \
 Before an external merge, compare host-provided main/branch path signals with the plan, receipts, current Contract snapshots, and checker findings:
 
 ```bash
-npx project-context integration-review \
+npm exec --offline -- project-context integration-review \
   --project . \
   --plan task-context-plan.json \
   --receipt stage-understand.receipt.json \
@@ -156,14 +187,33 @@ npx project-context integration-review \
 
 Both commands are read-only. They do not inspect Git, read source bodies, execute the task or tests, save task state, promote decisions, or grant merge authority. Budget limits are caller-supplied canonical UTF-8 bytes and read-target counts, not model tokens.
 
-Starting with local version `1.3.1`, every supplied Stage Receipt must have exactly one matching `--receipt-bundle`. Both commands strictly validate and deterministically rebuild the complete receipt/bundle dependency chain before accepting `inputBundleDigest`; missing, duplicate, mismatched, tampered, stale, or blocked inputs fail closed. Public release remains separately gated.
+Starting with `1.3.1`, every supplied Stage Receipt must have exactly one matching `--receipt-bundle`. Both commands strictly validate and deterministically rebuild the complete receipt/bundle dependency chain before accepting `inputBundleDigest`; missing, duplicate, mismatched, tampered, stale, or blocked inputs fail closed.
+
+To turn an already-redacted local observation into a deterministic Evidence Bundle, keep the input JSON inside the project and run:
+
+```bash
+npm exec --offline -- project-context evidence --project . --input evidence-input.json --json
+```
+
+`evidence` reads only the supplied input plus Project Context health metadata, writes nothing, and never uploads. It excludes project identity, paths, source bodies, logs, and Contract values by structure. The two summary fields remain free text, so every bundle is permanently marked `human-review-required`; a person decides whether and where to transfer it.
+
+After a human and the Host pin an exact target package version outside this product, assess the project-owned migration surface and create one digest-bound work unit:
+
+```bash
+npm exec --offline -- project-context upgrade-check --project . --from-version 1.5.0 --json > .project-context/upgrade-assessment.json
+npm exec --offline -- project-context upgrade-plan --project . --assessment .project-context/upgrade-assessment.json --json > .project-context/migration-plan.json
+npm exec --offline -- project-context upgrade-apply --project . --plan .project-context/migration-plan.json --json
+npm exec --offline -- project-context upgrade-apply --project . --plan .project-context/migration-plan.json --write --json
+```
+
+`upgrade-check` and `upgrade-plan` are permanently read-only. `upgrade-apply` previews by default and can write only the single compiled, product-owned unit shown in that exact plan. Re-run check and plan after every unit. Even `coreMigration: complete` still requires the Host to verify dependency/lockfile pins, project tests or CI, and an independent new window. The product does not run a package manager, Git, network, project tests, business writes, automatic approval, rollback, or publication.
 
-The package publishes eight machine schemas: capabilities, Assist Bundle, Action Plan, Review Bundle, Task Context Plan, Stage Receipt, Stage Context Bundle, and Integration Review Bundle.
+The package publishes twenty machine schemas, including capabilities 7, project status, projection lock 1/2, Migration Manifest 2, Upgrade Assessment/Migration Plan/Upgrade Result Bundle 1, Evidence Input/Bundle, Assist/Action/Review bundles, the four staged-context schemas, Context Query/Adaptive Context Bundle/Routing Index 2, and Coverage Audit 1.
 
 Generate the read-only governance dashboard:
 
 ```bash
-npx project-context dashboard --project . > project-context-dashboard.html
+npm exec --offline -- project-context dashboard --project . > project-context-dashboard.html
 ```
 
 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.
@@ -205,28 +255,34 @@ All commands are read-only unless that command explicitly includes `--write`. So
 | --- | --- |
 | `setup` | Aggregate safe initialization, conservative discovery, and an Assist Bundle |
 | `capabilities` | Discover protocol versions, schemas, action kinds, initialization, and permanent boundaries |
+| `evidence` | Build a deterministic, read-only, human-reviewed Evidence Bundle from a project-local input |
 | `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 |
+| `context-query` | Compile adaptive review JSON or its compact model-facing `--prompt` projection with complete-context fallback |
+| `coverage-audit` | Audit declared registration coverage without claiming all project truth |
+| `index-context` | Preview or explicitly persist a disposable routing index |
 | `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 |
 | `stage-context` | Rebuild receipt/bundle inputs and compile the explicitly requested stage within caller-provided byte/read-target budgets |
 | `integration-review` | Review paired receipts/bundles, host path signals, baselines, and context-layer conflicts without Git |
+| `reconcile-truth` | Reconcile explicit branch/promotion evidence against the current truth baseline without reading Git or CI |
 | `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.
+Run `npm exec --offline -- project-context --help` for the complete command syntax.
 
 ### Documentation
 
+- [User and AI operation manual](./docs/USER-AND-AI-OPERATION-MANUAL.md)
 - [Product constitution](./docs/00-PRODUCT-CONSTITUTION.md)
 - [Program and CLI design](./docs/04-PROGRAM-DESIGN.md)
 - [Acceptance contract](./docs/05-ACCEPTANCE-CONTRACT.md)
@@ -237,7 +293,9 @@ Run `npx project-context --help` for the complete command syntax.
 - [Guided onboarding and AI-assisted reconciliation](./docs/16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md)
 - [AI exchange boundary](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
 - [Branch-aware staged context and handoff](./docs/18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md)
-- [AI Exchange Boundary design](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
+- [Evidence Feedback Protocol](./docs/21-PHASE-B-EVIDENCE-FEEDBACK-PROTOCOL-DESIGN.md)
+- [Real-project source-of-truth maintenance design](./docs/25-REAL-PROJECT-SOURCE-OF-TRUTH-MAINTENANCE-DESIGN.md)
+- [A-130 quality closure and adaptive delivery repair](./docs/26-A130-QUALITY-CLOSURE-AND-ADAPTIVE-DELIVERY-REPAIR-DESIGN.md)
 - [Upgrade notes](./UPGRADING.md)
 
 ## 中文
@@ -248,7 +306,7 @@ AI 编程工具通常只读取仓库的一部分，而项目约定分散在文
 
 - 按文件或目录选择真正生效的已批准规则；
 - 为现有 Coding Agent 生成精简且可追溯的上下文；
-- 向模型无关宿主公开版本化 capability 与机器 schema；
+- 向模型无关宿主公开版本化 capability、机器 schema 与需人工复核的证据包；
 - 把 AI 建议收敛为无权限 Action Plan 和只读 Review Bundle；
 - 从同一合同生成受管 Markdown、AGENTS 或 Ruler 兼容投影；
 - 检测来源、合同和投影是否过期；
@@ -266,19 +324,37 @@ AI 编程工具通常只读取仓库的一部分，而项目约定分散在文
 建议固定为开发依赖，让本地与 CI 使用同一版本：
 
 ```bash
-npm install --save-dev frontend-project-context@1.3.1
+npm install --save-dev frontend-project-context@1.7.0
 ```
 
 本包没有运行时第三方依赖。
 
-`1.3.1` 是当前本地实现版本。公共 npm `latest` 在获得独立发布授权前仍是已经独立核验的 `1.3.0`。
+`1.7.0` 是当前源码树描述的版本，累计包含 `1.4.0` 状态/接管、`1.5.0` 证据、`1.6.0` 目标升级、自适应有界任务上下文、真源裁定修复和中文人类可读项目语义。候选已通过本地 194 项回归；公开发布仍必须通过单独治理的 Host/Provider 与发布门槛。
 
 ### 快速开始
 
+任何宿主都可以先运行同一条只读状态命令，包括尚未初始化的项目：
+
+```bash
+npm exec --offline -- project-context status --project . --json
+```
+
+以下所有 `npm exec --offline -- project-context` 命令都要求先安装上面的精确开发依赖。`--offline` 会在本地 CLI 缺失时失败封闭，避免从配置的 registry 下载无关的同名 `project-context` 包。
+
+`status` 在不读取业务源码正文、不写项目文件的前提下分类 uninitialized、partial、invalid、attention、clean 和所有权冲突。初始化后，可把固定启动路由发布到根 `AGENTS.md` 的受管区域，同时完整保留区域外人工内容：
+
+```bash
+npm exec --offline -- project-context publish-entry --project . --output AGENTS.md --write --json
+```
+
+`1.7.0` 的 AI Entry renderer 3 默认用中文生成人类可读的项目规则，并只调用离线的项目本地 CLI；命令、marker、ID、JSON 字段和枚举继续保持稳定英文。既有 renderer 1/2 入口仍可读取，但会标记 stale，只有显式受管 republish 才会升级，不会自动重写。
+
+使用相同 output 的 `remove-entry` 只移除可信受管区域。计划与 preview 都不含 `--write`，仍需人对精确路径授权。
+
 让现有 Coding Agent 生成确定性的首次接入候选：
 
 ```bash
-npx project-context setup \
+npm exec --offline -- project-context setup \
   --project . \
   --id my-project \
   --name "My Project" \
@@ -288,10 +364,12 @@ npx project-context setup \
 
 `setup` 只创建三个 store 和一份 create-only proposal，不会批准候选或发布 Agent 文件。JSON 中的 `artifacts` receipt 会返回精确 proposal 路径，以及 preview、create 或 unchanged 结果。先读取 `summary`、`workUnits` 和 `readTargets`，再审查具体 proposal ID。
 
+`setup` 对已初始化项目是幂等操作，不会重置 store，也不会翻译已经批准的 statement。明确授权全新初始化前，必须先保留所有人工 policy、validation-description、手工 source 和批准决定；只移除可信受管 AI Entry，再由外部精确清理可丢弃的 Project Context 文件，使用已安装包重新 setup，最后重新录入并批准所保留的人工规则。
+
 登记一个明确来源：
 
 ```bash
-npx project-context register \
+npm exec --offline -- project-context register \
   --project . \
   --id source.package \
   --kind file \
@@ -302,7 +380,7 @@ npx project-context register \
 提出一条带作用域的合同项。这里只生成待审 proposal，不会自动批准：
 
 ```bash
-npx project-context propose \
+npm exec --offline -- project-context propose \
   --project . \
   --id policy.ui-copy \
   --kind policy \
@@ -319,7 +397,7 @@ npx project-context propose \
 人工审查后，只批准明确选中的 item：
 
 ```bash
-npx project-context approve \
+npm exec --offline -- project-context approve \
   --project . \
   --proposal .project-context/policy.ui-copy.proposal.json \
   --ids policy.ui-copy \
@@ -330,14 +408,25 @@ npx project-context approve \
 为目标目录生成上下文，并检查漂移：
 
 ```bash
-npx project-context context --project . --path src --locale zh-CN
-npx project-context check --project .
+npm exec --offline -- project-context context --project . --path src --locale zh-CN
+npm exec --offline -- project-context check --project .
 ```
 
+需要按任务路由上下文时，把当前 snapshot 写入 schema 2 Context Query，再运行：
+
+```bash
+npm exec --offline -- project-context context-query --project . --input .project-context/context-query.json --json
+npm exec --offline -- project-context context-query --project . --input .project-context/context-query.json --prompt
+npm exec --offline -- project-context coverage-audit --project . --json
+npm exec --offline -- project-context index-context --project . --json
+```
+
+`context-query --json` 返回可审计的机器 Bundle，`--prompt` 只返回与 digest 绑定的模型面向 Markdown，不把 deferred/review 包络或 source locator 发给模型。完整 Context 在 delivery soft threshold 内或不大于 adaptive 正文时优先；非 ready 交付 stdout 为空。`index-context` 默认只读；只有显式 `--write` 才保存可删除、可重建的派生索引。
+
 项目来源或实现路径变化后，可一次生成只读的增量维护工作单元：
 
 ```bash
-npx project-context sync \
+npm exec --offline -- project-context sync \
   --project . \
   --changed-path src/example.ts \
   --json
@@ -348,13 +437,13 @@ npx project-context sync \
 无需初始化项目即可查询双向交换协议：
 
 ```bash
-npx project-context capabilities --project . --json
+npm exec --offline -- project-context capabilities --project . --json
 ```
 
-外部 AI 宿主可使用返回的三个项目 snapshot 和八类 action 生成 Action Plan schema 1。把这份短生命周期计划保存在项目内，再生成只读 Review Bundle：
+外部 AI 宿主可使用返回的三个项目 snapshot 和十类 action 生成 Action Plan schema 2；schema-1 plan 仍可读取。把这份短生命周期计划保存在项目内，再生成只读 Review Bundle：
 
 ```bash
-npx project-context preflight \
+npm exec --offline -- project-context preflight \
   --project . \
   --plan .project-context/action-plan.json \
   --json
@@ -365,7 +454,7 @@ npx project-context preflight \
 多阶段功能开发中，宿主可以显式提供 Task Context Plan、前序 Stage Receipt 和 changed-path 信号，只编译当前指定阶段：
 
 ```bash
-npx project-context stage-context \
+npm exec --offline -- project-context stage-context \
   --project . \
   --plan task-context-plan.json \
   --stage stage-render \
@@ -378,7 +467,7 @@ npx project-context stage-context \
 外部合并前，可把宿主提供的 main/branch 路径信号与 plan、receipt、当前 Contract snapshot 和 checker finding 一起进行只读审查：
 
 ```bash
-npx project-context integration-review \
+npm exec --offline -- project-context integration-review \
   --project . \
   --plan task-context-plan.json \
   --receipt stage-understand.receipt.json \
@@ -390,14 +479,33 @@ npx project-context integration-review \
 
 两个命令都不会读取 Git 或源码正文、执行任务或测试、保存任务状态、晋升决定或授予合并权限。预算由调用方以规范 UTF-8 字节数和 read-target 数量显式提供，不等同于模型 token。
 
-从本地版本 `1.3.1` 起，每份 Stage Receipt 都必须恰好对应一份 `--receipt-bundle`。两个命令会严格验证并确定性重建完整 receipt/bundle 依赖链后再接受 `inputBundleDigest`；缺失、重复、错配、篡改、过期或 blocked 输入都会失败封闭。公开发布仍需单独授权。
+从 `1.3.1` 起，每份 Stage Receipt 都必须恰好对应一份 `--receipt-bundle`。两个命令会严格验证并确定性重建完整 receipt/bundle 依赖链后再接受 `inputBundleDigest`；缺失、重复、错配、篡改、过期或 blocked 输入都会失败封闭。
+
+要把一次已经脱敏的本地观察收敛为确定性 Evidence Bundle，请把输入 JSON 保持在项目内并运行：
+
+```bash
+npm exec --offline -- project-context evidence --project . --input evidence-input.json --json
+```
+
+`evidence` 只读取这份输入和 Project Context 健康元数据，不写文件，也不上传；项目身份、路径、来源正文、日志和 Contract value 按结构排除。两个 summary 仍是自由文本，因此所有 bundle 永远标记为 `human-review-required`，由人决定是否以及向谁转交。
+
+在人和 Host 已于产品边界外把依赖固定到精确目标版本后，可以评估产品自有迁移面，并生成一个 digest 绑定的工作单元：
+
+```bash
+npm exec --offline -- project-context upgrade-check --project . --from-version 1.5.0 --json > .project-context/upgrade-assessment.json
+npm exec --offline -- project-context upgrade-plan --project . --assessment .project-context/upgrade-assessment.json --json > .project-context/migration-plan.json
+npm exec --offline -- project-context upgrade-apply --project . --plan .project-context/migration-plan.json --json
+npm exec --offline -- project-context upgrade-apply --project . --plan .project-context/migration-plan.json --write --json
+```
+
+`upgrade-check` 与 `upgrade-plan` 永久只读；`upgrade-apply` 默认 preview，只有显式 `--write` 才能执行该 plan 展示的一个已编译、产品自有单元。每个单元后必须重新 check/plan。即使 `coreMigration: complete`，Host 仍需核对依赖与 lockfile、运行项目测试或 CI，并用独立新窗口复核。产品不会执行包管理器、Git、网络、项目测试、业务写入、自动批准、回滚或发布。
 
-npm 包公开八份机器 schema：capabilities、Assist Bundle、Action Plan、Review Bundle、Task Context Plan、Stage Receipt、Stage Context Bundle 和 Integration Review Bundle。
+npm 包包含二十份机器 schema，包括 capabilities 7、project status、projection lock 1/2、Migration Manifest 2、Upgrade Assessment/Migration Plan/Upgrade Result Bundle 1、Evidence Input/Bundle、Assist/Action/Review Bundle、四份 staged-context schema、Context Query/Adaptive Context Bundle/Routing Index 2 与 Coverage Audit 1。
 
 生成只读治理看板：
 
 ```bash
-npx project-context dashboard --project . > project-context-dashboard.html
+npm exec --offline -- project-context dashboard --project . > project-context-dashboard.html
 ```
 
 看板是一个可离线打开的自包含 HTML。命令只输出到 stdout，不会自动打开浏览器，也不会修改合同。
@@ -439,28 +547,34 @@ npx project-context dashboard --project . > project-context-dashboard.html
 | --- | --- |
 | `setup` | 聚合安全初始化、保守 discovery 和 Assist Bundle |
 | `capabilities` | 查询协议版本、schema、action kind、初始化状态和永久边界 |
+| `evidence` | 从项目内输入生成确定性、只读且需人工复核的 Evidence Bundle |
 | `init` | 安全创建空项目合同 |
 | `register` | 登记文件、路径、JSON Pointer 或人工决定 |
 | `discover` | 保守提出首次接入候选 |
 | `propose` | 创建 fact、policy、reference 或 validation-description |
 | `approve` | 显式批准选中的 proposal ID |
 | `context` | 为一个或多个路径编译已批准上下文 |
+| `context-query` | 编译自适应审查 JSON，或生成带完整上下文回退的紧凑 `--prompt` 模型投影 |
+| `coverage-audit` | 审计声明范围内的来源登记覆盖，不宣称发现全部项目真源 |
+| `index-context` | 预览或显式保存可删除的派生路由索引 |
 | `publish` | 写入仍归工具所有的 AGENTS、Markdown 或 Ruler 投影 |
 | `check` | 检测来源、合同和投影漂移 |
 | `sync` | 聚合来源漂移、item 影响、变化路径和维护工作单元 |
 | `preflight` | 验证 Action Plan 并返回只读分组 Review Bundle |
 | `stage-context` | 重建 receipt/bundle 输入，并在调用方字节/read-target 预算内编译显式指定的当前阶段 |
 | `integration-review` | 不读取 Git，只读审查成对 receipt/bundle、路径信号、baseline 与上下文冲突 |
+| `reconcile-truth` | 不读取 Git/CI，将显式分支与晋升证据对当前真源基线做只读重算 |
 | `dashboard` | 生成只读治理看板 |
 | `review-source` | 查看来源变化及精确影响集 |
 | `accept-source-change` | 接受固定摘要并撤销受影响批准 |
 | `revise` / `deprecate` | 显式维护合同项 |
 | `deprecate-source` | 用审计记录退役已无引用的来源 |
 
-运行 `npx project-context --help` 查看完整命令语法。
+运行 `npm exec --offline -- project-context --help` 查看完整命令语法。
 
 ### 深入文档
 
+- [使用与 AI 协作操作手册](./docs/USER-AND-AI-OPERATION-MANUAL.md)
 - [产品宪法](./docs/00-PRODUCT-CONSTITUTION.md)
 - [程序与 CLI 设计](./docs/04-PROGRAM-DESIGN.md)
 - [验收合同](./docs/05-ACCEPTANCE-CONTRACT.md)
@@ -471,7 +585,9 @@ npx project-context dashboard --project . > project-context-dashboard.html
 - [引导式接入与 AI 辅助维护](./docs/16-GUIDED-ONBOARDING-AND-AI-RECONCILIATION-DESIGN.md)
 - [AI 双向交换边界](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
 - [分支感知的分阶段上下文与交接](./docs/18-BRANCH-AWARE-STAGED-CONTEXT-DESIGN.md)
-- [AI 双向交换边界设计](./docs/17-AI-EXCHANGE-BOUNDARY-DESIGN.md)
+- [Evidence Feedback Protocol](./docs/21-PHASE-B-EVIDENCE-FEEDBACK-PROTOCOL-DESIGN.md)
+- [真实项目全量应用下的真源维护设计](./docs/25-REAL-PROJECT-SOURCE-OF-TRUTH-MAINTENANCE-DESIGN.md)
+- [A-130 质量闭环与自适应交付协议修订](./docs/26-A130-QUALITY-CLOSURE-AND-ADAPTIVE-DELIVERY-REPAIR-DESIGN.md)
 - [升级说明](./UPGRADING.md)
 
 ## License / 许可证

package/UPGRADING.md

@@ -1,5 +1,59 @@
 # 升级说明
 
+## `1.6.0 → 1.7.0`（本地实现，未发布）
+
+`1.7.0` 新增只读 `context-query`、`coverage-audit`、`reconcile-truth`，以及默认 preview、只有显式 `--write` 才持久化可删除派生索引的 `index-context`。Context Query、Adaptive Context Bundle、Routing Index、Truth Reconciliation Input 与 Truth Reconciliation Review Bundle 当前写 schema 2，Coverage Audit 与 Host Promotion Evidence 保持 schema 1，capabilities / Exchange Protocol 升至 7；Contract、source lock、proposal、持久 renderer、Action Plan 与 Review Bundle 均不迁移。AI Entry 的人类可读文案改为中文，并固定 `npm exec --offline -- project-context` 的项目本地安全入口，renderer 从 1/2 升至 3；Projection Lock schema 仍为 2。
+
+Migration Manifest 把 `1.6.0` 到中文 AI Entry renderer 3 的迁移记录为显式 `republish-ai-entry`。升级后应重新生成 capabilities、schema 2 Context Query/Adaptive Context Bundle/Truth Reconciliation 工件与 Coverage Audit；schema 1 Routing Index 可在内存中重建，schema 1 Adaptive Bundle/Truth Review 不得作为 previous 输入。既有 renderer 1/2 AI Entry 仍可读取但会报告 stale，工具只生成一个摘要绑定的 republish 单元，未经 `--write` 不修改 `AGENTS.md` 或 Projection Lock。这些派生、短生命周期或投影工件不得回写 Project Contract，也不授予任务执行权限。
+
+目标项目必须先由 Host 把依赖精确固定到 `frontend-project-context@1.7.0`，再使用 `npm exec --offline -- project-context` 执行升级或初始化；不能用可能回退到 registry 同名包的 `npx project-context`。`setup` 不是 reset/翻译命令：需要全新初始化时，先外部留存人工规则并安全移除受管 Entry，再经明确授权清理精确 store，最后从已安装包重建和重新批准。
+
+```bash
+project-context upgrade-check --project . --from-version 1.6.0 --json
+project-context index-context --project . --json
+project-context index-context --project . --write --json
+project-context coverage-audit --project . --json
+project-context context-query --project . --input .project-context/context-query.json --json
+project-context context-query --project . --input .project-context/context-query.json --prompt
+project-context reconcile-truth --project . --input truth-reconciliation-input.json --json
+project-context reconcile-truth --project . --input truth-reconciliation-resolution.json --previous-review truth-reconciliation-review.json --json
+```
+
+`context-query --json` 返回可审计包络，`--prompt` 只返回 digest-bound 模型输入；默认只在当前证据闭包中校验相关来源，`strict-current` 或 `complete` 会回退到完整健康与覆盖审计。audit、delivery、read-target 预算独立，非 ready 交付不输出正文。`reconcile-truth` 严格核对 live source/item 基线、Project snapshots、acceptance suite 与 previous Review，只生成无权 Review Bundle。docs/26 本地实现和 194/194 回归已完成；历史真实 Host/Provider 复验仍因质量 7/8 对 8/8 而失败，新的 Provider 复验、Git 和发布仍未授权。
+
+## `1.3.1 / 1.4.0 / 1.5.0 → 1.6.0`
+
+`1.6.0` 新增 Target Upgrade Protocol：Migration Manifest 升至 schema 2，新增 Upgrade Assessment、Migration Plan 与 Upgrade Result Bundle schema 1，并把 capabilities / Exchange Protocol 升至 4。Action Plan 与 Review Bundle 继续写 schema 2；Contract、source lock、proposal、projection lock 与 renderer 的目标版本不变。
+
+依赖和 lockfile 必须先由人授权、由 Host 在产品边界外固定到精确 `1.6.0`。随后按顺序运行：
+
+```bash
+project-context upgrade-check --project . --from-version 1.5.0 --json
+project-context upgrade-plan --project . --assessment .project-context/upgrade-assessment.json --json
+project-context upgrade-apply --project . --plan .project-context/migration-plan.json --json
+project-context upgrade-apply --project . --plan .project-context/migration-plan.json --write --json
+```
+
+assessment 与 plan 文件由 Host 保存到项目内 `.project-context/` 的非 store JSON 路径。前两条命令永久只读；apply 默认 preview，并且每份 plan 只允许一个已编译的产品自有工作单元。每次写入后旧 plan 必然过期，必须从真实字节重新 check/plan。健康的 `1.3.1`、`1.4.0`、`1.5.0` 基线走 `package-only` / `verify-complete`，不会为了升级人为改写 store；只有仍受工具所有且 renderer 过旧的 AI Entry/projection 才会生成 republish 单元。
+
+`coreMigration: complete` 只证明产品自有迁移面收敛。依赖/lockfile 一致性、项目测试或 CI、独立新窗口复核、外部恢复点以及临时 assessment/plan/result 清理由 Host 或人确认。工具不调用包管理器、不读 Git、不联网、不执行项目测试、不修改业务代码，也不自动批准、回滚或发布。
+
+## `1.4.0 → 1.5.0`
+
+`1.5.0` 新增只读 `evidence`、Evidence Input/Bundle schema 1，并把 Exchange Protocol 与 capabilities 升至 3。Action Plan/Review Bundle 保持 schema 2，Project Status、Assist Bundle 与四份 staged-context schema 保持原版本；Contract、source/projection lock、proposal 和 renderer 均无迁移。
+
+本版本的 manifest `writes` 为空，回退类别为 `package-only`。从公开 `1.3.1` 直达 `1.5.0` 时，仍需遵守 `1.4.0` 已声明的 AI Entry/projection-lock 延迟迁移：如果曾运行 `publish-entry --write`，回到 `1.3.1` reader 需要从外部 Git 或备份同时恢复 `AGENTS.md` 和 projection lock。
+
+外部 consumer 必须按 capabilities schema 3 / Exchange Protocol 3 分支，并把 Evidence Bundle 视为短生命周期、`human-review-required` 的本地工件。工具不上传、不保存、不自动脱敏自由文本、不创建需求或执行权限。
+
+## `1.3.1 → 1.4.0`
+
+`1.4.0` 新增只读 `status`、`publish-entry` / `remove-entry`区域型 AI Entry、Projection Lock schema 1/2 reader、Exchange Protocol 2 与机器可读迁移清单。Contract 1/2、source lock 1、proposal 1、Assist Bundle 1 和四份 staged-context schema 1 不变。
+
+只安装新包且未写 AI Entry 时可仅回退包版本。第一次成功执行 `publish-entry --write` 才会把 `.project-context/projections.lock.json` 延迟转换为 schema 2；此后对 `1.3.1` reader 为 forward-only。如必须回到 `1.3.1`，需通过外部 Git 或备份同时恢复 `AGENTS.md` 与 projection lock，不能只降包版本。精确 reader/writer、consumer change 与 rollback class 见 `migration-manifest.json`。
+
+Action Plan 2 新增 `publish-ai-entry` 和 `remove-ai-entry`，但仍只是无权建议；Review Bundle 的 structured invocation 不含 `--write` 或 `--by`。`status.health: clean` 只证明 Project Context 治理层健康，不代表业务测试、Git 或发布状态。这些能力已随 `1.6.0` 发布到官方公共 npm，并完成候选/registry 逐字节一致性与全新安装复验。
+
 ## `1.3.0 → 1.3.1`
 
 `1.3.1` 修复 `1.3.0` 正式调用链未把 Stage Receipt `inputBundleDigest` 绑定到实际 Stage Context Bundle 的协议缺陷，并统一 README、示例依赖、package 与发布验收的消费者版本 pin。
@@ -8,7 +62,7 @@
 
 不带 receipt 的首 stage 调用不变。旧的“只传 receipt”调用会从可能错误的 ready/reviewable 收紧为 blocked，这是恢复既有失败封闭合同。四份 task/bundle schema 仍为 1，所有持久 store、exchange protocol、renderer 和 Dashboard View Model 均不迁移。命令仍只读，不创建 task store、不读取 Git/网络/源码正文、不执行任务或测试，也不增加依赖。
 
-本地实现与 A-01 至 A-76、B0、CLI 和发布工件共 82 项验收已经完成；公开 npm `latest` 仍为 `1.3.0`，`1.3.1` 的打包、Git 与发布需另行授权。
+实现与 A-01 至 A-76、B0、CLI 和发布工件共 82 项验收已经完成。该版本已于 2026-09-10 发布到官方公共 npm，`latest` 指向 `1.3.1`；发布包与冻结候选逐字节一致，从 registry 独立安装后的 help、capabilities 与版本冒烟均通过。
 
 ## `1.2.0 → 1.3.0`