frontend-project-context 1.8.0 → 1.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +18 -1
  2. package/README.md +7 -7
  3. package/UPGRADING.md +10 -0
  4. package/docs/08-INSTALLATION-AND-DISTRIBUTION.md +9 -3
  5. package/docs/14-FORMAL-RELEASE-READINESS.md +14 -0
  6. package/docs/28-REAL-PROJECT-ONBOARDING-CLOSURE-DESIGN.md +10 -0
  7. package/docs/29-REAL-PROJECT-1.8.0-INITIALIZATION-OBSERVATIONS.md +228 -0
  8. package/docs/30-TASK-CONTEXT-CONSUMPTION-CLOSURE-DESIGN.md +563 -0
  9. package/docs/31-TASK-CONTEXT-INTEGRITY-REPAIR-DESIGN.md +281 -0
  10. package/docs/AI-PROJECT-INITIALIZATION.md +3 -2
  11. package/docs/PRODUCT-SHARING-AND-ADOPTION-GUIDE.md +111 -0
  12. package/docs/README.md +14 -2
  13. package/docs/USER-AND-AI-OPERATION-MANUAL.md +3 -3
  14. package/docs/assets/product-sharing-01-overview.svg +32 -0
  15. package/docs/assets/product-sharing-02-how-it-works.svg +17 -0
  16. package/docs/assets/product-sharing-03-example.svg +19 -0
  17. package/examples/package.json +1 -1
  18. package/migration-manifest.json +30 -12
  19. package/package.json +2 -2
  20. package/schemas/capabilities.schema.json +14 -10
  21. package/schemas/context-bundle.schema.json +32 -0
  22. package/schemas/coverage-audit.schema.json +6 -4
  23. package/schemas/evidence-bundle.schema.json +1 -1
  24. package/schemas/initialization-instruction.schema.json +17 -5
  25. package/schemas/migration-manifest.schema.json +3 -3
  26. package/schemas/migration-plan.schema.json +1 -1
  27. package/schemas/projection-lock.schema.json +1 -1
  28. package/schemas/upgrade-assessment.schema.json +1 -1
  29. package/schemas/upgrade-result-bundle.schema.json +1 -1
  30. package/src/project-context/adaptive-context-schema.mjs +1 -1
  31. package/src/project-context/adaptive-context.mjs +12 -23
  32. package/src/project-context/ai-entry.mjs +22 -9
  33. package/src/project-context/approver.mjs +6 -2
  34. package/src/project-context/authoring.mjs +28 -8
  35. package/src/project-context/capabilities.mjs +4 -1
  36. package/src/project-context/checker.mjs +1 -1
  37. package/src/project-context/cli.mjs +29 -16
  38. package/src/project-context/context-bundle.mjs +378 -0
  39. package/src/project-context/contract-schema.mjs +62 -9
  40. package/src/project-context/coverage-profile.mjs +127 -0
  41. package/src/project-context/exchange-schema.mjs +23 -6
  42. package/src/project-context/exchange.mjs +3 -0
  43. package/src/project-context/initialization-instruction.mjs +20 -2
  44. package/src/project-context/maintenance.mjs +5 -4
  45. package/src/project-context/migration-manifest.mjs +3 -3
  46. package/src/project-context/renderer.mjs +11 -4
  47. package/src/project-context/source-reader.mjs +27 -2
  48. package/src/project-context/upgrade-schema.mjs +1 -1
package/CHANGELOG.md CHANGED
@@ -1,6 +1,23 @@
1
1
  # Changelog
2
2
 
3
- ## 1.8.0 - Unreleased
3
+ ## 1.9.1 - 2026-09-23
4
+
5
+ - Repair Context Bundle read-target identity so task targets and local Contract sources merge by normalized path without duplicate output.
6
+ - Preserve complete, stable unions of item IDs, source IDs, reasons, and every JSON Pointer, including the RFC 6901 root pointer.
7
+ - Share one strict coverage profile parser and selector between Context Bundle and Coverage Audit; invalid v1/v2 profiles now fail closed consistently.
8
+ - Add HC-01 through HC-14 while retaining TC-01 through TC-16 and every prior regression; public schemas, Exchange Protocol 9, and AI Entry renderer 5 remain unchanged.
9
+ - Adopt schema-3 consumption, outside-owned AI Entry digest mode, and bounded coverage v2 in this repository.
10
+ - Pass read-only real-Host revalidation in `dtg-tmc-mobile` and `dtg-tmc-pc` with the same frozen source candidate; both end clean, same-path task/source aggregation stays unique, and undeclared target coverage is reported as a Contract data gap. The release tarball is a separate artifact and does not claim byte identity with that earlier source snapshot.
11
+
12
+ ## 1.9.0 - Unreleased
13
+
14
+ - Add deterministic `context --locate --task` followed by exact, order-independent multi-path targeted Context.
15
+ - Publish Context Bundle schema 1 with structured items, scope coverage, typed read targets, gaps, authority handoff, compatibility `content`, and a canonical digest.
16
+ - Add Contract schema 3 `consumption` roles and `outside-owned-ai-entry` source digest mode while preserving schema-1/2 read-only bytes.
17
+ - Add coverage profile v2 / Coverage Audit schema 2, Initialization Instruction schema 2, capabilities / Exchange Protocol 9, and AI Entry renderer 5.
18
+ - Add TC-01 through TC-16 without Provider, Agent Runtime, Git, network, dependency installation, business-code execution, or a new persistent store.
19
+
20
+ ## 1.8.0 - 2026-09-15
4
21
 
5
22
  - Add the package-owned `docs/AI-PROJECT-INITIALIZATION.md` as the only normative Host initialization procedure and expose it through read-only `instructions --json|--prompt` plus capabilities discovery.
6
23
  - Resolve and freeze `targetRoot`, forbid parent-project truth discovery and outside symlink evidence, and keep Provider, Agent Runtime, Git, network, package mutation, business-code writes, automatic approval, and publication outside the runtime.
package/README.md CHANGED
@@ -32,12 +32,12 @@ It does **not** call an AI provider, edit business code, manage Git, install dep
32
32
  Pin it as a development dependency so local users and CI run the same version:
33
33
 
34
34
  ```bash
35
- npm install --save-dev frontend-project-context@1.8.0
35
+ npm install --save-dev frontend-project-context@1.9.1
36
36
  ```
37
37
 
38
38
  The package has zero runtime dependencies.
39
39
 
40
- `1.8.0` is the Real Project Onboarding Closure release. It adds one package-owned Host initialization instruction, capabilities schema / Exchange Protocol 8, project-status schema 2 with independent Contract readiness, and AI Entry renderer 4. Local O-01 through O-12, the complete regression suite, and an isolated real-project memoryless Host acceptance form its release gate.
40
+ Version `1.9.1` repairs normalized-path read-target aggregation, lossless JSON Pointer union, and shared strict coverage parsing while keeping Context Bundle schema 1, Coverage Audit schema 2, capabilities / Exchange Protocol 9, and AI Entry renderer 5 unchanged. Read-only real-Host revalidation passed in both TMC targets on the same frozen source candidate; that earlier source snapshot is distinct from the published package artifact.
41
41
 
42
42
  ### Quick start
43
43
 
@@ -58,7 +58,7 @@ All `npm exec --offline -- project-context` commands below require the exact dev
58
58
  npm exec --offline -- project-context publish-entry --project . --output AGENTS.md --write --json
59
59
  ```
60
60
 
61
- The `1.8.0` AI Entry renderer 4 requires every clean-state real task to compile task/path context and consume actual Contract item IDs, scopes, and read targets before source development. Existing renderer-1/2/3 entries remain readable but become stale and require an explicit owned republish; no entry is rewritten automatically.
61
+ Version `1.9.1` keeps AI Entry renderer 5: it routes unknown targets through `context --locate`, then recompiles exact multi-path Context and reports item IDs, scopeCoverage, required/conditional read targets, provenance-only sources, and gaps. Existing renderer-1/2/3/4 entries remain readable but stale until an explicit owned republish.
62
62
 
63
63
  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.
64
64
 
@@ -211,7 +211,7 @@ npm exec --offline -- project-context upgrade-apply --project . --plan .project-
211
211
 
212
212
  `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.
213
213
 
214
- 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.
214
+ The package publishes twenty machine schemas, including capabilities 9, 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 2.
215
215
 
216
216
  Generate the read-only governance dashboard:
217
217
 
@@ -327,12 +327,12 @@ AI 编程工具通常只读取仓库的一部分,而项目约定分散在文
327
327
  建议固定为开发依赖,让本地与 CI 使用同一版本:
328
328
 
329
329
  ```bash
330
- npm install --save-dev frontend-project-context@1.8.0
330
+ npm install --save-dev frontend-project-context@1.9.1
331
331
  ```
332
332
 
333
333
  本包没有运行时第三方依赖。
334
334
 
335
- `1.8.0` 是 Real Project Onboarding Closure 正式版本:新增包内唯一 Host 初始化指令、capabilities schema / Exchange Protocol 8、带独立 Contract readiness 的 project-status schema 2,以及 AI Entry renderer 4。本地 O-01 至 O-12、完整回归与隔离真实项目的无历史 Host 接管共同构成发布门。
335
+ `1.9.1` 修复了规范化 path 级 read-target 聚合、JSON Pointer 无损并集和共享严格 coverage 解析,Context Bundle schema 1、Coverage Audit schema 2、capabilities / Exchange Protocol 9 与 AI Entry renderer 5 保持不变。两个 TMC 目标曾使用同一冻结源码候选完成只读真实 Host 复验;该历史源码快照与正式包工件不是同一字节对象。
336
336
 
337
337
  ### 快速开始
338
338
 
@@ -353,7 +353,7 @@ npm exec --offline -- project-context status --project . --json
353
353
  npm exec --offline -- project-context publish-entry --project . --output AGENTS.md --write --json
354
354
  ```
355
355
 
356
- `1.8.0` 的 AI Entry renderer 4 要求 clean 状态下的真实任务先编译 task/path context,消费实际命中的 Contract item IDs、scope 和 read targets,之后才能进入源码。既有 renderer 1/2/3 入口仍可读取但会标记 stale,只有显式受管 republish 才会升级,不会自动重写。
356
+ `1.9.1` 继续使用 AI Entry renderer 5:目标未知时先运行 `context --locate`,随后用完整最小路径集合重新编译 targeted Context,并报告 item IDs、scopeCoverage、required/conditional read targets、provenance-only sources 与 gaps。既有 renderer 1/2/3/4 仍可读取但会标记 stale,只有显式受管 republish 才升级。
357
357
 
358
358
  使用相同 output 的 `remove-entry` 只移除可信受管区域。计划与 preview 都不含 `--write`,仍需人对精确路径授权。
359
359
 
package/UPGRADING.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # 升级说明
2
2
 
3
+ ## `1.8.0 / 1.9.0 → 1.9.1`
4
+
5
+ `1.9.1` 是对未发布 `1.9.0` Context 消费语义的补丁:read target 改为按规范化 path 唯一聚合,同路径多 JSON Pointer 完整保留,Context Bundle 与 Coverage Audit 共用一份严格 coverage profile parser/selector。Context Bundle schema 1、Coverage Audit schema 2、Contract schema 3、capabilities / Exchange Protocol 9 和 AI Entry renderer 5 均不升级。
6
+
7
+ 从已发布 `1.8.0` 或本地 `1.9.0` 进入 `1.9.1` 均是 `package-only`;不会自动迁移目标项目 Contract。两个真实项目曾在同一冻结源码候选上完成只读 Host 复验;目标项目实际安装本包并执行任务仍需各自授权与核验。
8
+
9
+ ## `1.8.0 → 1.9.0`
10
+
11
+ `1.9.0` 增加 Context Bundle schema 1、`context --locate`、稳定多路径 targeted Context、Contract schema 3 的可选消费职责与受管区域外摘要、Coverage Audit schema 2、Initialization Instruction schema 2、capabilities / Exchange Protocol 9 和 AI Entry renderer 5。Contract schema 1/2 继续只读兼容;只有显式使用 `consumption` 或 `digestMode` 的治理写入才升级为 schema 3。短生命周期 Context/Coverage/Instruction 工件应重新生成,AI Entry 需要显式 republish;不自动改写 store 或人工入口。
12
+
3
13
  ## `1.7.0 → 1.8.0`
4
14
 
5
15
  `1.8.0` 新增只读 `instructions` 和唯一包内规范 `docs/AI-PROJECT-INITIALIZATION.md`;capabilities / Exchange Protocol 升至 8,新增 initialization-instruction schema 1;project-status 升至 schema 2,以 `contractReadiness` 独立区分 `not-initialized`、`contract-incomplete` 与 `contract-ready`;AI Entry 升至 renderer 4,clean 状态也必须先运行 task/path context 并消费实际 Contract。
@@ -2,7 +2,7 @@
2
2
 
3
3
  > 权威说明:本文是支持性设计文档;当前唯一规范真源是 [00-PRODUCT-CONSTITUTION.md](./00-PRODUCT-CONSTITUTION.md)。
4
4
 
5
- 状态:`frontend-project-context@1.7.0` 已发布到 public npm,registry 工件逐字节匹配并完成全新项目回装初始化;195/195、真实 PC 初始化与 A-130 有界 Host/Provider 终验均通过
5
+ 状态:本文记录安装与分发原则及历史发布证据;当前版本与发布事实以 `package.json` 和 `PROJECT_STATE.json` 为准。
6
6
  适用项目:`dtg-frontend-delivery-agent`
7
7
  本文记录产品如何交付、安装、共享、升级和验证;它不自行授权打包、registry、Git 或发布操作。
8
8
 
@@ -43,10 +43,10 @@ CI 安装项目锁定的依赖版本并执行只读检查。CI 不依赖机器
43
43
  持久初始化前,先把精确版本安装为项目开发依赖:
44
44
 
45
45
  ```bash
46
- npm install --save-dev frontend-project-context@1.8.0
46
+ npm install --save-dev frontend-project-context@1.9.1
47
47
  ```
48
48
 
49
- 包名冻结为 `frontend-project-context`,可执行文件名为 `project-context`。安装必须先于任何持久初始化写入,使 discovery 登记的 `package.json` digest 已包含正式依赖,避免补装工具后立即产生 `source-changed`。`1.8.0` 已通过本地 O-01 至 O-12、完整回归与隔离真实项目的无历史 Host 发布阻断验收。
49
+ 包名冻结为 `frontend-project-context`,可执行文件名为 `project-context`。安装必须先于任何持久初始化写入,使 discovery 登记的 `package.json` digest 已包含正式依赖,避免补装工具后立即产生 `source-changed`。`1.9.1` 的实现门为 HC-01 至 HC-14、TC-01 至 TC-16 和全部回归;此前两个真实项目的只读 Host 复验使用同一冻结源码候选,目标项目安装发布包及运行具体需求需在各自窗口另行核验。
50
50
 
51
51
  选择项目内安装而不是全局安装,原因是:
52
52
 
@@ -281,3 +281,9 @@ IDE 插件可以在未来提供状态提示、冲突解释和可视化配置,
281
281
  6. check 无 findings,status 为 `clean/ready-for-task`,正常中文任务 context 成功生成。
282
282
 
283
283
  发布工件、Git 与回装证据全部闭合,本次 release 权限已经消费。
284
+
285
+ ## 19. `1.8.0` Real Project Onboarding Closure 正式发布
286
+
287
+ `frontend-project-context@1.8.0` 于 `2026-09-15T09:41:29.644Z` 由 `fushanyx1` 发布到官方 public npm,`latest` 指向 `1.8.0`。发布包包含 104 个文件,压缩大小 378437 bytes、解包大小 1352711 bytes;SHA-1 为 `0146a54dd7b0fab80aa877efd5d09056eacede01`,SHA-256 为 `0153d84761e13c6c7b4d84e66bc802402db7cea71c50ff387374cc57adf56a5b`,integrity 为 `sha512-6EoGqyM2YucdgN49l/3Pm9Gid7zd6mmtHr9pMFb2lnxHiN7V/VVp6tJJiPPQ1SKNIPD1C46wzoGGjvb2HFYmag==`。
288
+
289
+ 官方 registry 重下载包与冻结候选逐字节一致。全新消费者从该包离线安装后通过 package version、help、capabilities schema 8、uninitialized status 和唯一初始化指令 digest 冒烟。实现前置门为 O-01 至 O-12 与完整回归 207/207,真实 Host 前置门已在真实项目隔离副本通过。最终授权只完成官方 public npm 发布、registry 核验和本地事实归档;没有继续推送私有 Git 远端,后续发布仍需重新授权。
@@ -130,3 +130,17 @@ registry/可见性决策、发布者认证、A-39/pack、release commit、`v1.0.
130
130
  7. 从 registry 重新下载的 tarball 与候选逐字节一致,随后在全新目录从 registry 安装,version/help/capabilities/status/init/publish-entry/clean-check 全部通过。
131
131
 
132
132
  该授权不包含真实目标项目升级、Phase D 其余适配器、Provider/Agent Runtime、自动批准或新产品能力。本次实现与发布授权均已消耗。
133
+
134
+ ## 13. `1.8.0` Real Project Onboarding Closure 正式发布
135
+
136
+ 用户于 `2026-09-15` 在 O-01 至 O-12、207/207 本地回归和隔离真实项目无历史 Host 验收通过后,明确授权 `1.8.0` 发布到官方 public npm。冻结候选对应本地 release commit `5f997106d195506afcb6a991400045e973365548` 与本地 annotated tag `v1.8.0`;最终 public-registry-only 范围未继续推送私有 Git 远端。
137
+
138
+ 发布验证记录:
139
+
140
+ 1. tarball 包含 104 个文件,压缩大小 378437 bytes、解包大小 1352711 bytes,不包含测试、自托管 `.project-context/`、`PROJECT_STATE.json`、`RTK.md` 或 tarball;
141
+ 2. SHA-1 为 `0146a54dd7b0fab80aa877efd5d09056eacede01`,SHA-256 为 `0153d84761e13c6c7b4d84e66bc802402db7cea71c50ff387374cc57adf56a5b`,integrity 为 `sha512-6EoGqyM2YucdgN49l/3Pm9Gid7zd6mmtHr9pMFb2lnxHiN7V/VVp6tJJiPPQ1SKNIPD1C46wzoGGjvb2HFYmag==`;
142
+ 3. `fushanyx1` 于 `2026-09-15T09:41:29.644Z` 发布 `frontend-project-context@1.8.0`,官方 registry 的 `latest` 指向该版本;
143
+ 4. registry 重下载 tarball 与冻结候选逐字节一致;
144
+ 5. 全新消费者离线安装后通过 package version、help、capabilities schema / Exchange Protocol 8、uninitialized status 与初始化指令 digest 冒烟。
145
+
146
+ 本次发布与核验授权已经消费。Provider、A-144、Sidecar、真实目标写入、业务代码修改、私有 Git 远端推送和后续版本发布仍需分别授权。
@@ -532,3 +532,13 @@ renderer 3 的 clean 分支原文语义是“继续遵守本文件其余仓库
532
532
  - fresh Host 全程留在 targetRoot,未继承初始化讨论,未写文件,未执行 Git、网络、Provider、构建、安装、发布或业务代码修改。
533
533
 
534
534
  据此,第 9.2 节真实 Host 发布阻断验收通过。该授权已经消费;用户已于同日另行授权 `1.8.0` 发布,发布结果将在完成后继续归档。Provider、A-144、Sidecar、真实目标写入与业务代码修改继续后置。
535
+
536
+ ## 15. `1.8.0` public npm 发布事实归档
537
+
538
+ `2026-09-15T09:41:29.644Z`,`fushanyx1` 将 `frontend-project-context@1.8.0` 发布到官方 `https://registry.npmjs.org/`,访问级别为 public,`latest` 已指向 `1.8.0`。本地 release commit 为 `5f997106d195506afcb6a991400045e973365548`,本地 annotated tag 为 `v1.8.0`;最终 public-registry-only 范围内没有继续推送私有 Git 远端。
539
+
540
+ 冻结发布包共 104 个文件,压缩大小 378437 bytes、解包大小 1352711 bytes;SHA-1 为 `0146a54dd7b0fab80aa877efd5d09056eacede01`,SHA-256 为 `0153d84761e13c6c7b4d84e66bc802402db7cea71c50ff387374cc57adf56a5b`,integrity 为 `sha512-6EoGqyM2YucdgN49l/3Pm9Gid7zd6mmtHr9pMFb2lnxHiN7V/VVp6tJJiPPQ1SKNIPD1C46wzoGGjvb2HFYmag==`。从官方 registry 重新下载的 tarball 与冻结候选 `cmp` 逐字节一致。
541
+
542
+ 全新临时消费者只安装 registry 下载包,并以离线 CLI 完成以下冒烟:安装版本为 `1.8.0`;help 可用;capabilities schema / Exchange Protocol 为 8;status 正确报告 `uninitialized`;唯一初始化指令 ID/version/digest 为 `ai-project-initialization` / `1` / `sha256:8ec3bbf0202c3893514325db3f48d23adbcf18d7668b9731ac4f10e2a3be4d9e`。CLI 不提供顶层 `--version`,因此版本由已安装 package metadata 与 capabilities 双重确认。
543
+
544
+ 至此,本地 O-01 至 O-12、207/207 回归、隔离真实项目完整初始化、无历史 Host 接管、官方 public npm 发布、registry 逐字节复验和新消费者冒烟全部闭合。发布授权已经消费;Provider、A-144、Sidecar、真实目标写入、业务代码修改、私有 Git 远端推送和任何后续发布均未由本归档授权。
@@ -0,0 +1,228 @@
1
+ # 1.8.0 真实项目初始化与上下文观察记录
2
+
3
+ > 状态:`observation-only / discussion-only / draft`
4
+ >
5
+ > 日期:`2026-09-16`
6
+ >
7
+ > 目标项目:`/Users/fushan/开发/tmc/dtg-tmc-pc`
8
+ >
9
+ > 目标分支:`dev_agent20160904`
10
+ >
11
+ > 安装版本:`frontend-project-context@1.8.0`
12
+
13
+ ## 1. 记录目的与边界
14
+
15
+ 本文只归档 `frontend-project-context@1.8.0` 在真实项目中的正式初始化过程、任务 Context 实测和新 Host 审查结果,供后续集中整理问题时使用。
16
+
17
+ 本文不是产品设计、路线图、缺陷裁定、Project Contract、实现授权、发布授权或真实项目业务代码修改授权。文中“已确认”“观察风险”“待真实任务验证”必须保持区分;不得因为单次真实项目现象直接扩大 discovery、修改内核或形成新版本实现。
18
+
19
+ 本轮观察者不替代真实 Host 执行初始化,不修改目标项目业务代码,不提交或推送任何仓库。
20
+
21
+ ## 2. 正式初始化结果
22
+
23
+ 真实 Host 严格使用目标项目本地安装的 `frontend-project-context@1.8.0` 和包内唯一指令 `ai-project-initialization@1` 执行初始化。
24
+
25
+ 初始化指令摘要:
26
+
27
+ ```text
28
+ sha256:8ec3bbf0202c3893514325db3f48d23adbcf18d7668b9731ac4f10e2a3be4d9e
29
+ ```
30
+
31
+ 人工集中审查绑定:
32
+
33
+ - 12 个来源;
34
+ - 16 个 Contract item;
35
+ - proposal 摘要 `sha256:5fa3c7a974adae911fe448505a765fce4d64e80f6908c34eaccc104908466e36`;
36
+ - `AGENTS.md` 人工区域不修改;
37
+ - 只追加 renderer 4 受管 AI Entry;
38
+ - reviewer 为 `fushan`。
39
+
40
+ 机械应用和 Phase E 完成后的结果:
41
+
42
+ - `health=clean`;
43
+ - `contractReadiness=contract-ready`;
44
+ - `check` 无 findings;
45
+ - AI Entry renderer 4,状态 `current`;
46
+ - 12 个 active source;
47
+ - 16 个 approved item;
48
+ - Contract 摘要 `sha256:144eb00d0a5ef1c6f6c531ca3147d179d500b6ecedd6008adf4e62ba1dc96fd1`;
49
+ - `setup.proposal.json` 与 `initialization.proposal.json` 已删除;
50
+ - 无本轮 Action Plan、Review Bundle、receipt、日志或初始化缓存残留;
51
+ - 未修改业务代码。
52
+
53
+ 代表性 Context 验证覆盖 project、`src` path-prefix、router/http/store/build file scope,文件级 sibling isolation 成立。
54
+
55
+ ## 3. 生成文件的实际职责
56
+
57
+ | 文件 | 本轮确认的职责 |
58
+ | --- | --- |
59
+ | `.project-context/contract.json` | 保存人工批准的长期事实、规则、引用和验证描述,是 Context Bundle 的语义来源 |
60
+ | `.project-context/sources.lock.json` | 锁定来源摘要,用于发现来源漂移 |
61
+ | `.project-context/projections.lock.json` | 记录 `AGENTS.md` 受管区域所有权和 renderer 状态 |
62
+ | `AGENTS.md` 受管区域 | 让新 Host 先检查 Project Context 状态并按目标路径编译任务 Context |
63
+
64
+ 三份 store 和 AI Entry 共同建立治理、来源、作用域、所有权和漂移检查闭环;它们不自动形成组件调用图、接口字段语义或业务任务实现知识。
65
+
66
+ ## 4. 普通 Vue 任务 Context 实测
67
+
68
+ 本轮对以下两个不同目标和任务执行了实际 Context 编译:
69
+
70
+ 1. `src/views/flight/list/index.vue`:修改航班列表页面的行李信息展示;
71
+ 2. `src/components/flight/non-whitelist-confirm.vue`:调整非白名单航班确认弹窗的行李信息展示。
72
+
73
+ 两份 Bundle 除任务文字和目标路径外,命中内容基本相同:
74
+
75
+ - 项目技术栈;
76
+ - 可用 scripts;
77
+ - 授权边界;
78
+ - 格式化与提交钩子;
79
+ - 工作流选择;
80
+ - 用户工作区保护;
81
+ - `src` 级国际化规则;
82
+ - `src` 级源码复用原则;
83
+ - 项目入口与 OpenSpec 引用;
84
+ - 风险验证描述。
85
+
86
+ 两份 Bundle 均未直接提供:
87
+
88
+ - Vue 组件 props、events 和实际数据结构;
89
+ - 调用方与被调用方;
90
+ - 对应接口、字段映射和请求链路;
91
+ - 行李展示的稳定业务规则;
92
+ - 往返、多程、国内、国际等业务差异;
93
+ - 可直接复用的相邻实现;
94
+ - 本次任务的精确验证路径。
95
+
96
+ 因此,当前 Contract 对普通 Vue 文件的新增价值主要是项目治理、安全边界、通用开发规则和来源可追溯性;具体功能实现仍需要 Host 动态调查目标文件、调用方、接口和相邻实现。
97
+
98
+ ## 5. 已确认问题
99
+
100
+ ### O-01 普通业务文件的 Context 区分度不足
101
+
102
+ 两个不同机票 Vue 目标实际获得了近似相同的通用 Bundle。当前 scope compiler 工作正常,但 Contract 没有提供机票域或组件级稳定语义,因此不能仅凭 Bundle 明显提高具体业务修改的准确度。
103
+
104
+ 这不等于应该把所有业务源码注册为长期真源。后续需要通过真实任务判断哪些稳定业务边界值得进入 Contract,哪些应继续由 Host 动态调查。
105
+
106
+ ### O-02 未知目标路径时存在启动歧义
107
+
108
+ AI Entry 要求根据真实任务确定路径后编译 Context;仓库人工规则又要求先全仓定位。对于只有现象、尚不知道文件位置的任务,Host 可能在“先定位源码”和“先编译精确 Context”之间发生循环。
109
+
110
+ 候选收口方向是粗粒度定位 Context 与精确多路径 Context 两阶段,但本文不冻结具体协议。
111
+
112
+ ### O-03 单路径示例不足以表达多文件任务
113
+
114
+ CLI 可以表达多个目标路径,但 AI Entry 示例只展示一个 `<RELATIVE_PATH>`。真实任务同时涉及页面、组件、API、store、router 或构建文件时,只传主文件会遗漏其他文件的精确 scope policy。
115
+
116
+ ### O-04 `read targets` 要求缺少结构化输出支持
117
+
118
+ AI Entry 要求 Host 报告必要 read targets;实际 `context --json` 只返回一个 Markdown `content` 字段,Bundle 中只有 Source index,没有结构化区分:
119
+
120
+ - required read targets;
121
+ - conditional read targets;
122
+ - provenance-only sources;
123
+ - 已被 Contract statement 充分替代的来源。
124
+
125
+ Source index 不能直接等同于全部必读文件,否则普通 Vue 任务会重新读取 `vue.config.js`、`.husky/pre-commit`、`openspec/config.yaml` 等不一定相关的来源。
126
+
127
+ ### O-05 `AGENTS.md` 与 Contract 重复较多
128
+
129
+ 当前人工 `AGENTS.md` 已包含技术栈、目录、命令、格式、路由、HTTP、Vuex、国际化、构建和授权规则;Context Bundle 又重新输出其中一部分。
130
+
131
+ 实际链路可能变成:
132
+
133
+ ```text
134
+ 自动读取完整 AGENTS
135
+ → 编译 Context
136
+ → 再收到 AGENTS 规则摘要
137
+ → Source index 再次指向 AGENTS/docs
138
+ ```
139
+
140
+ 这降低了最小读取和按 scope 分发的增量价值。Contract 语义覆盖充分以前,不应直接删除 AGENTS 人工规则。
141
+
142
+ ### O-06 `source.entry` 将人工真源与受管投影绑定在同一摘要中
143
+
144
+ 多个 Contract item 使用整个 `AGENTS.md` 作为 `source.entry`,而该文件同时包含 Project Context 自己维护的 marker 区。未来 renderer 升级或 AI Entry 文案变化可能造成产品自身引起的 source drift,并牵连并未变化的人工事实。
145
+
146
+ 可能方向包括只摘要人工区域或把长期规则迁入独立人工真源;本文不选择实现方案。
147
+
148
+ ### O-07 关键域处置没有形成可供后续 Host 查询的持久 coverage 结论
149
+
150
+ 初始化集中审查曾逐项说明关键开发域已纳入、排除或动态调查;但后续 `coverage-audit` 仍显示 `registrationCoverage=not-declared`,具体排除和动态调查结论没有以清晰持久结构提供给新 Host。
151
+
152
+ `contract-ready` 当前只能证明 Contract 结构、来源、审批和作用域编译有效,不能被解释为所有业务语义覆盖完整。
153
+
154
+ ### O-08 产品能力边界与 Host 开发权限的交接不够明确
155
+
156
+ `status` 中的 `businessCodeWrites=false` 和 `taskExecution=false` 表示 Project Context 产品自身不执行开发任务;新 Host 可能误解为当前开发请求也禁止修改代码。AI Entry 尚未明确说明 Context 编译完成后如何回到人工规则和当前用户请求判断 Host 的任务权限。
157
+
158
+ ## 6. 观察风险,尚未裁定为产品缺陷
159
+
160
+ ### R-01 `attention` 可能抢占无关真实任务
161
+
162
+ AI Entry 要求在 `attention` 时执行 `sync` 返回的维护工作单元,但没有在入口中明确区分与当前目标相关和无关的漂移。需要真实分支和日常开发观察后再判断是否会阻断无关任务。
163
+
164
+ ### R-02 宿主的外部 memory 仍可能进入推理链
165
+
166
+ 新的审查 Host 在读取当前项目前访问了 `/Users/fushan/.codex/memories/MEMORY.md`。因此该窗口不能作为仅凭初始化后目标项目完成接管的无历史证明。
167
+
168
+ 这首先属于 Host/平台偏离和外部条件:Project Context 可以声明外部记忆不是项目真源,但未必能阻止更高优先级的平台机制读取它。后续验收必须显式区分“读取过外部 memory”和“是否把外部 memory 当成项目事实”。
169
+
170
+ ### R-03 新 Host 最终报告存在 item 数量误差
171
+
172
+ 新 Host 报告当前 Contract 有 14 个 approved item;实际为 16 个。可能遗漏了两个 reference item:
173
+
174
+ - `reference.openspec-workflow`;
175
+ - `reference.project-guidance`。
176
+
177
+ 该问题属于 Host 报告质量,不直接证明 Contract 错误。
178
+
179
+ ## 7. 当前合理且应保留的能力
180
+
181
+ - 项目本地精确版本和 `npm exec --offline` 阻止隐式版本漂移;
182
+ - 人工 Project Contract、稳定 ID、来源和显式审批成立;
183
+ - AI Entry 只拥有 marker 区,人工区域所有权清晰;
184
+ - `status`、`sync` 和 `context` 默认只读;
185
+ - Contract、source lock、projection lock 当前一致;
186
+ - 文件级 scope 与 sibling isolation 实际生效;
187
+ - router、HTTP、store、build policy 不会污染普通业务页;
188
+ - Contract 不自动扩张业务代码、提交、推送、发布或外部副作用权限;
189
+ - 模板 README、生成物、历史任务实例和虚构测试能力没有被提升为长期真相。
190
+
191
+ ## 8. 尚不能得出的结论
192
+
193
+ 本轮不能证明:
194
+
195
+ - 当前 Contract 已包含所有业务语义;
196
+ - 普通 Vue 任务仅靠 Context Bundle 就能完成正确修改;
197
+ - 每个 Source index 都应由 Host 读取;
198
+ - 外部 memory 已被 Project Context 隔离;
199
+ - `attention` 一定会阻断无关开发;
200
+ - 任一观察项已经获得产品修复、设计或下一版本授权。
201
+
202
+ ## 9. 后续真实开发的观察清单
203
+
204
+ 下一次在同一分支使用无历史 Host 执行真实业务需求时,重点记录:
205
+
206
+ 1. Host 是否只从目标项目入口发现并消费 Project Context;
207
+ 2. 目标路径未知时如何完成首次定位;
208
+ 3. 是否在识别多个受影响文件后重新编译多路径 Context;
209
+ 4. 实际报告的 item IDs、scope 和 read targets 是否准确;
210
+ 5. Source index 是否引发不必要的重复读取;
211
+ 6. 通用 Contract 是否减少错误命令、越权、全仓格式化或危险构建;
212
+ 7. 缺少业务域语义是否导致漏读调用方、接口或相邻实现;
213
+ 8. Context 不足时 Host 是否明确报告 gap,而不是猜测;
214
+ 9. 真实修改完成后 Project Context 是否仍为 `clean`;
215
+ 10. 哪些缺口属于产品协议、目标项目 Contract 数据、Host 偏离或外部平台条件。
216
+
217
+ ## 10. 后续整合原则
218
+
219
+ 在真实开发链路完成前,保持目标项目安装的 `1.8.0` 不变,不边走边修改产品或目标项目内部 store。观察项应先按以下类型归类:
220
+
221
+ - 产品协议缺口;
222
+ - 目标项目 Contract 数据缺口;
223
+ - AI Entry/消费者适配问题;
224
+ - Host 行为偏离;
225
+ - 外部平台条件;
226
+ - 尚未证实的风险。
227
+
228
+ 完成至少一个真实业务任务后,再基于本记录和新证据集中决定哪些问题需要进入设计。任何设计、Contract 修订、产品实现、Git 操作和发布仍需单独授权。