frontend-project-context 1.7.0 → 1.8.0

package/docs/USER-AND-AI-OPERATION-MANUAL.md

@@ -1,6 +1,6 @@
 # Frontend Project Context 操作手册
 
-> 适用版本：`frontend-project-context@1.7.0` 发布候选
+> 适用版本：`frontend-project-context@1.8.0` 本地实现
 >
 > 适用对象：项目维护者、开发者、使用 Codex / Claude / Cursor / 其他 Coding Agent 的团队，以及集成该 CLI 的 AI Host Agent。
 >
@@ -101,7 +101,7 @@ AI 可以提取事实、整理文字、去重、建议 scope/override、生成 p
 固定为项目开发依赖，使本地与 CI 使用同一版本：
 
 ```bash
-npm install --save-dev frontend-project-context@1.7.0
+npm install --save-dev frontend-project-context@1.8.0
 ```
 
 建议在 `package.json` 中提供稳定入口：
@@ -121,15 +121,16 @@ npm install --save-dev frontend-project-context@1.7.0
 
 ```bash
 npm exec --offline -- project-context --help
+npm exec --offline -- project-context instructions --project . --prompt
 npm exec --offline -- project-context capabilities --project . --json
 npm exec --offline -- project-context status --project . --json
 ```
 
 所有正式命令都通过 `npm exec --offline -- project-context` 或上面的项目脚本调用。`--offline` 会在本地依赖缺失时失败封闭，不能退回 registry 下载无关的同名 `project-context` 包。持久初始化必须发生在精确版本安装之后，避免后续补装依赖改变已登记的 `package.json` source digest。
 
-`capabilities` 在项目未初始化时也可用，适合 AI Host 先查询当前包版本、schema、支持的 action kind 和永久边界。
+`instructions` 和 `capabilities` 在项目未初始化时也可用。初始化的唯一规范正文是 [AI-PROJECT-INITIALIZATION.md](./AI-PROJECT-INITIALIZATION.md)；本手册只引用它，不另行定义执行顺序。
 
-`1.7.0` 默认以中文生成 AI Entry 和 discovery 候选的 `statement`，便于中文团队直接审查项目语义；稳定 ID、subject、kind、CLI 命令、JSON 字段、枚举和 marker 继续使用英文。AI Entry renderer 3 同时固定离线项目本地 CLI 入口；既有 renderer 1/2 不会被静默覆盖，升级后会报告 stale，必须先预览并获得明确写入授权，再 republish 为 renderer 3 中文入口。
+`1.8.0` 的 AI Entry renderer 4 固定离线项目本地 CLI 入口，并要求 clean 状态的真实任务先运行 task/path `context`、消费实际命中的 item IDs、scope 与 read targets。既有 renderer 1/2/3 不会被静默覆盖，升级后会报告 stale，必须先预览并获得明确写入授权再 republish。
 
 ### 4.3 全新初始化不是普通升级
 
@@ -143,9 +144,11 @@ npm exec --offline -- project-context status --project . --json
 
 工具没有自动 reset 命令，也不会把删除 store、翻译批准规则或接受 source drift 伪装成普通升级。
 
-## 5. 首次接入 SOP
+## 5. 唯一初始化指令与底层原语参考
 
-### 第 1 步：只读预览初始化结果
+首次接入只遵循 [AI-PROJECT-INITIALIZATION.md](./AI-PROJECT-INITIALIZATION.md)。下面保留的是单个 CLI 原语的参数参考，不是可由 Host 自行拼装的第二套初始化流程；语义审查、执行顺序、临时工件清理和完成门均以包内唯一指令为准。
+
+### 底层参考：setup 只读 preview
 
 ```bash
 npm exec --offline -- project-context setup \
@@ -165,7 +168,7 @@ npm exec --offline -- project-context setup \
 
 此时项目文件应保持不变。
 
-### 第 2 步：明确同意创建 store 和 proposal
+### 底层参考：setup 的显式 bootstrap 写入
 
 确认项目 ID、名称和 proposal 路径后执行：
 
@@ -181,7 +184,7 @@ npm exec --offline -- project-context setup \
 
 `setup --write` 只代表允许创建三个 store 和一份 create-only proposal，**不代表批准 proposal，也不代表允许生成 AGENTS/Ruler 投影**。
 
-### 第 3 步：AI 只按 work unit 渐进读取
+### 底层参考：读取 work unit
 
 AI 应：
 
@@ -192,7 +195,7 @@ AI 应：
 5. 需要额外来源时，先说明原因并把它列为 source 候选；
 6. 不以“代码存在”推导出“团队长期 policy”。
 
-### 第 4 步：补充来源和候选合同项
+### 底层参考：补充来源和候选合同项
 
 支持的来源类型：
 
@@ -241,7 +244,7 @@ scope 只有：
 - `path-prefix`：指定目录及其后代；
 - `file`：单个文件。
 
-### 第 5 步：人工集中审查
+### 底层参考：审查视图字段
 
 AI 必须先展示：
 
@@ -272,7 +275,7 @@ AI 必须先展示：
 应该没问题。
 ```
 
-### 第 6 步：批准精确 ID
+### 底层参考：批准精确 ID
 
 ```bash
 npm exec --offline -- project-context approve \
@@ -284,7 +287,7 @@ npm exec --offline -- project-context approve \
 
 先看 preview，确认无误后才加 `--write`。一份 proposal 中未被 `--ids` 点名的 item 不会自动获得批准。
 
-### 第 7 步：生成上下文和投影
+### 底层参考：生成上下文和投影
 
 为目标路径生成临时上下文：
 
@@ -319,7 +322,7 @@ npm exec --offline -- project-context publish \
 
 如果根 `AGENTS.md` 由人工或其他工具管理，不要覆盖。可以改为在无冲突的子目录生成受管 `AGENTS.md`，或使用 `.ruler/` 投影。
 
-### 第 8 步：检查并提交
+### 底层参考：检查结果
 
 ```bash
 npm exec --offline -- project-context check --project .
@@ -809,6 +812,7 @@ Receipt 只记录阶段证据，不代表人已验收、合并或批准长期规
 
 | 命令 | 用途 | 是否可写 |
 | --- | --- | --- |
+| `instructions` | 返回包内唯一初始化指令、digest 与 resolved targetRoot | 否 |
 | `capabilities` | 查询版本、schema、action kind 和永久边界 | 否 |
 | `setup` | 聚合安全初始化、保守 discovery 和 Assist Bundle | 仅显式 `--write` |
 | `init` | 创建空的三个 store | 仅显式 `--write` |

package/examples/README.md

@@ -2,10 +2,10 @@
 
 包实际发布后，把 [package.json](./package.json) 中的脚本和 devDependency 合并到项目，并把 [project-context-check.yml](./project-context-check.yml) 复制到 `.github/workflows/project-context-check.yml`。
 
-维护者首次初始化：
+维护者首次初始化前先读取包内唯一指令；后续命令由该指令和一次集中语义确认驱动：
 
 ```bash
-npm run context:setup -- --id my-project --name "My Project" --write --json
+npm exec --offline -- project-context instructions --project . --prompt
 ```
 
 为完全新窗口写入稳定入口并查询治理健康：

package/examples/package.json

@@ -14,6 +14,6 @@
     "context:upgrade-check": "project-context upgrade-check --project ."
   },
   "devDependencies": {
-    "frontend-project-context": "1.7.0"
+    "frontend-project-context": "1.8.0"
   }
 }

package/migration-manifest.json

@@ -23,14 +23,16 @@
   "consumerChanges": {
     "actionPlan": {"reason": "Action Plan schema 1 and 2 readers remain compatible; writers remain schema 2.", "state": "preserve"},
     "adaptiveContextBundle": {"reason": "Schema 1 Adaptive Context Bundles lack task lineage and strict withheld-delivery semantics; regenerate as schema 2.", "state": "regenerate"},
-    "capabilities": {"reason": "Consumers must branch on capabilities schema 7 and exchange protocol 7.", "state": "regenerate"},
+    "capabilities": {"reason": "Consumers must branch on capabilities schema 8 and exchange protocol 8.", "state": "regenerate"},
     "contextQuery": {"reason": "Context Query schema 1 is short-lived and must use current snapshots.", "state": "regenerate"},
     "coverageAudit": {"reason": "Coverage Audit schema 1 is derived from the current Contract and filesystem evidence.", "state": "regenerate"},
     "evidenceBundle": {"reason": "Evidence Bundle schema 1 remains readable and separate from upgrade results.", "state": "preserve"},
     "evidenceInput": {"reason": "Evidence Input schema 1 remains readable and is never rewritten by upgrade.", "state": "preserve"},
-    "exchange": {"reason": "Exchange protocol capability metadata changes to version 7.", "state": "regenerate"},
+    "exchange": {"reason": "Exchange protocol capability metadata changes to version 8.", "state": "regenerate"},
     "hostPromotionEvidence": {"reason": "Host Promotion Evidence is short-lived and remains bound to exact code, artifact, and Project Context snapshots.", "state": "regenerate"},
+    "initializationInstruction": {"reason": "Schema 1 is package-derived from the exact installed instruction and resolved target root.", "state": "regenerate"},
     "integrationReviewBundle": {"reason": "Short-lived integration review bundles must be regenerated against current baselines.", "state": "regenerate"},
+    "projectStatus": {"reason": "Schema 2 separates governance health from Contract readiness and task-context routing.", "state": "regenerate"},
     "reviewBundle": {"reason": "Review Bundle schema 2 remains readable but short-lived reviews must be regenerated when their baselines change.", "state": "regenerate"},
     "routingIndex": {"reason": "Routing Index schema 1 is disposable derived data and must be rebuilt from the current Contract.", "state": "invalidate"},
     "stageContextBundle": {"reason": "Short-lived stage context bundles must be regenerated against current receipts.", "state": "regenerate"},
@@ -40,8 +42,8 @@
     ,"truthReconciliationReviewBundle": {"reason": "Schema 1 reviews lack finding digests and machine-verifiable resolution outcomes; recompute as schema 2.", "state": "regenerate"}
   },
   "externalEffects": {"automaticUpgrade": false, "businessCode": false, "git": false, "network": false, "packageManager": false, "projectTests": false},
-  "manifestDigest": "sha256:34b1b611ebf31471f2e136eb3f84ad627df612998d0358654e7cdde4713de777",
-  "package": {"name": "frontend-project-context", "version": "1.7.0"},
+  "manifestDigest": "sha256:be29e7ee930d34533380e6d2408f614fc7406ad3491a1657776d904bcc5ebacf",
+  "package": {"name": "frontend-project-context", "version": "1.8.0"},
   "paths": [
     {
       "acceptance": ["project-context-clean", "target-renderers-current"],
@@ -74,6 +76,14 @@
       "migrationIds": ["upgrade.republish-ai-entry.v1"],
       "requiresHumanReview": false,
       "rollbackClass": "package-only"
+    },
+    {
+      "acceptance": ["project-context-clean", "target-renderers-current"],
+      "classification": "package-only",
+      "fromVersion": "1.7.0",
+      "migrationIds": ["upgrade.republish-ai-entry.v1"],
+      "requiresHumanReview": false,
+      "rollbackClass": "package-only"
     }
   ],
   "protocols": {
@@ -83,9 +93,11 @@
     "coverageAudit": {"readable": [1], "written": 1},
     "evidenceBundle": {"readable": [1], "written": 1},
     "evidenceInput": {"readable": [1], "written": 1},
-    "exchange": {"readable": [4, 5, 6, 7], "written": 7},
+    "exchange": {"readable": [4, 5, 6, 7, 8], "written": 8},
     "hostPromotionEvidence": {"readable": [1], "written": 1},
+    "initializationInstruction": {"readable": [1], "written": 1},
     "integrationReviewBundle": {"readable": [1], "written": 1},
+    "projectStatus": {"readable": [1, 2], "written": 2},
     "reviewBundle": {"readable": [1, 2], "written": 2},
     "routingIndex": {"readable": [1, 2], "written": 2},
     "stageContextBundle": {"readable": [1], "written": 1},
@@ -95,7 +107,7 @@
     "truthReconciliationReviewBundle": {"readable": [2], "written": 2}
   },
   "renderers": {
-    "aiEntry": {"readable": [1, 2, 3], "written": 3},
+    "aiEntry": {"readable": [1, 2, 3, 4], "written": 4},
     "projection": {"readable": [1, 2, 3], "written": 3}
   },
   "rollback": {"automatic": false, "defaultClass": "package-only", "externalRestoreRequired": true},
@@ -106,5 +118,5 @@
     "proposal": {"readable": [1], "written": [1]},
     "sourceLock": {"readable": [1], "written": [1]}
   },
-  "upgradeFrom": ["1.3.1", "1.4.0", "1.5.0", "1.6.0"]
+  "upgradeFrom": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-project-context",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Govern, compile, and verify project-local context for AI coding tools.",
   "private": false,
   "publishConfig": {
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "check": "node --check bin/project-context.mjs && npm test",
-    "test": "node --test test/project-context/acceptance.test.mjs test/project-context/adaptive-context.test.mjs test/project-context/adaptive-delivery-v2.test.mjs test/project-context/assist.test.mjs test/project-context/cli.test.mjs test/project-context/dashboard.test.mjs test/project-context/evidence.test.mjs test/project-context/exchange.test.mjs test/project-context/maintenance.test.mjs test/project-context/source-lifecycle.test.mjs test/project-context/task-context.test.mjs test/project-context/takeover.test.mjs test/project-context/truth-reconciliation.test.mjs test/project-context/upgrade.test.mjs test/release/acceptance.test.mjs",
+    "test": "node --test test/project-context/acceptance.test.mjs test/project-context/adaptive-context.test.mjs test/project-context/adaptive-delivery-v2.test.mjs test/project-context/assist.test.mjs test/project-context/cli.test.mjs test/project-context/dashboard.test.mjs test/project-context/evidence.test.mjs test/project-context/exchange.test.mjs test/project-context/maintenance.test.mjs test/project-context/onboarding-closure.test.mjs test/project-context/source-lifecycle.test.mjs test/project-context/task-context.test.mjs test/project-context/takeover.test.mjs test/project-context/truth-reconciliation.test.mjs test/project-context/upgrade.test.mjs test/release/acceptance.test.mjs",
     "prepack": "npm run check"
   },
   "engines": {

package/schemas/capabilities.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:frontend-project-context:schema:capabilities:7",
+  "$id": "urn:frontend-project-context:schema:capabilities:8",
   "title": "Frontend Project Context Capabilities",
   "type": "object",
   "additionalProperties": false,
@@ -12,23 +12,24 @@
     "commands",
     "actionKinds",
     "contextBudget",
+    "initializationInstruction",
     "initialization",
     "initialized",
     "project",
     "boundaries"
   ],
   "properties": {
-    "schemaVersion": { "const": 7 },
+    "schemaVersion": { "const": 8 },
     "package": {
       "type": "object",
       "additionalProperties": false,
       "required": ["name", "version"],
       "properties": {
         "name": { "const": "frontend-project-context" },
-        "version": { "const": "1.7.0" }
+        "version": { "const": "1.8.0" }
       }
     },
-    "exchangeProtocolVersion": { "const": 7 },
+    "exchangeProtocolVersion": { "const": 8 },
     "schemas": {
       "type": "object",
       "additionalProperties": false,
@@ -45,6 +46,7 @@
         "evidenceInput",
         "hostPromotionEvidence",
         "integrationReviewBundle",
+        "initializationInstruction",
         "projectionLock",
         "projectionLockReadable",
         "projectionLockWritten",
@@ -69,7 +71,7 @@
         "actionPlan": { "const": 2 },
         "adaptiveContextBundle": { "const": 2 },
         "assistBundle": { "const": 1 },
-        "capabilities": { "const": 7 },
+        "capabilities": { "const": 8 },
         "contract": { "const": 2 },
         "contextQuery": { "const": 2 },
         "coverageAudit": { "const": 1 },
@@ -78,13 +80,14 @@
         "evidenceInput": { "const": 1 },
         "hostPromotionEvidence": { "const": 1 },
         "integrationReviewBundle": { "const": 1 },
+        "initializationInstruction": { "const": 1 },
         "projectionLock": { "const": 2 },
         "projectionLockReadable": { "const": [1, 2] },
         "projectionLockWritten": { "enum": [1, 2] },
         "projectionRenderer": { "type": "integer" },
         "proposal": { "const": 1 },
-        "projectStatus": { "const": 1 },
-        "aiEntryRenderer": { "const": 3 },
+        "projectStatus": { "const": 2 },
+        "aiEntryRenderer": { "const": 4 },
         "migrationManifest": { "const": 2 },
         "migrationPlan": { "const": 1 },
         "reviewBundle": { "const": 2 },
@@ -99,7 +102,7 @@
         "upgradeResultBundle": { "const": 1 }
       }
     },
-    "commands": { "type": "array", "minItems": 1, "uniqueItems": true, "allOf": [{"contains": {"const": "upgrade-check"}}, {"contains": {"const": "upgrade-plan"}}, {"contains": {"const": "upgrade-apply"}}], "items": { "type": "string" } },
+    "commands": { "type": "array", "minItems": 1, "uniqueItems": true, "allOf": [{"contains": {"const": "instructions"}}, {"contains": {"const": "upgrade-check"}}, {"contains": {"const": "upgrade-plan"}}, {"contains": {"const": "upgrade-apply"}}], "items": { "type": "string" } },
     "actionKinds": {
       "type": "array",
       "minItems": 10,
@@ -130,6 +133,18 @@
         "callerMustProvideLimit": { "const": true }
       }
     },
+    "initializationInstruction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "packagePath", "digest", "command"],
+      "properties": {
+        "id": {"const": "ai-project-initialization"},
+        "version": {"const": 1},
+        "packagePath": {"const": "docs/AI-PROJECT-INITIALIZATION.md"},
+        "digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+        "command": {"const": "project-context instructions --project PATH [--json | --prompt]"}
+      }
+    },
     "initialization": { "enum": ["uninitialized", "partial", "initialized"] },
     "initialized": { "type": "boolean" },
     "project": {

package/schemas/evidence-bundle.schema.json

@@ -14,7 +14,7 @@
       "required": ["name", "version", "exchangeProtocolVersion"],
       "properties": {
         "name": { "const": "frontend-project-context" },
-        "version": { "const": "1.7.0" },
+        "version": { "const": "1.8.0" },
         "exchangeProtocolVersion": { "const": 6 }
       }
     },

package/schemas/initialization-instruction.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:initialization-instruction:1",
+  "title": "Frontend Project Context Initialization Instruction",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "package", "instruction", "targetRoot", "boundaries"],
+  "properties": {
+    "schemaVersion": {"const": 1},
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": {"const": "frontend-project-context"},
+        "version": {"const": "1.8.0"}
+      }
+    },
+    "instruction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "packagePath", "digest", "content"],
+      "properties": {
+        "id": {"const": "ai-project-initialization"},
+        "version": {"const": 1},
+        "packagePath": {"const": "docs/AI-PROJECT-INITIALIZATION.md"},
+        "digest": {"$ref": "#/$defs/digest"},
+        "content": {"type": "string", "minLength": 1}
+      }
+    },
+    "targetRoot": {"type": "string", "minLength": 1},
+    "boundaries": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "agentRuntime", "git", "network", "dependencyInstallation", "automaticApproval", "businessCodeWrites", "taskExecution", "stagePathBodyReads", "applyPlan", "scheduler", "daemon", "telemetry", "selfUpdate", "automaticEvidenceUpload", "packageManager", "automaticUpgrade"],
+      "properties": {
+        "provider": {"const": false},
+        "agentRuntime": {"const": false},
+        "git": {"const": false},
+        "network": {"const": false},
+        "dependencyInstallation": {"const": false},
+        "automaticApproval": {"const": false},
+        "businessCodeWrites": {"const": false},
+        "taskExecution": {"const": false},
+        "stagePathBodyReads": {"const": false},
+        "applyPlan": {"const": false},
+        "scheduler": {"const": false},
+        "daemon": {"const": false},
+        "telemetry": {"const": false},
+        "selfUpdate": {"const": false},
+        "automaticEvidenceUpload": {"const": false},
+        "packageManager": {"const": false},
+        "automaticUpgrade": {"const": false}
+      }
+    }
+  },
+  "$defs": {
+    "digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"}
+  }
+}

package/schemas/migration-manifest.schema.json

@@ -7,12 +7,12 @@
   "required": ["schemaVersion", "package", "upgradeFrom", "stores", "renderers", "protocols", "paths", "builtInMigrations", "consumerChanges", "acceptanceCommands", "rollback", "externalEffects", "manifestDigest"],
   "properties": {
     "schemaVersion": {"const": 2},
-    "package": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "frontend-project-context"}, "version": {"const": "1.7.0"}}},
-    "upgradeFrom": {"const": ["1.3.1", "1.4.0", "1.5.0", "1.6.0"]},
+    "package": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "frontend-project-context"}, "version": {"const": "1.8.0"}}},
+    "upgradeFrom": {"const": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]},
     "stores": {"type": "object", "additionalProperties": false, "required": ["contract", "projectionLock", "proposal", "sourceLock"], "properties": {"contract": {"$ref": "#/$defs/versionMatrix"}, "projectionLock": {"$ref": "#/$defs/versionMatrix"}, "proposal": {"$ref": "#/$defs/versionMatrix"}, "sourceLock": {"$ref": "#/$defs/versionMatrix"}}},
     "renderers": {"type": "object", "additionalProperties": false, "required": ["aiEntry", "projection"], "properties": {"aiEntry": {"$ref": "#/$defs/versionTarget"}, "projection": {"$ref": "#/$defs/versionTarget"}}},
     "protocols": {"type": "object", "additionalProperties": {"$ref": "#/$defs/versionTarget"}},
-    "paths": {"type": "array", "minItems": 4, "maxItems": 4, "items": {"type": "object", "additionalProperties": false, "required": ["fromVersion", "classification", "migrationIds", "requiresHumanReview", "rollbackClass", "acceptance"], "properties": {"fromVersion": {"enum": ["1.3.1", "1.4.0", "1.5.0", "1.6.0"]}, "classification": {"enum": ["package-only", "republish-ai-entry", "republish-projection", "built-in-store-migration", "invalidate-ephemeral-protocol"]}, "migrationIds": {"$ref": "#/$defs/strings"}, "requiresHumanReview": {"type": "boolean"}, "rollbackClass": {"$ref": "#/$defs/rollbackClass"}, "acceptance": {"$ref": "#/$defs/strings"}}}},
+    "paths": {"type": "array", "minItems": 5, "maxItems": 5, "items": {"type": "object", "additionalProperties": false, "required": ["fromVersion", "classification", "migrationIds", "requiresHumanReview", "rollbackClass", "acceptance"], "properties": {"fromVersion": {"enum": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]}, "classification": {"enum": ["package-only", "republish-ai-entry", "republish-projection", "built-in-store-migration", "invalidate-ephemeral-protocol"]}, "migrationIds": {"$ref": "#/$defs/strings"}, "requiresHumanReview": {"type": "boolean"}, "rollbackClass": {"$ref": "#/$defs/rollbackClass"}, "acceptance": {"$ref": "#/$defs/strings"}}}},
     "builtInMigrations": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["id", "kind", "input", "targetType", "writes", "rollbackClass", "reverseMigrationId"], "properties": {"id": {"type": "string"}, "kind": {"enum": ["package-only", "republish-ai-entry", "republish-projection", "built-in-store-migration", "invalidate-ephemeral-protocol"]}, "input": {"type": "object", "additionalProperties": false, "required": ["schemaVersions", "beforeDigestRequired"], "properties": {"schemaVersions": {"type": "array", "items": {"type": "integer", "minimum": 1}}, "beforeDigestRequired": {"type": "boolean"}}}, "targetType": {"enum": ["none", "ai-entry", "projection", "store", "ephemeral-protocol"]}, "writes": {"type": "boolean"}, "rollbackClass": {"$ref": "#/$defs/rollbackClass"}, "reverseMigrationId": {"type": ["string", "null"]}}}},
     "consumerChanges": {"type": "object", "additionalProperties": {"type": "object", "additionalProperties": false, "required": ["state", "reason"], "properties": {"state": {"enum": ["preserve", "regenerate", "invalidate"]}, "reason": {"type": "string"}}}},
     "acceptanceCommands": {"$ref": "#/$defs/strings"},

package/schemas/migration-plan.schema.json

@@ -8,8 +8,8 @@
   "properties": {
     "schemaVersion": {"const": 1},
     "kind": {"const": "target-upgrade-plan"},
-    "fromVersion": {"enum": ["1.3.1", "1.4.0", "1.5.0", "1.6.0"]},
-    "targetVersion": {"const": "1.7.0"},
+    "fromVersion": {"enum": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]},
+    "targetVersion": {"const": "1.8.0"},
     "manifestDigest": {"$ref": "#/$defs/digest"},
     "assessmentDigest": {"$ref": "#/$defs/digest"},
     "snapshots": {"anyOf": [{"type": "null"}, {"$ref": "#/$defs/snapshots"}]},

package/schemas/project-status.schema.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:frontend-project-context:schema:project-status:1",
+  "$id": "urn:frontend-project-context:schema:project-status:2",
   "title": "Frontend Project Context Project Status",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "package", "initialization", "project", "snapshots", "health", "entry", "summary", "findingCodes", "sourceIds", "itemIds", "projectionPaths", "readTargets", "workUnits", "nextActions", "boundaries"],
+  "required": ["schemaVersion", "package", "initialization", "project", "snapshots", "health", "entry", "contractReadiness", "summary", "findingCodes", "sourceIds", "itemIds", "projectionPaths", "readTargets", "workUnits", "nextActions", "boundaries"],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "package": {
       "type": "object",
       "additionalProperties": false,
@@ -36,6 +36,7 @@
         "rendererVersion": { "type": ["integer", "null"] }
       }
     },
+    "contractReadiness": {"enum": ["not-initialized", "contract-incomplete", "contract-ready"]},
     "summary": {
       "type": "object",
       "additionalProperties": false,
@@ -56,7 +57,7 @@
     "nextActions": {
       "type": "array",
       "uniqueItems": true,
-      "items": { "enum": ["run-setup-preview", "run-sync", "review-pending", "review-source-change", "review-projection", "publish-ai-entry", "resolve-conflict", "ready-for-task"] }
+      "items": { "enum": ["read-initialization-instructions", "complete-onboarding", "compile-task-context", "run-sync", "review-pending", "review-source-change", "review-projection", "publish-ai-entry", "resolve-conflict"] }
     },
     "boundaries": { "type": "object", "additionalProperties": { "const": false } }
   },

package/schemas/upgrade-assessment.schema.json

@@ -9,8 +9,8 @@
     "schemaVersion": {"const": 1},
     "kind": {"const": "upgrade-assessment"},
     "product": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"const": "frontend-project-context"}}},
-    "fromVersion": {"enum": ["1.3.1", "1.4.0", "1.5.0", "1.6.0"]},
-    "targetVersion": {"const": "1.7.0"},
+    "fromVersion": {"enum": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]},
+    "targetVersion": {"const": "1.8.0"},
     "fromVersionEvidence": {"const": "host-asserted"},
     "manifestSchemaVersion": {"const": 2},
     "manifestDigest": {"$ref": "#/$defs/digest"},

package/schemas/upgrade-result-bundle.schema.json

@@ -10,7 +10,7 @@
     "kind": {"const": "upgrade-result-bundle"},
     "product": {"type": "object", "additionalProperties": false, "required": ["name"], "properties": {"name": {"const": "frontend-project-context"}}},
     "fromVersion": {"type": "string"},
-    "targetVersion": {"const": "1.7.0"},
+    "targetVersion": {"const": "1.8.0"},
     "manifestDigest": {"$ref": "#/$defs/digest"},
     "planDigest": {"$ref": "#/$defs/digest"},
     "mode": {"enum": ["preview", "write"]},

package/src/project-context/ai-entry.mjs

@@ -6,23 +6,25 @@ import { fail } from "./errors.mjs";
 import { atomicWriteFile, atomicWriteJson, readJsonFile } from "./io.mjs";
 import { normalizeRelativePath, resolveWritableInside } from "./path-policy.mjs";
 
-export const AI_ENTRY_RENDERER_VERSION = 3;
+export const AI_ENTRY_RENDERER_VERSION = 4;
 export const AI_ENTRY_REGION_ID = "project-context-ai-entry";
 export const AI_ENTRY_START = "<!-- project-context:ai-entry:start -->";
 export const AI_ENTRY_END = "<!-- project-context:ai-entry:end -->";
 
 const ENTRY_LINES = [
   AI_ENTRY_START,
-  "<!-- project-context:ai-entry; schema-version: 1; renderer-version: 3 -->",
+  "<!-- project-context:ai-entry; schema-version: 1; renderer-version: 4 -->",
   "## Project Context 启动流程",
   "",
   "开始项目工作前，使用项目本地安装的 `frontend-project-context` CLI，不要临时下载其他版本。",
   "",
   "1. 运行 `npm exec --offline -- project-context status --project . --json`；如果本地依赖不存在，停止并报告，不要临时下载同名包。",
-  "2. 如果状态为 `partial` 或 `invalid`，停止写入并报告准确的恢复证据。",
-  "3. 如果尚未初始化，先预览 `setup`；如果已初始化但需要处理，使用 `sync` 工作单元；如果为 `clean`，继续遵守本文件其余仓库规则，并执行已获授权的用户任务。",
-  "4. 任何 plan、bundle、receipt、review 或 AI 建议都不代表人工批准。",
-  "5. 声明完成前，将 Project Context 恢复为 `clean`，否则报告准确的阻断项。",
+  "2. 如果状态为 `uninitialized`，运行 `npm exec --offline -- project-context instructions --project . --prompt`，按包内唯一指令完成完整初始化；如果为 `partial` 或 `invalid`，停止写入并报告准确的恢复证据。",
+  "3. 如果状态为 `attention`，执行 `sync` 返回的维护工作单元；不得重新运行 `setup` 覆盖已有 store。",
+  "4. 如果状态为 `clean`，根据真实任务确定项目内目标路径，并运行 `npm exec --offline -- project-context context --project . --path <RELATIVE_PATH> --task <TEXT>`。",
+  "5. 必须先消费命中的 Project Contract，报告实际 item IDs、scope 和必要 read targets；Contract 为空、目标 scope 未命中或关键上下文不足时，报告 onboarding/context gap 并停止，不能直接进入源码。",
+  "6. 任何 plan、bundle、receipt、review 或 AI 建议都不代表人工批准。",
+  "7. 声明完成前，将 Project Context 恢复为 `clean`，否则报告准确的阻断项。",
   AI_ENTRY_END,
 ];
 

package/src/project-context/capabilities.mjs

@@ -37,6 +37,11 @@ import {
   TRUTH_RECONCILIATION_INPUT_SCHEMA_VERSION,
   TRUTH_RECONCILIATION_REVIEW_BUNDLE_SCHEMA_VERSION,
 } from "./truth-reconciliation-schema.mjs";
+import {
+  INITIALIZATION_INSTRUCTION_COMMAND,
+  INITIALIZATION_INSTRUCTION_SCHEMA_VERSION,
+  readInitializationInstruction,
+} from "./initialization-instruction.mjs";
 
 function schemas(projectionLockWritten = 1) {
   return {
@@ -51,6 +56,7 @@ function schemas(projectionLockWritten = 1) {
     evidenceBundle: EVIDENCE_BUNDLE_SCHEMA_VERSION,
     evidenceInput: EVIDENCE_INPUT_SCHEMA_VERSION,
     integrationReviewBundle: INTEGRATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+    initializationInstruction: INITIALIZATION_INSTRUCTION_SCHEMA_VERSION,
     hostPromotionEvidence: HOST_PROMOTION_EVIDENCE_SCHEMA_VERSION,
     projectionLock: 2,
     projectionLockReadable: [1, 2],
@@ -96,6 +102,7 @@ export const PERMANENT_BOUNDARIES = Object.freeze({
 
 export async function buildCapabilities(root) {
   const initialization = await inspectProjectInitialization(root);
+  const instruction = await readInitializationInstruction();
   let project = null;
   let projectionLockWritten = 1;
   if (initialization.status === "initialized") {
@@ -111,6 +118,13 @@ export async function buildCapabilities(root) {
     commands: [...COMMANDS],
     actionKinds: [...ACTION_KINDS],
     contextBudget: { unit: CONTEXT_BUDGET_UNIT, modelTokens: false, callerMustProvideLimit: true },
+    initializationInstruction: {
+      id: instruction.id,
+      version: instruction.version,
+      packagePath: instruction.packagePath,
+      digest: instruction.digest,
+      command: INITIALIZATION_INSTRUCTION_COMMAND,
+    },
     initialization: initialization.status,
     initialized: initialization.status === "initialized",
     project,

package/src/project-context/cli.mjs

@@ -24,12 +24,14 @@ import { renderContextBundle } from "./renderer.mjs";
 import { buildIntegrationReviewBundleFiles, buildStageContextBundleFiles } from "./task-context.mjs";
 import { applyMigrationPlanFile, buildMigrationPlanFile, buildUpgradeAssessment } from "./upgrade.mjs";
 import { buildTruthReconciliationReviewFiles } from "./truth-reconciliation.mjs";
+import { buildInitializationInstruction, renderInitializationPrompt } from "./initialization-instruction.mjs";
 
 const HELP = `project-context — model-neutral project contract compiler
 
 Usage:
   project-context init --project PATH --id ID --name NAME [--write] [--json]
   project-context capabilities --project PATH [--json]
+  project-context instructions --project PATH [--json | --prompt]
   project-context status --project PATH [--json]
   project-context evidence --project PATH --input FILE [--json]
   project-context upgrade-check --project PATH --from-version VERSION [--json]
@@ -75,6 +77,7 @@ const BOOLEAN_FLAGS = new Set(["write", "json", "full-json", "help", "pending",
 const COMMAND_OPTIONS = new Map([
   ["init", new Set(["project", "id", "name", "write", "json", "help"])],
   ["capabilities", new Set(["project", "json", "help"])],
+  ["instructions", new Set(["project", "json", "prompt", "help"])],
   ["status", new Set(["project", "json", "help"])],
   ["evidence", new Set(["project", "input", "json", "help"])],
   ["upgrade-check", new Set(["project", "from-version", "json", "help"])],
@@ -342,6 +345,18 @@ async function runCommand(command, options) {
   if (!COMMAND_OPTIONS.has(command)) fail("command-unknown", `unknown command: ${command}`);
   rejectUnsupportedOptions(command, options, COMMAND_OPTIONS.get(command));
   const root = await resolveProjectRoot(required(options, "project"));
+  if (command === "instructions") {
+    if (options.json && options.prompt) fail("argument-conflict", "instructions accepts only one of --json or --prompt");
+    const instruction = await buildInitializationInstruction(root, PERMANENT_BOUNDARIES);
+    if (options.prompt) return { exitCode: 0, stdout: renderInitializationPrompt(instruction), stderr: "" };
+    const summary = [
+      `Initialization instruction ${instruction.instruction.id} v${instruction.instruction.version}.`,
+      `Package: ${instruction.package.name}@${instruction.package.version}.`,
+      `Target root: ${instruction.targetRoot}.`,
+      `Instruction: ${instruction.instruction.packagePath}; ${instruction.instruction.digest}.`,
+    ].join("\n") + "\n";
+    return { exitCode: 0, stdout: jsonOrText(options, instruction, summary), stderr: "" };
+  }
   if (command === "capabilities") {
     const capabilities = await buildCapabilities(root);
     const summary = [

package/src/project-context/contract-schema.mjs

@@ -308,7 +308,7 @@ export function validateProjectionLock(lock) {
       if (entry.regionId !== "project-context-ai-entry") fail("schema-invalid-enum", "AI Entry regionId is invalid");
       string(entry.regionDigest, `${label}.regionDigest`);
       if (!SHA256.test(entry.regionDigest)) fail("schema-invalid", "AI Entry regionDigest must be sha256");
-      if (![1, 2, 3].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, or 3");
+      if (![1, 2, 3, 4].includes(entry.rendererVersion)) fail("schema-version-unsupported", "AI Entry rendererVersion must be 1, 2, 3, or 4");
       if (typeof entry.createdFile !== "boolean") fail("schema-invalid", `${label}.createdFile must be boolean`);
     } else {
       if (entry.target !== "agents" && entry.target !== "ruler") fail("schema-invalid-enum", "projection target is invalid");