frontend-project-context 1.8.0 → 1.9.1

package/migration-manifest.json

@@ -23,14 +23,15 @@
   "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 8 and exchange protocol 8.", "state": "regenerate"},
+    "capabilities": {"reason": "Consumers must branch on capabilities schema 9 and exchange protocol 9.", "state": "regenerate"},
+    "contextBundle": {"reason": "Context Bundle schema 1 is short-lived and must be regenerated from the current Contract and exact task paths.", "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"},
+    "coverageAudit": {"reason": "Coverage Audit schema 2 is derived from the current Contract and declared coverage profile.", "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 8.", "state": "regenerate"},
+    "exchange": {"reason": "Exchange protocol capability metadata changes to version 9.", "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"},
+    "initializationInstruction": {"reason": "Schema 2 adds concentrated human entry rule dispositions and remains package-derived.", "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"},
@@ -42,8 +43,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:be29e7ee930d34533380e6d2408f614fc7406ad3491a1657776d904bcc5ebacf",
-  "package": {"name": "frontend-project-context", "version": "1.8.0"},
+  "manifestDigest": "sha256:8b1a6bce6ac179591b122593c062cf6d0f80680da1eca5aba663e3273bbd1e56",
+  "package": {"name": "frontend-project-context", "version": "1.9.1"},
   "paths": [
     {
       "acceptance": ["project-context-clean", "target-renderers-current"],
@@ -84,18 +85,35 @@
       "migrationIds": ["upgrade.republish-ai-entry.v1"],
       "requiresHumanReview": false,
       "rollbackClass": "package-only"
+    },
+    {
+      "acceptance": ["project-context-clean", "target-renderers-current"],
+      "classification": "package-only",
+      "fromVersion": "1.8.0",
+      "migrationIds": ["upgrade.republish-ai-entry.v1"],
+      "requiresHumanReview": false,
+      "rollbackClass": "package-only"
+    },
+    {
+      "acceptance": ["project-context-clean", "target-renderers-current"],
+      "classification": "package-only",
+      "fromVersion": "1.9.0",
+      "migrationIds": [],
+      "requiresHumanReview": false,
+      "rollbackClass": "package-only"
     }
   ],
   "protocols": {
     "actionPlan": {"readable": [1, 2], "written": 2},
     "adaptiveContextBundle": {"readable": [2], "written": 2},
+    "contextBundle": {"readable": [1], "written": 1},
     "contextQuery": {"readable": [2], "written": 2},
-    "coverageAudit": {"readable": [1], "written": 1},
+    "coverageAudit": {"readable": [1, 2], "written": 2},
     "evidenceBundle": {"readable": [1], "written": 1},
     "evidenceInput": {"readable": [1], "written": 1},
-    "exchange": {"readable": [4, 5, 6, 7, 8], "written": 8},
+    "exchange": {"readable": [4, 5, 6, 7, 8, 9], "written": 9},
     "hostPromotionEvidence": {"readable": [1], "written": 1},
-    "initializationInstruction": {"readable": [1], "written": 1},
+    "initializationInstruction": {"readable": [1, 2], "written": 2},
     "integrationReviewBundle": {"readable": [1], "written": 1},
     "projectStatus": {"readable": [1, 2], "written": 2},
     "reviewBundle": {"readable": [1, 2], "written": 2},
@@ -107,16 +125,16 @@
     "truthReconciliationReviewBundle": {"readable": [2], "written": 2}
   },
   "renderers": {
-    "aiEntry": {"readable": [1, 2, 3, 4], "written": 4},
+    "aiEntry": {"readable": [1, 2, 3, 4, 5], "written": 5},
     "projection": {"readable": [1, 2, 3], "written": 3}
   },
   "rollback": {"automatic": false, "defaultClass": "package-only", "externalRestoreRequired": true},
   "schemaVersion": 2,
   "stores": {
-    "contract": {"readable": [1, 2], "written": [1, 2]},
+    "contract": {"readable": [1, 2, 3], "written": [1, 2, 3]},
     "projectionLock": {"readable": [1, 2], "written": [1, 2]},
     "proposal": {"readable": [1], "written": [1]},
     "sourceLock": {"readable": [1], "written": [1]}
   },
-  "upgradeFrom": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]
+  "upgradeFrom": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0", "1.8.0", "1.9.0"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-project-context",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "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/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",
+    "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/task-context-consumption.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:8",
+  "$id": "urn:frontend-project-context:schema:capabilities:9",
   "title": "Frontend Project Context Capabilities",
   "type": "object",
   "additionalProperties": false,
@@ -19,17 +19,17 @@
     "boundaries"
   ],
   "properties": {
-    "schemaVersion": { "const": 8 },
+    "schemaVersion": { "const": 9 },
     "package": {
       "type": "object",
       "additionalProperties": false,
       "required": ["name", "version"],
       "properties": {
         "name": { "const": "frontend-project-context" },
-        "version": { "const": "1.8.0" }
+        "version": { "const": "1.9.1" }
       }
     },
-    "exchangeProtocolVersion": { "const": 8 },
+    "exchangeProtocolVersion": { "const": 9 },
     "schemas": {
       "type": "object",
       "additionalProperties": false,
@@ -39,6 +39,8 @@
         "assistBundle",
         "capabilities",
         "contract",
+        "contractReadable",
+        "contextBundle",
         "contextQuery",
         "coverageAudit",
         "dashboardViewModel",
@@ -71,23 +73,25 @@
         "actionPlan": { "const": 2 },
         "adaptiveContextBundle": { "const": 2 },
         "assistBundle": { "const": 1 },
-        "capabilities": { "const": 8 },
-        "contract": { "const": 2 },
+        "capabilities": { "const": 9 },
+        "contract": { "const": 3 },
+        "contractReadable": { "const": [1, 2, 3] },
+        "contextBundle": { "const": 1 },
         "contextQuery": { "const": 2 },
-        "coverageAudit": { "const": 1 },
+        "coverageAudit": { "const": 2 },
         "dashboardViewModel": { "type": "integer" },
         "evidenceBundle": { "const": 1 },
         "evidenceInput": { "const": 1 },
         "hostPromotionEvidence": { "const": 1 },
         "integrationReviewBundle": { "const": 1 },
-        "initializationInstruction": { "const": 1 },
+        "initializationInstruction": { "const": 2 },
         "projectionLock": { "const": 2 },
         "projectionLockReadable": { "const": [1, 2] },
         "projectionLockWritten": { "enum": [1, 2] },
         "projectionRenderer": { "type": "integer" },
         "proposal": { "const": 1 },
         "projectStatus": { "const": 2 },
-        "aiEntryRenderer": { "const": 4 },
+        "aiEntryRenderer": { "const": 5 },
         "migrationManifest": { "const": 2 },
         "migrationPlan": { "const": 1 },
         "reviewBundle": { "const": 2 },
@@ -139,7 +143,7 @@
       "required": ["id", "version", "packagePath", "digest", "command"],
       "properties": {
         "id": {"const": "ai-project-initialization"},
-        "version": {"const": 1},
+        "version": {"const": 2},
         "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]"}

package/schemas/context-bundle.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:context-bundle:1",
+  "title": "Frontend Project Context Bundle",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "kind", "project", "mode", "task", "snapshots", "semanticCompleteness", "commonItemIds", "targets", "items", "readTargets", "provenanceSources", "coverage", "authority", "gaps", "nextActions", "content", "bundleDigest"],
+  "properties": {
+    "schemaVersion": {"const": 1},
+    "kind": {"const": "context-bundle"},
+    "project": {"type": "object", "additionalProperties": false, "required": ["id", "name"], "properties": {"id": {"type": "string", "minLength": 1}, "name": {"type": "string", "minLength": 1}}},
+    "mode": {"enum": ["locate", "targeted"]},
+    "task": {"type": "object", "additionalProperties": false, "required": ["text", "paths"], "properties": {"text": {"type": "string"}, "paths": {"$ref": "#/$defs/strings"}}},
+    "snapshots": {"type": "object", "additionalProperties": false, "required": ["contract", "sourcesLock", "projectionsLock"], "properties": {"contract": {"$ref": "#/$defs/digest"}, "sourcesLock": {"$ref": "#/$defs/digest"}, "projectionsLock": {"$ref": "#/$defs/digest"}}},
+    "semanticCompleteness": {"const": "not-claimed"},
+    "commonItemIds": {"$ref": "#/$defs/strings"},
+    "targets": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["path", "scopeCoverage", "itemIds", "scopedItemIds", "deltaItemIds"], "properties": {"path": {"type": "string"}, "scopeCoverage": {"enum": ["scoped", "project-only", "none"]}, "itemIds": {"$ref": "#/$defs/strings"}, "scopedItemIds": {"$ref": "#/$defs/strings"}, "deltaItemIds": {"$ref": "#/$defs/strings"}}}},
+    "items": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["id", "kind", "subject", "scope", "sourceIds", "statement", "value", "overrides"], "properties": {"id": {"type": "string", "minLength": 1}, "kind": {"enum": ["fact", "policy", "reference", "validation-description"]}, "subject": {"type": "string", "minLength": 1}, "scope": {"type": "object", "additionalProperties": false, "required": ["kind"], "properties": {"kind": {"enum": ["project", "path-prefix", "file"]}, "path": {"type": "string"}}}, "sourceIds": {"$ref": "#/$defs/strings"}, "statement": {"type": "string", "minLength": 1}, "value": true, "overrides": {"$ref": "#/$defs/strings"}, "verification": {"type": "object", "additionalProperties": false, "required": ["kind"], "properties": {"kind": {"enum": ["none", "file-exists", "json-value", "path-digest"]}, "source": {"type": "string"}, "expected": true}}, "consumption": {"type": "object", "additionalProperties": false, "required": ["requiredSources", "conditionalSources"], "properties": {"requiredSources": {"$ref": "#/$defs/strings"}, "conditionalSources": {"$ref": "#/$defs/strings"}}}}}},
+    "readTargets": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["path", "role", "itemIds", "sourceIds", "reasons"], "properties": {"path": {"type": "string"}, "role": {"enum": ["required", "conditional"]}, "itemIds": {"$ref": "#/$defs/strings"}, "sourceIds": {"$ref": "#/$defs/strings"}, "reasons": {"$ref": "#/$defs/strings"}, "pointers": {"$ref": "#/$defs/strings"}}}},
+    "provenanceSources": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["sourceId", "itemIds", "kind", "locator"], "properties": {"sourceId": {"type": "string"}, "itemIds": {"$ref": "#/$defs/strings"}, "kind": {"type": "string"}, "locator": {"type": "object"}}}},
+    "coverage": {"type": "object", "additionalProperties": false, "required": ["profileItemId", "profileVersion", "registrationCoverage", "targets", "guarantee"], "properties": {"profileItemId": {"type": ["string", "null"]}, "profileVersion": {"enum": [null, 1, 2]}, "registrationCoverage": {"enum": ["not-declared", "review-required", "unresolved", "closed-for-declared-scope"]}, "targets": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["path", "disposition", "domainId"], "properties": {"path": {"type": "string"}, "disposition": {"enum": ["contract-covered", "dynamic-investigation", "excluded-approved", "unresolved", "outside-declared-coverage"]}, "domainId": {"type": ["string", "null"]}}}}, "guarantee": {"const": "declared-scope-only-never-all-project-truth"}}},
+    "authority": {"type": "object", "additionalProperties": false, "required": ["productTaskExecution", "productBusinessCodeWrites", "hostTaskAuthority", "resolveFrom"], "properties": {"productTaskExecution": {"const": false}, "productBusinessCodeWrites": {"const": false}, "hostTaskAuthority": {"const": "external-to-project-context"}, "resolveFrom": {"const": ["current-user-request", "human-authored-project-instructions", "higher-priority-safety-constraints"]}}},
+    "gaps": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["code"], "properties": {"code": {"enum": ["target-path-not-yet-known", "project-scope-only", "no-applicable-contract-item", "registration-coverage-not-declared", "registration-coverage-review-required", "required-read-target-unavailable"]}, "path": {"type": "string"}, "sourceIds": {"$ref": "#/$defs/strings"}, "reason": {"type": "string"}, "disposition": {"enum": ["unresolved"]}}}},
+    "nextActions": {"$ref": "#/$defs/strings"},
+    "content": {"type": "string", "minLength": 1},
+    "bundleDigest": {"$ref": "#/$defs/digest"}
+  },
+  "$defs": {
+    "digest": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+    "strings": {"type": "array", "uniqueItems": true, "items": {"type": "string"}}
+  }
+}

package/schemas/coverage-audit.schema.json

@@ -1,25 +1,27 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:frontend-project-context:schema:coverage-audit:1",
+  "$id": "urn:frontend-project-context:schema:coverage-audit:2",
   "title": "Frontend Project Context Coverage Audit",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "kind", "project", "snapshots", "profile", "registrationCoverage", "categories", "guarantee", "auditDigest"],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": { "const": 2 },
     "kind": { "const": "coverage-audit" },
     "project": { "type": "object", "additionalProperties": false, "required": ["id", "name"], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } },
     "snapshots": { "$ref": "context-query.schema.json#/$defs/snapshots" },
     "profile": { "type": ["object", "null"] },
-    "registrationCoverage": { "enum": ["not-declared", "review-required", "closed-for-declared-scope"] },
+    "registrationCoverage": { "enum": ["not-declared", "review-required", "unresolved", "closed-for-declared-scope"] },
     "categories": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["registered", "excluded-approved", "review-required", "outside-declared-coverage"],
+      "required": ["registered", "dynamic-investigation", "excluded-approved", "review-required", "unresolved", "outside-declared-coverage"],
       "properties": {
         "registered": { "$ref": "#/$defs/candidates" },
+        "dynamic-investigation": { "$ref": "#/$defs/candidates" },
         "excluded-approved": { "$ref": "#/$defs/candidates" },
         "review-required": { "$ref": "#/$defs/candidates" },
+        "unresolved": { "$ref": "#/$defs/candidates" },
         "outside-declared-coverage": { "$ref": "#/$defs/candidates" }
       }
     },

package/schemas/evidence-bundle.schema.json

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

package/schemas/initialization-instruction.schema.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:frontend-project-context:schema:initialization-instruction:1",
+  "$id": "urn:frontend-project-context:schema:initialization-instruction:2",
   "title": "Frontend Project Context Initialization Instruction",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "package", "instruction", "targetRoot", "boundaries"],
+  "required": ["schemaVersion", "package", "instruction", "targetRoot", "boundaries", "entryRuleReview"],
   "properties": {
-    "schemaVersion": {"const": 1},
+    "schemaVersion": {"const": 2},
     "package": {
       "type": "object",
       "additionalProperties": false,
       "required": ["name", "version"],
       "properties": {
         "name": {"const": "frontend-project-context"},
-        "version": {"const": "1.8.0"}
+        "version": {"const": "1.9.1"}
       }
     },
     "instruction": {
@@ -22,13 +22,25 @@
       "required": ["id", "version", "packagePath", "digest", "content"],
       "properties": {
         "id": {"const": "ai-project-initialization"},
-        "version": {"const": 1},
+        "version": {"const": 2},
         "packagePath": {"const": "docs/AI-PROJECT-INITIALIZATION.md"},
         "digest": {"$ref": "#/$defs/digest"},
         "content": {"type": "string", "minLength": 1}
       }
     },
     "targetRoot": {"type": "string", "minLength": 1},
+    "entryRuleReview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "present", "allowedDispositions", "records", "automaticDeletion"],
+      "properties": {
+        "path": {"const": "AGENTS.md"},
+        "present": {"type": "boolean"},
+        "allowedDispositions": {"const": ["migrated-to-contract", "kept-in-entry-intentionally", "excluded-as-stale", "unresolved-blocker"]},
+        "records": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["id", "disposition", "rationale"], "properties": {"id": {"type": "string"}, "disposition": {"enum": ["migrated-to-contract", "kept-in-entry-intentionally", "excluded-as-stale", "unresolved-blocker"]}, "rationale": {"type": "string"}}}},
+        "automaticDeletion": {"const": false}
+      }
+    },
     "boundaries": {
       "type": "object",
       "additionalProperties": false,

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.8.0"}}},
-    "upgradeFrom": {"const": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0"]},
+    "package": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "frontend-project-context"}, "version": {"const": "1.9.1"}}},
+    "upgradeFrom": {"const": ["1.3.1", "1.4.0", "1.5.0", "1.6.0", "1.7.0", "1.8.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": 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"}}}},
+    "paths": {"type": "array", "minItems": 6, "maxItems": 6, "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", "1.8.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

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

package/schemas/projection-lock.schema.json

@@ -33,7 +33,7 @@
       "properties": {
         "path": { "type": "string" }, "target": { "const": "ai-entry" }, "ownership": { "const": "region" },
         "regionId": { "const": "project-context-ai-entry" }, "regionDigest": { "$ref": "#/$defs/digest" },
-        "rendererVersion": { "enum": [1, 2, 3] }, "createdFile": { "type": "boolean" }
+        "rendererVersion": { "enum": [1, 2, 3, 4, 5] }, "createdFile": { "type": "boolean" }
       }
     },
     "schema1": {

package/schemas/upgrade-assessment.schema.json

@@ -10,7 +10,7 @@
     "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", "1.7.0"]},
-    "targetVersion": {"const": "1.8.0"},
+    "targetVersion": {"const": "1.9.1"},
     "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.8.0"},
+    "targetVersion": {"const": "1.9.1"},
     "manifestDigest": {"$ref": "#/$defs/digest"},
     "planDigest": {"$ref": "#/$defs/digest"},
     "mode": {"enum": ["preview", "write"]},

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

@@ -5,7 +5,7 @@ import { normalizeRelativePath } from "./path-policy.mjs";
 export const CONTEXT_QUERY_SCHEMA_VERSION = 2;
 export const ADAPTIVE_CONTEXT_BUNDLE_SCHEMA_VERSION = 2;
 export const ROUTING_INDEX_SCHEMA_VERSION = 2;
-export const COVERAGE_AUDIT_SCHEMA_VERSION = 1;
+export const COVERAGE_AUDIT_SCHEMA_VERSION = 2;
 export const ADAPTIVE_SELECTOR_VERSION = 2;
 export const ROUTING_INDEX_PATH = ".project-context/derived/routing-index.json";
 

package/src/project-context/adaptive-context.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 import { canonicalJson, digestJson, prettyCanonicalJson, sha256 } from "./canonical-json.mjs";
 import { blockingContextFindings, checkProject } from "./checker.mjs";
 import { sourceStatus } from "./contract-schema.mjs";
+import { coverageClass, coverageProfile } from "./coverage-profile.mjs";
 import { discoverProject } from "./discovery.mjs";
 import { ProjectContextError, fail } from "./errors.mjs";
 import { atomicWriteFile, readJsonFile } from "./io.mjs";
@@ -26,7 +27,6 @@ import {
 const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
 const MANDATORY_KINDS = new Set(["policy", "validation-description"]);
 const ROUTED_KINDS = new Set(["fact", "reference"]);
-const COVERAGE_SUBJECT = "project.registration-coverage";
 const RETRIEVAL_SUBJECT = "project.context-retrieval";
 const EXCLUDED_BODIES = Object.freeze(["chat-history", "git-diffs", "source-bodies", "task-path-bodies", "verification-logs"]);
 const ROUTING_STOP_TERMS = new Set(["a", "an", "and", "apply", "change", "for", "in", "of", "on", "project", "rule", "the", "to", "update", "use"]);
@@ -145,24 +145,7 @@ export async function indexContext(root, project, options = {}) {
   return index;
 }
 
-function pathWithin(target, parent) { return parent === "." || target === parent || target.startsWith(`${parent}/`); }
-function coverageProfile(contract) {
-  const candidates = contract.items.filter((item) => item.status === "approved" && item.kind === "policy" && item.subject === COVERAGE_SUBJECT);
-  if (candidates.length === 0) return null;
-  if (candidates.length > 1) fail("coverage-profile-conflict", `multiple approved ${COVERAGE_SUBJECT} items are active`);
-  const item = candidates[0];
-  const value = item.value;
-  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["excludedPaths", "roots"].includes(key)) || !Array.isArray(value.roots) || !Array.isArray(value.excludedPaths)) fail("coverage-profile-invalid", `${item.id} coverage value is invalid`);
-  const normalize = (values, label) => uniqueSorted(values.map((entry) => normalizeRelativePath(entry, { allowRoot: true, label })));
-  return { itemId: item.id, itemDigest: digestJson(item), sourceIds: [...item.sources].sort(), roots: normalize(value.roots, "coverage root"), excludedPaths: normalize(value.excludedPaths, "coverage excluded path") };
-}
-function coverageClass(profile, registeredPaths, candidatePath) {
-  if (registeredPaths.has(candidatePath)) return "registered";
-  if (!profile) return "outside-declared-coverage";
-  if (profile.excludedPaths.some((entry) => pathWithin(candidatePath, entry))) return "excluded-approved";
-  if (profile.roots.some((entry) => pathWithin(candidatePath, entry))) return "review-required";
-  return "outside-declared-coverage";
-}
+export { coverageClass, coverageProfile } from "./coverage-profile.mjs";
 export async function buildCoverageAudit(root, project, changedPaths = []) {
   const profile = coverageProfile(project.contract);
   const proposal = await discoverProject(root, project.contract);
@@ -175,10 +158,16 @@ export async function buildCoverageAudit(root, project, changedPaths = []) {
     if (!byPath.has(normalized)) byPath.set(normalized, { path: normalized, origin: "host-changed-path-signal" });
   }
   for (const registeredPath of registered) if (!byPath.has(registeredPath)) byPath.set(registeredPath, { path: registeredPath, origin: "registered-source" });
-  const categories = { registered: [], "excluded-approved": [], "review-required": [], "outside-declared-coverage": [] };
+  const categories = { registered: [], "dynamic-investigation": [], "excluded-approved": [], "review-required": [], unresolved: [], "outside-declared-coverage": [] };
   for (const candidate of [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path))) categories[coverageClass(profile, registeredPaths, candidate.path)].push(candidate);
-  const registrationCoverage = !profile ? "not-declared" : categories["review-required"].length === 0 ? "closed-for-declared-scope" : "review-required";
-  return sealArtifact({ schemaVersion: 1, kind: "coverage-audit", project: { id: project.contract.project.id, name: project.contract.project.name }, snapshots: snapshots(project), profile, registrationCoverage, categories, guarantee: "declared-scope-only-never-all-project-truth" }, "auditDigest");
+  const registrationCoverage = !profile
+    ? "not-declared"
+    : categories.unresolved.length > 0
+      ? "unresolved"
+      : categories["review-required"].length === 0
+        ? "closed-for-declared-scope"
+        : "review-required";
+  return sealArtifact({ schemaVersion: 2, kind: "coverage-audit", project: { id: project.contract.project.id, name: project.contract.project.name }, snapshots: snapshots(project), profile, registrationCoverage, categories, guarantee: "declared-scope-only-never-all-project-truth" }, "auditDigest");
 }
 
 function effectiveByTarget(contract, paths, findings) {
@@ -331,7 +320,7 @@ async function auditRelevantSources(root, project, items, sourceReadContext) {
     const base = { id: source.id, kind: source.kind, locator: sourceLocator(source), sourceDigest: digestJson(source) };
     if (!LOCAL_SOURCE_KINDS.has(source.kind)) { evidence.push({ ...base, freshness: "unverifiable-non-local" }); continue; }
     try {
-      const actual = await readSourceDigest(root, source, sourceReadContext);
+      const actual = await readSourceDigest(root, source, sourceReadContext, { projectionsLock: project.projectionsLock });
       const expected = lock.get(source.id) ?? null;
       const freshness = expected !== null && expected === source.digest && actual === expected ? "current" : "drifted";
       evidence.push({ ...base, freshness, expectedDigest: expected, actualDigest: actual });

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

@@ -6,14 +6,14 @@ 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 = 4;
+export const AI_ENTRY_RENDERER_VERSION = 5;
 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: 4 -->",
+  "<!-- project-context:ai-entry; schema-version: 1; renderer-version: 5 -->",
   "## Project Context 启动流程",
   "",
   "开始项目工作前，使用项目本地安装的 `frontend-project-context` CLI，不要临时下载其他版本。",
@@ -21,10 +21,11 @@ const ENTRY_LINES = [
   "1. 运行 `npm exec --offline -- project-context status --project . --json`；如果本地依赖不存在，停止并报告，不要临时下载同名包。",
   "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`，否则报告准确的阻断项。",
+  "4. 如果状态为 `clean` 且目标路径未知，先运行 `npm exec --offline -- project-context context --project . --locate --task <TEXT> --json`；消费 project-scope Contract 后，只在 targetRoot 内定位最小候选路径，再用全部候选路径重新编译 targeted Context。",
+  "5. 如果目标路径已知，运行 `npm exec --offline -- project-context context --project . --path <RELATIVE_PATH...> --task <TEXT> --json`；发现新的影响路径后，必须用完整的最小路径集合重新编译。",
+  "6. 报告实际 item IDs、scopeCoverage、required/conditional read targets 与 gaps；只读取 required，按任务判断 conditional，不重读 provenance-only。Contract 为空、目标 scope 未命中或关键上下文不足时，报告 onboarding/context gap。",
+  "7. `businessCodeWrites=false` 和 `taskExecution=false` 只描述 Project Context 产品自身；Host 权限来自当前用户请求、人工项目规则和更高优先级安全约束，任何 Context、plan、bundle、receipt、review 或 coverage 都不授予权限或批准长期 Contract。",
+  "8. 声明完成前，将 Project Context 恢复为 `clean`，否则报告准确的阻断项。",
   AI_ENTRY_END,
 ];
 
@@ -109,7 +110,13 @@ function schema2FileEntry(entry) {
   return entry.ownership ? structuredClone(entry) : { ...structuredClone(entry), ownership: "file" };
 }
 
-function sourceImpact(project, output, afterDigest) {
+function outsideOwnedDigest(content) {
+  const parsed = parseAiEntryRegion(content);
+  if (parsed.state !== "present") return null;
+  return digestJson({ before: content.slice(0, parsed.start), after: content.slice(parsed.end) });
+}
+
+function sourceImpact(project, output, afterContent) {
   const sources = project.contract.sources
     .filter((source) => sourceStatus(source) === "active" && ["file", "path", "json-pointer"].includes(source.kind) && source.path === output)
     .sort((left, right) => left.id.localeCompare(right.id));
@@ -119,6 +126,12 @@ function sourceImpact(project, output, afterDigest) {
     .filter((item) => item.sources.some((id) => selected.has(id)) || selected.has(item.verification?.source))
     .map((item) => item.id)
     .sort((left, right) => left.localeCompare(right));
+  const digestMode = sources[0]?.digestMode ?? "full-file";
+  const afterDigest = afterContent === null
+    ? null
+    : digestMode === "outside-owned-ai-entry"
+      ? outsideOwnedDigest(afterContent)
+      : sha256(afterContent);
   return { sourceIds, itemIds, afterDigest: sourceIds.length > 0 ? afterDigest : null };
 }
 
@@ -249,7 +262,7 @@ export async function publishAiEntry(root, project, options, dependencies = {})
   };
   const nextLock = nextProjectionLock(project, resolved.normalized, nextEntry);
   const action = currentEntry && existing === nextContent && canonicalJson(currentEntry) === canonicalJson(nextEntry) ? "unchanged" : currentEntry ? "update" : "create";
-  const impact = sourceImpact(project, resolved.normalized, sha256(nextContent));
+  const impact = sourceImpact(project, resolved.normalized, nextContent);
   const result = {
     action,
     current: {
@@ -304,7 +317,7 @@ export async function removeAiEntry(root, project, options, dependencies = {}) {
   }
   const nextContent = `${existing.slice(0, parsed.start)}${existing.slice(parsed.end)}`;
   const nextLock = nextProjectionLock(project, resolved.normalized, null);
-  const impact = sourceImpact(project, resolved.normalized, sha256(nextContent));
+  const impact = sourceImpact(project, resolved.normalized, nextContent);
   const result = {
     action: "remove",
     current: { entry: structuredClone(currentEntry), contentDigest: sha256(existing), region: parsed.region },

package/src/project-context/approver.mjs

@@ -1,5 +1,6 @@
 import { canonicalJson } from "./canonical-json.mjs";
 import {
+  promoteContractToSchema3,
   sourceForContract,
   sourceRegistrationShape,
   sourceStatus,
@@ -52,7 +53,7 @@ export async function approveProposal(root, project, proposalInput, options) {
   for (const sourceId of selectedSourceIds) {
     const source = proposalSources.get(sourceId);
     if (!source) fail("proposal-source-missing", `proposal source is missing: ${sourceId}`);
-    const actual = await readSourceDigest(root, source);
+    const actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
     if (actual !== null && actual !== source.digest) {
       fail("proposal-source-changed", `source changed after discovery: ${sourceId}`, {
         exitCode: 1,
@@ -61,6 +62,9 @@ export async function approveProposal(root, project, proposalInput, options) {
     }
   }
   const nextContract = structuredClone(project.contract);
+  if (selected.some((item) => item.consumption !== undefined) || [...selectedSourceIds].some((id) => proposalSources.get(id)?.digestMode !== undefined)) {
+    promoteContractToSchema3(nextContract);
+  }
   for (const sourceId of selectedSourceIds) {
     const source = proposalSources.get(sourceId);
     const existing = nextContract.sources.find((entry) => entry.id === sourceId);
@@ -141,7 +145,7 @@ export async function approvePendingItems(root, project, options) {
     }
     let actual;
     try {
-      actual = await readSourceDigest(root, source);
+      actual = await readSourceDigest(root, source, undefined, { projectionsLock: project.projectionsLock });
     } catch (error) {
       fail("pending-source-changed", `pending item source is unavailable: ${sourceId}`, {
         exitCode: 1,