frontend-project-context 1.8.0 → 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-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

@@ -1,12 +1,11 @@
-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";
+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";
@@ -26,7 +25,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 +143,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 +156,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 +318,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 });
@@ -372,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;
 }
@@ -413,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);
@@ -493,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),