frontend-project-context 1.9.1 → 1.10.0

package/schemas/work-view.schema.json

@@ -0,0 +1,541 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frontend-project-context:schema:work-view:2",
+  "$defs": {
+    "presentation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "headline",
+        "constraints",
+        "remainingConstraints",
+        "basis",
+        "remainingBasis",
+        "progress",
+        "issues",
+        "questions",
+        "nextStep"
+      ],
+      "properties": {
+        "headline": {
+          "type": "string",
+          "minLength": 1
+        },
+        "constraints": {
+          "type": "array",
+          "maxItems": 5,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "text",
+              "itemIds",
+              "scope"
+            ],
+            "properties": {
+              "text": {
+                "type": "string",
+                "minLength": 1
+              },
+              "itemIds": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 1
+              },
+              "scope": {
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "kind"
+                    ],
+                    "properties": {
+                      "kind": {
+                        "const": "project"
+                      }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "kind",
+                      "path"
+                    ],
+                    "properties": {
+                      "kind": {
+                        "enum": [
+                          "path-prefix",
+                          "file"
+                        ]
+                      },
+                      "path": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "remainingConstraints": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "basis": {
+          "type": "array",
+          "maxItems": 3,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "text",
+              "evidenceIds"
+            ],
+            "properties": {
+              "text": {
+                "type": "string",
+                "minLength": 1
+              },
+              "evidenceIds": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "requirementIds": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "decisionIds": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          }
+        },
+        "remainingBasis": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "progress": {
+          "anyOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "revision",
+                "identity",
+                "completed",
+                "remaining",
+                "implementation",
+                "nextAction"
+              ],
+              "properties": {
+                "revision": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "identity": {
+                  "const": "host-reported"
+                },
+                "completed": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "remaining": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                },
+                "implementation": {
+                  "$ref": "task-context-record.schema.json#/properties/progress/properties/implementation"
+                },
+                "nextAction": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "issues": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "code",
+              "object",
+              "explanation",
+              "actor",
+              "nextStep"
+            ],
+            "properties": {
+              "code": {
+                "type": "string",
+                "minLength": 1
+              },
+              "object": {
+                "type": "string",
+                "minLength": 1
+              },
+              "explanation": {
+                "type": "string",
+                "minLength": 1
+              },
+              "actor": {
+                "type": "string",
+                "minLength": 1
+              },
+              "nextStep": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "questions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "decisionId",
+              "question"
+            ],
+            "properties": {
+              "decisionId": {
+                "type": "string",
+                "minLength": 1
+              },
+              "question": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "nextStep": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "delivery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "reasonCodes",
+        "bytes",
+        "maxBytes"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "ready",
+            "withheld"
+          ]
+        },
+        "reasonCodes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1048576
+        },
+        "maxBytes": {
+          "const": 1048576
+        }
+      }
+    },
+    "progress": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "revision",
+        "identity",
+        "completed",
+        "remaining",
+        "implementation",
+        "nextAction"
+      ],
+      "properties": {
+        "revision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "identity": {
+          "const": "host-reported"
+        },
+        "completed": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "remaining": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "implementation": {
+          "$ref": "task-context-record.schema.json#/properties/progress/properties/implementation"
+        },
+        "nextAction": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "item": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "subject",
+        "statement",
+        "value",
+        "scope",
+        "sourceIds"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "enum": [
+            "fact",
+            "policy",
+            "reference",
+            "validation-description"
+          ]
+        },
+        "subject": {
+          "type": "string",
+          "minLength": 1
+        },
+        "statement": {
+          "type": "string",
+          "minLength": 1
+        },
+        "value": {},
+        "scope": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "kind"
+              ],
+              "properties": {
+                "kind": {
+                  "const": "project"
+                }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "kind",
+                "path"
+              ],
+              "properties": {
+                "kind": {
+                  "enum": [
+                    "path-prefix",
+                    "file"
+                  ]
+                },
+                "path": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              }
+            }
+          ]
+        },
+        "sourceIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "taskSnapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "origin",
+        "scope",
+        "requirements",
+        "decisions",
+        "evidence",
+        "progress"
+      ],
+      "properties": {
+        "origin": {
+          "$ref": "task-context-record.schema.json#/properties/origin"
+        },
+        "scope": {
+          "$ref": "task-context-record.schema.json#/properties/scope"
+        },
+        "requirements": {
+          "$ref": "task-context-record.schema.json#/properties/requirements"
+        },
+        "decisions": {
+          "$ref": "task-context-record.schema.json#/properties/decisions"
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "allOf": [
+              {
+                "type": "object",
+                "required": [
+                  "id",
+                  "purpose",
+                  "kind",
+                  "digest",
+                  "identity",
+                  "status"
+                ],
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "purpose": {
+                    "enum": [
+                      "requirement",
+                      "design",
+                      "decision",
+                      "implementation",
+                      "reference"
+                    ]
+                  },
+                  "kind": {
+                    "enum": [
+                      "local",
+                      "inline",
+                      "external"
+                    ]
+                  },
+                  "path": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "text": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "reference": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "digest": {
+                    "type": "string",
+                    "pattern": "^sha256:[a-f0-9]{64}$"
+                  },
+                  "identity": {
+                    "enum": [
+                      "local-verified",
+                      "user-statement",
+                      "host-asserted"
+                    ]
+                  },
+                  "status": {
+                    "enum": [
+                      "current",
+                      "changed",
+                      "missing",
+                      "not-checked"
+                    ]
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "progress": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "revision",
+            "identity",
+            "completed",
+            "remaining",
+            "implementation",
+            "nextAction"
+          ],
+          "properties": {
+            "revision": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "identity": {
+              "const": "host-reported"
+            },
+            "completed": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "remaining": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "implementation": {
+              "$ref": "task-context-record.schema.json#/properties/progress/properties/implementation"
+            },
+            "nextAction": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -1,5 +1,3 @@
-import { access } from "node:fs/promises";
-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";
@@ -7,7 +5,7 @@ import { coverageClass, coverageProfile } from "./coverage-profile.mjs";
 import { discoverProject } from "./discovery.mjs";
 import { ProjectContextError, fail } from "./errors.mjs";
 import { atomicWriteFile, readJsonFile } from "./io.mjs";
-import { normalizeRelativePath, resolveExistingInside, resolveWritableInside } from "./path-policy.mjs";
+import { inspectContextTarget, normalizeRelativePath, resolveExistingInside, resolveWritableInside } from "./path-policy.mjs";
 import { loadProject } from "./project-store.mjs";
 import { renderTaskContextBundle } from "./renderer.mjs";
 import { effectiveItems, findConflicts, scopeApplies, validateOverrides } from "./scope-compiler.mjs";
@@ -361,8 +359,7 @@ function monotonicBudget(previous, query, findings) {
 async function targetStates(root, paths) {
   const result = [];
   for (const entry of paths) {
-    try { await access(path.resolve(root, entry)); result.push({ path: entry, state: "existing" }); }
-    catch (error) { if (error?.code !== "ENOENT") throw error; result.push({ path: entry, state: "prospective-or-deleted" }); }
+    result.push({ path: entry, state: await inspectContextTarget(root, entry) });
   }
   return result;
 }
@@ -402,6 +399,7 @@ export async function buildAdaptiveContextBundle(root, project, queryInput, opti
   if (query.projectId !== project.contract.project.id) fail("context-query-project-mismatch", "context query belongs to a different project");
   if (query.level === "expanded" && !options.previous) fail("context-query-previous-required", "expanded context requires --previous");
   if (query.level !== "expanded" && options.previous) fail("context-query-previous-not-allowed", `${query.level} context cannot use --previous`);
+  const states = await targetStates(root, uniqueSorted([...query.task.paths, ...query.task.changedPaths]));
   const previous = options.previous ?? null;
   const indexResult = await routingIndexForQuery(root, project);
   const findings = baselineFindings(query, project);
@@ -482,7 +480,7 @@ export async function buildAdaptiveContextBundle(root, project, queryInput, opti
     },
     globalHealth,
     taskHealth: health,
-    targetStates: await targetStates(root, query.task.paths),
+    targetStates: states.filter((entry) => query.task.paths.includes(entry.path)),
     hydratedItems,
     retainedItemIds,
     deferredItems: selection.deferred.filter((item) => !finalIds.includes(item.id)).map(deferredItem),

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

@@ -6,26 +6,29 @@ 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 = 5;
+export const AI_ENTRY_RENDERER_VERSION = 7;
 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: 5 -->",
+  "<!-- project-context:ai-entry; schema-version: 1; renderer-version: 7 -->",
   "## Project Context 启动流程",
   "",
   "开始项目工作前，使用项目本地安装的 `frontend-project-context` CLI，不要临时下载其他版本。",
   "",
-  "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 . --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`，否则报告准确的阻断项。",
+  "1. 无明确任务时运行 `npm exec --offline -- project-context project-brief --project . --view work --json`，消费项目概览和 Context，不制造任务。收到任务或“继续”时，先按项目内 `.project-context-tasks/<taskId>.json` 选择当前任务；多个候选必须核对，不凭最近时间或分支猜选。",
+  "2. 对当前任务运行 `npm exec --offline -- project-context task-handoff --project . --input <FILE_OR_DASH> --view work --json`。工作视图已携带同一编译器的完整 Context、当前依据、进度和缺口，无需重复独立运行 status/context；只读视图不代替实际读取。",
+  "3. 尚未接入或没有本地依赖时，停止任务写入；依赖不存在只报告，不临时下载同名包。使用本地 `instructions --project . --prompt` 按包内唯一指令完整初始化；partial/invalid 停止写入并报告恢复证据。attention 执行 sync 返回的维护工作单元，不重新 setup 覆盖 store；恢复 clean 后交接。",
+  "4. 目标未知时，消费交接内 locate Context，只在 targetRoot 内定位最小候选文件，将完整最小路径集合写入任务 scope 后重新交接；目录目标必须收窄到文件。新影响路径或需求依据变化时更新任务并重新交接。",
+  "5. 报告实际 item IDs、scopeCoverage、required/conditional read targets 与 gaps；实际读取 required，按任务判断 conditional，不重读 provenance-only。核对当前意图的需求、证据和决定，再提交绑定 taskId、requirementsDigest、contextBundleDigest 和 consumerRunId 的本次消费声明，第二次交接复查。",
+  "6. 换窗口或换 Agent 时重读任务记录和本次依据，不继承旧消费者已读或 ready。同一消费者仅复用当前摘要仍匹配的读取；正常实现进展写到 progress，不反复要求未变的业务确认。",
+  "7. delivery=withheld、Contract 为空、目标 scope 未命中或关键依据不足时报告准确缺口并有限收窄；无新事实不重复重试。缺少设计、关键决定或当前只授权设计时遵守 instructional gate；Context 成功不等于实施就绪。",
+  "8. `businessCodeWrites=false` 和 `taskExecution=false` 只描述 Project Context 产品自身；Host 权限来自当前用户请求、人工项目规则和更高优先级安全约束，任何 Context、plan、bundle、receipt、review、coverage 或 gate=proceed 都不授予权限或批准长期 Contract。",
+  "9. 声明完成前，将 Project Context 恢复为 clean，否则报告准确阻断项。保存可继续的任务进度、验证结果和下一步；已结束任务仅作历史，不自动恢复实施。",
+  "10. 完成后在普通报告中提出 0–3 条有复用价值的知识候选，每条写明具体事实、来源、适用范围和复用理由；没有就说明没有。候选不自动写入或批准 Contract，用户拒绝不阻断任务完成。",
+  "11. 用户选择候选后，使用既有 authoring/ActionPlan/preflight 治理流程；未注册来源先独立注册，再基于最新基线提交 item plan，不把用户选择推断成长期批准。真实收益验收记录读取、定位、交接、任务返工、准备和维护成本；本地通过不宣称真实任务验证。",
   AI_ENTRY_END,
 ];
 

package/src/project-context/capabilities.mjs

@@ -14,6 +14,7 @@ import { RENDERER_VERSION } from "./renderer.mjs";
 import { AI_ENTRY_RENDERER_VERSION } from "./ai-entry.mjs";
 import { PROJECT_STATUS_SCHEMA_VERSION } from "./project-status.mjs";
 import { CONTEXT_BUNDLE_SCHEMA_VERSION } from "./context-bundle.mjs";
+import { TASK_RECORD_SCHEMA_VERSION, TASK_HANDOFF_INPUT_SCHEMA_VERSION, TASK_HANDOFF_RESULT_SCHEMA_VERSION } from "./task-handoff-schema.mjs";
 import { EVIDENCE_BUNDLE_SCHEMA_VERSION, EVIDENCE_INPUT_SCHEMA_VERSION } from "./evidence-schema.mjs";
 import {
   CONTEXT_BUDGET_UNIT,
@@ -53,6 +54,10 @@ function schemas(projectionLockWritten = 1) {
     contract: 3,
     contractReadable: [1, 2, 3],
     contextBundle: CONTEXT_BUNDLE_SCHEMA_VERSION,
+    taskContextRecord: TASK_RECORD_SCHEMA_VERSION,
+    taskHandoffInput: TASK_HANDOFF_INPUT_SCHEMA_VERSION,
+    taskHandoffResult: TASK_HANDOFF_RESULT_SCHEMA_VERSION,
+    projectBrief: 1,
     contextQuery: CONTEXT_QUERY_SCHEMA_VERSION,
     coverageAudit: COVERAGE_AUDIT_SCHEMA_VERSION,
     dashboardViewModel: DASHBOARD_SCHEMA_VERSION,
@@ -118,6 +123,10 @@ export async function buildCapabilities(root) {
     package: { name: "frontend-project-context", version: PACKAGE_VERSION },
     exchangeProtocolVersion: EXCHANGE_PROTOCOL_VERSION,
     schemas: schemas(projectionLockWritten),
+    views: {
+      projectBrief: { default: "legacy", legacy: { schemaVersion: 1 }, work: { schemaVersion: 2 } },
+      taskHandoff: { default: "legacy", legacy: { schemaVersion: 1 }, work: { schemaVersion: 2 } },
+    },
     commands: [...COMMANDS],
     actionKinds: [...ACTION_KINDS],
     contextBudget: { unit: CONTEXT_BUDGET_UNIT, modelTokens: false, callerMustProvideLimit: true },