@piagent/platform 1.6.0 → 1.6.1

package/packages/piagent-core/extensions/acceptance-receipt.js

@@ -5,6 +5,7 @@ import { durableContextEvidenceEntries, hasDurableContextEvidence } from "./cont
 import { matchesAnyPath, normalizePathCandidate } from "./policy-core.js";
 import { baselineReturnRepresentationConflicts, returnRepresentationGuidance } from "./return-contract.js";
 import { hasLengthPrefixedIdentityKey, tenantAssertionSignals } from "./tenant-contract.js";
+import { criterionBehaviorProofDisposition, criterionRequiresBehavioralProof, durableBehaviorProofRequired, genericCriterionEvidence, genericFallbackEvidence, isVerificationOnlyCriterion, verifierCommandsCoverTests } from "./acceptance-behavior-proof.js";
 import { latestObservedVerificationEvidence, meaningfulVerificationCommands, verificationEvidenceProvesStableTree } from "./verification-intelligence.js";
 import {
   acceptanceContractProofGuidance,
@@ -34,7 +35,7 @@ const EVIDENCE_FIELDS = new Set(["kind", "summary", "paths", "command", "exitCod
 const PROVENANCE_FIELDS = new Set(["assurance", "disposition", "repairCount", "retryCount", "finalRecoveryDisposition", "failureRef", "recoveryRef", "handoffRef", "recordedAt"]);
 const FAILURE_REF_FIELDS = new Set(["evidenceDigest", "category", "captureRef"]);
 const RECOVERY_REF_FIELDS = new Set(["policyVersion", "action", "reasonCodes"]);
-const HELPER_USAGE_FIELDS = new Set(["mode", "used", "reasonCodes", "helpers", "recordedAt"]);
+const HELPER_USAGE_FIELDS = new Set(["mode", "used", "decision", "projectedSavingsRatio", "reasonCodes", "helpers", "recordedAt"]);
 const HELPER_ENTRY_FIELDS = new Set(["role", "disposition", "requestRef", "outputDigest", "calls", "tokens"]);
 const HELPER_ROLES = new Set(["retriever", "scout", "planner", "worker", "reviewer", "oracle", "researcher"]);
 const RECEIPT_DISPOSITIONS = new Set(["first-pass-success", "repaired-success", "blocked", "partial", "failed", "pending"]);
@@ -43,7 +44,7 @@ const RECOVERY_ACTIONS = new Set(["repair", "retry", "fresh-session", "ask-opera
 const FAILURE_CATEGORIES = new Set(["passed", "compile-typecheck", "test-assertion", "lint-format", "dependency-config", "environment", "provider-network", "permission-policy", "scope-protected-path", "flaky-infrastructure", "unknown"]);
 const HASH = /^[a-f0-9]{64}$/;
 const SAFE_REF = /^[a-z0-9.][a-z0-9:._/-]{0,511}$/i;
-const READ_ONLY_BOUNDARY = /\b(?:read-only|no edits?|do not edit(?: files?| source| project| repo)?|do not change (?:files?|source|project|repo)|do not mutate (?:files?|source|project|repo|workspace)|khong sua(?: file| source| project)?|khong edit(?: file| source| project)?|khong doi(?: file| source| project)?)\b/;
+const READ_ONLY_BOUNDARY = /\b(?:read-only|no\s+(?:code|source|project|file|workspace|repo(?:sitory)?)?\s*(?:edits?|changes?|mutations?)|do not\s+(?:edit|change|modify|mutate|touch)(?: files?| source| project| repo| workspace)?|leave\s+(?:the\s+)?(?:source|project|repo|workspace)\s+(?:unchanged|unmodified)|khong\s+(?:sua|edit|thay\s+doi)(?: file| source| project)?)\b/;
 
 function sha256(value) {
   return crypto.createHash("sha256").update(String(value ?? "")).digest("hex");
@@ -80,11 +81,9 @@ function normalizedText(value) {
     .replace(/[\u0300-\u036f]/g, "")
     .toLowerCase();
 }
-
 function includesAny(text, patterns) {
   return patterns.some((pattern) => pattern.test(text));
 }
-
 function pathBoundaryMentioned(text, patterns) {
   const value = normalizedText(text);
   return uniqueStrings(patterns).some((pattern) => {
@@ -95,20 +94,35 @@ function pathBoundaryMentioned(text, patterns) {
     return value.includes(lower) || (Boolean(basename) && value.includes(basename));
   });
 }
-
+function readOnlyBoundaryTiedToPattern(text, patterns) {
+  return normalizedText(text)
+    .split(/(?:\r?\n+|[.!?;]+|\s+[—–]\s+)/)
+    .some((clause) => READ_ONLY_BOUNDARY.test(clause) && pathBoundaryMentioned(clause, patterns));
+}
 function changedFilesRespectBoundaries(changedFiles, boundaryPatterns) {
   const patterns = uniqueStrings(boundaryPatterns);
   if (patterns.length === 0) return true;
   return uniqueStrings(changedFiles).every((file) => !matchesAnyPath(file, patterns));
 }
+function acceptanceReadOnlyInferenceOptions(input, text) {
+  const boundaryPatterns = uniqueStrings([
+    ...(Array.isArray(input?.outOfScope) ? input.outOfScope : []),
+    ...(Array.isArray(input?.protectedPaths) ? input.protectedPaths : [])
+  ]);
+  return {
+    mutationPolicy: input?.mutationPolicy,
+    readOnlyBoundary: boundaryPatterns.length > 0
+      && readOnlyBoundaryTiedToPattern(text, boundaryPatterns)
+  };
+}
 
-export function inferAcceptanceObligations(text, changeMode = "source-change") {
+export function inferAcceptanceObligations(text, changeMode = "source-change", options = {}) {
   const value = normalizedText(text);
   const accessControlText = value
     .replace(/`[^`\n]*`/g, " ")
     .replace(/\b(?:[a-z0-9_.@-]+\/)+[a-z0-9_.@/-]+\b/g, " ");
   const obligations = [];
-  if (changeMode === "read-only" || READ_ONLY_BOUNDARY.test(value)) {
+  if (changeMode === "read-only" || options.mutationPolicy === "forbidden" || options.readOnlyBoundary === true) {
     obligations.push("read-only-evidence");
   }
   const actorAccessControl = includesAny(accessControlText, [
@@ -191,7 +205,6 @@ const GENERATED_ACCEPTANCE_TEXTS = new Set([
   "authorization-deny-case", "tenant-boundary", "tenant-storage-isolation", "invalid-input-rejection", "boundary-case",
   "backward-compatibility", "read-only-evidence", "verification-evidence"
 ].map((obligation) => generatedCriterionForObligation(obligation)));
-
 function acceptanceTaskText(task) {
   return [
     task?.summary,
@@ -227,8 +240,9 @@ function semanticConflictReasons(obligation, task, corpus, criterion) {
 
 /**
  * Surface a concrete existing return contract before implementation starts.
- * This is intentionally source-derived and bounded to exact in-scope files;
- * it does not guess from benchmark scenario names or hidden expectations.
+ * This is intentionally source-derived and bounded to exact known files; it
+ * does not turn the task's initial focus into write authority or guess from
+ * benchmark scenario names and hidden expectations.
  */
 export function acceptanceBaselineGuidance(task, options = {}) {
   if (!options.cwd) return [];
@@ -247,7 +261,11 @@ export function acceptanceSemanticConflicts(task, options = {}) {
     : { ...emptyAcceptanceCorpus(changedFiles.length > 0 ? changedFiles : ["inline.js"]), sourceText: normalizedText(options.sourceText), allText: normalizedText(options.sourceText) };
   if (!corpus.adapter.proofCapable) return [];
   const obligations = task?.acceptanceReceipt?.criteria?.map((criterion) => criterion.obligation)
-    ?? inferAcceptanceObligations(acceptanceTaskText(task), task?.changeMode);
+    ?? inferAcceptanceObligations(
+      acceptanceTaskText(task),
+      task?.changeMode,
+      acceptanceReadOnlyInferenceOptions(task, acceptanceTaskText(task))
+    );
   return uniqueStrings([
     ...obligations.flatMap((obligation) => semanticConflictReasons(obligation, task, corpus)),
     ...(options.cwd ? baselineReturnRepresentationConflicts(acceptanceTaskText(task), options.cwd, corpus.sourceFiles) : [])
@@ -258,7 +276,6 @@ function criterionId(text, obligation, index) {
   const prefix = compactId(obligation ?? "criterion").slice(0, 24);
   return `ac-${String(index + 1).padStart(2, "0")}-${prefix}-${sha256(text).slice(0, 8)}`.slice(0, 80);
 }
-
 export function buildAcceptanceReceipt(input = {}) {
   const changeMode = input.changeMode === "read-only" ? "read-only" : "source-change";
   const baseText = [
@@ -266,12 +283,20 @@ export function buildAcceptanceReceipt(input = {}) {
     input.expectedOutput,
     ...(Array.isArray(input.acceptanceCriteria) ? input.acceptanceCriteria : [])
   ].filter(Boolean).join("\n");
-  const obligations = inferAcceptanceObligations(baseText, changeMode);
+  const obligations = inferAcceptanceObligations(
+    baseText,
+    changeMode,
+    acceptanceReadOnlyInferenceOptions(input, baseText)
+  );
   const texts = uniqueStrings(Array.isArray(input.acceptanceCriteria) ? input.acceptanceCriteria : []);
   const generatedObligations = new Map();
   for (const obligation of obligations) {
     const generated = generatedCriterionForObligation(obligation);
-    if (!texts.some((text) => inferAcceptanceObligations(text, changeMode).includes(obligation))) {
+    if (!texts.some((text) => inferAcceptanceObligations(
+      text,
+      changeMode,
+      acceptanceReadOnlyInferenceOptions(input, text)
+    ).includes(obligation))) {
       texts.push(generated);
       generatedObligations.set(generated, obligation);
     }
@@ -282,17 +307,23 @@ export function buildAcceptanceReceipt(input = {}) {
       : generatedCriterionForObligation("verification-evidence"));
   }
   const acceptanceCriteria = texts.slice(0, MAX_CRITERIA);
+  const durableBehaviorProof = durableBehaviorProofRequired(baseText, changeMode);
   const criteria = acceptanceCriteria.map((text, index) => {
-    const inferred = inferAcceptanceObligations(text, changeMode);
+    const inferred = inferAcceptanceObligations(
+      text,
+      changeMode,
+      acceptanceReadOnlyInferenceOptions(input, text)
+    );
     const obligation = generatedObligations.get(text)
       ?? inferred.find((item) => item !== "verification-evidence" && item !== "backward-compatibility")
-      ?? inferred[0]
+      ?? (isVerificationOnlyCriterion(text) ? "verification-evidence" : undefined)
+      ?? (inferred.includes("backward-compatibility") ? "backward-compatibility" : undefined)
       ?? "requested-behavior";
     return {
       id: criterionId(text, obligation, index),
       hash: sha256(text),
       obligation,
-      priority: CRITICAL_OBLIGATIONS.has(obligation) ? "critical" : "normal",
+      priority: CRITICAL_OBLIGATIONS.has(obligation) || (durableBehaviorProof && obligation !== "verification-evidence") ? "critical" : "normal",
       status: "pending",
       evidence: []
     };
@@ -351,20 +382,30 @@ export function normalizeAcceptanceReceipt(value) {
 
 function normalizeHelperUsage(value) {
   if (!isRecord(value) || !["off", "recommend", "on"].includes(value.mode)) return undefined;
-  const helpers = Array.isArray(value.helpers) ? value.helpers.slice(0, 3).filter(isRecord).map((item) => ({
+  const rawHelpers = Array.isArray(value.helpers) ? value.helpers.slice(0, 3).filter(isRecord) : [];
+  const helpers = rawHelpers.map((item) => ({
     role: HELPER_ROLES.has(item.role) ? item.role : "scout",
     disposition: compactId(item.disposition ?? "unknown"),
     requestRef: HASH.test(String(item.requestRef)) ? item.requestRef : sha256(item.requestRef),
     outputDigest: item.outputDigest === null || HASH.test(String(item.outputDigest)) ? item.outputDigest : null,
     calls: Number.isInteger(item.calls) ? Math.max(0, Math.min(100, item.calls)) : 0,
     tokens: Number.isInteger(item.tokens) ? Math.max(0, Math.min(100_000_000, item.tokens)) : 0
-  })) : [];
-  return { mode: value.mode, used: helpers.some((item) => !["solo", "recommend", "unavailable", "blocked"].includes(item.disposition)), reasonCodes: uniqueStrings(value.reasonCodes).map(compactId).slice(0, 16), helpers, recordedAt: validTimestamp(value.recordedAt) ? value.recordedAt : new Date().toISOString() };
+  }));
+  const used = helpers.some((item) => !["solo", "recommend", "unavailable", "blocked"].includes(item.disposition));
+  const helperDecision = rawHelpers.find((item) => ["dispatch", "skip"].includes(item.decision))?.decision;
+  const decision = ["dispatch", "skip"].includes(value.decision) ? value.decision : helperDecision ?? (used ? "dispatch" : "skip");
+  const rawProjectedSavings = typeof value.projectedSavingsRatio === "number"
+    ? value.projectedSavingsRatio
+    : rawHelpers.find((item) => typeof item.projectedSavingsRatio === "number")?.projectedSavingsRatio;
+  const projectedSavingsRatio = typeof rawProjectedSavings === "number" && Number.isFinite(rawProjectedSavings)
+    ? Math.max(-10, Math.min(1, rawProjectedSavings))
+    : null;
+  return { mode: value.mode, used, decision, projectedSavingsRatio, reasonCodes: uniqueStrings(value.reasonCodes).map(compactId).slice(0, 16), helpers, recordedAt: validTimestamp(value.recordedAt) ? value.recordedAt : new Date().toISOString() };
 }
 
 export function applyAcceptanceHelperUsage(task, input = {}) {
   const receipt = normalizeAcceptanceReceipt(task?.acceptanceReceipt); if (!receipt) return task;
-  const helperUsage = normalizeHelperUsage({ mode: input.mode ?? "off", reasonCodes: input.reasonCodes ?? [], helpers: input.helpers ?? [], recordedAt: input.recordedAt ?? new Date().toISOString() });
+  const helperUsage = normalizeHelperUsage({ mode: input.mode ?? "off", decision: input.decision, projectedSavingsRatio: input.projectedSavingsRatio, reasonCodes: input.reasonCodes ?? [], helpers: input.helpers ?? [], recordedAt: input.recordedAt ?? new Date().toISOString() });
   return { ...task, acceptanceReceipt: { ...receipt, criteria: structuredClone(task.acceptanceReceipt.criteria), helperUsage } };
 }
 
@@ -633,8 +674,8 @@ function hasStructuredCompositeIdentity(sourceText) {
   return jsonTuple || nestedLookup || hasLengthPrefixedIdentityKey(text);
 }
 
-function focusedContractEvidence(obligation, task, corpus, verifierEvidence, criterion) {
-  if (!verifierEvidence || corpus.sourceFiles.length === 0 || corpus.testFiles.length === 0) return undefined;
+function focusedContractEvidence(obligation, task, corpus, verifierEvidence, criterion, cwd) {
+  if (!verifierEvidence || corpus.sourceFiles.length === 0 || !verifierCommandsCoverTests(task, corpus.testFiles, cwd)) return undefined;
   const targets = namedCodeTargets(task, criterion, corpus.sourceText);
   const targetCoverage = targets.length === 0 || targets.every((target) => (
     new RegExp(`\\b${escapeRegex(target.toLowerCase())}\\b`).test(corpus.testText)
@@ -681,7 +722,7 @@ function hasCurrentPassingVerifier(task, currentWorkingTreeDigest) {
   });
 }
 
-function evidenceForObligation(obligation, task, corpus, currentWorkingTreeDigest, criterion) {
+function evidenceForObligation(obligation, task, corpus, currentWorkingTreeDigest, criterion, cwd) {
   const passingVerifier = hasCurrentPassingVerifier(task, currentWorkingTreeDigest);
   const latestVerifyEvidence = latestObservedVerificationEvidence(task?.verifyEvidence);
   const verifyEvidence = meaningfulVerificationCommands(task?.verifyCommands ?? [])
@@ -699,7 +740,7 @@ function evidenceForObligation(obligation, task, corpus, currentWorkingTreeDiges
 
   if (obligation === "read-only-evidence") {
     const readOnlyEvidence = durableContextEvidenceEntries(task);
-    const readOnlyOk = task.changeMode === "read-only"
+    const readOnlyOk = (task.changeMode === "read-only" || task.mutationPolicy === "forbidden")
       && corpus.files.length === 0
       && hasDurableContextEvidence(task);
     if (readOnlyOk) return {
@@ -716,9 +757,9 @@ function evidenceForObligation(obligation, task, corpus, currentWorkingTreeDiges
       ].filter(Boolean).join("\n");
       const combinedText = `${taskText}\n${corpus.allText}`;
       const sourceChangeReadOnlyOk = corpus.files.length > 0
-        && READ_ONLY_BOUNDARY.test(normalizedText(combinedText))
+        && boundaryPatterns.length > 0
+        && readOnlyBoundaryTiedToPattern(combinedText, boundaryPatterns)
         && changedFilesRespectBoundaries(corpus.files, boundaryPatterns)
-        && (boundaryPatterns.length === 0 || pathBoundaryMentioned(combinedText, boundaryPatterns))
         && hasDurableContextEvidence(task);
       if (sourceChangeReadOnlyOk) {
         return {
@@ -732,23 +773,21 @@ function evidenceForObligation(obligation, task, corpus, currentWorkingTreeDiges
     return undefined;
   }
 
-  if (obligation === "verification-evidence" || obligation === "requested-behavior" || obligation === "backward-compatibility") {
-    if (!passingVerifier) return undefined;
-    return verifierEvidence;
-  }
+  const generic = genericCriterionEvidence({ obligation, task, criterion, taskText: acceptanceTaskText(task), corpus, verifierEvidence, passingVerifier, cwd });
+  if (generic.handled) return generic.evidence;
 
   if (!corpus.adapter.proofCapable) return undefined;
 
   if (obligation === "tenant-boundary") {
-    return focusedContractEvidence(obligation, task, corpus, verifierEvidence, criterion);
+    return focusedContractEvidence(obligation, task, corpus, verifierEvidence, criterion, cwd);
   }
 
   if (obligation === "tenant-storage-isolation") {
-    return focusedContractEvidence(obligation, task, corpus, verifierEvidence, criterion);
+    return focusedContractEvidence(obligation, task, corpus, verifierEvidence, criterion, cwd);
   }
 
   if (obligation === "authorization-deny-case") {
-    return focusedContractEvidence(obligation, task, corpus, verifierEvidence, criterion);
+    return focusedContractEvidence(obligation, task, corpus, verifierEvidence, criterion, cwd);
   }
 
   if (obligation === "invalid-input-rejection") {
@@ -761,7 +800,7 @@ function evidenceForObligation(obligation, task, corpus, currentWorkingTreeDiges
       namedTargets: namedCodeTargets(task, criterion, corpus.sourceText),
       provenanceTargets: explicitlyCallableTargets(task, criterion, corpus.sourceText)
     });
-    if (passingVerifier && corpus.sourceFiles.length > 0 && corpus.testFiles.length > 0 && sourceOk && testOk) {
+    if (passingVerifier && corpus.sourceFiles.length > 0 && verifierCommandsCoverTests(task, corpus.testFiles, cwd) && sourceOk && testOk) {
       return {
         ...verifierEvidence,
         kind: "verifier-backed-focused-test",
@@ -779,7 +818,7 @@ function evidenceForObligation(obligation, task, corpus, currentWorkingTreeDiges
     const sourceOk = /math\.ceil|ceil|clamp|min|max|round|zero|return\s+0|\?\?|nullish|falsey|falsy|default|retrylimit|enabled|label/.test(corpus.sourceText)
       || expirySourceOk
       || (passingVerifier && corpus.sourceFiles.length > 0 && testOk);
-    if (passingVerifier && corpus.sourceFiles.length > 0 && corpus.testFiles.length > 0 && sourceOk && testOk) {
+    if (passingVerifier && corpus.sourceFiles.length > 0 && verifierCommandsCoverTests(task, corpus.testFiles, cwd) && sourceOk && testOk) {
       return {
         ...verifierEvidence,
         kind: "verifier-backed-focused-test",
@@ -790,12 +829,12 @@ function evidenceForObligation(obligation, task, corpus, currentWorkingTreeDiges
     return undefined;
   }
 
-  return passingVerifier ? verifierEvidence : undefined;
+  return genericFallbackEvidence({ behavioral: generic.behavioral, corpus, verifierEvidence, passingVerifier });
 }
 
 export function refreshAcceptanceReceipt(task, options = {}) {
   const receipt = normalizeAcceptanceReceipt(task?.acceptanceReceipt);
-  if (!receipt) return { task, missing: [], criticalMissing: [], changed: false };
+  if (!receipt) return { task, missing: [], criticalMissing: [], adapterAbstained: [], changed: false };
   const cwd = options.cwd;
   const changedFiles = uniqueStrings(options.changedFiles ?? task.changedFiles ?? task.observedChangedFiles ?? []);
   const currentWorkingTreeDigest = options.currentWorkingTreeDigest;
@@ -810,7 +849,7 @@ export function refreshAcceptanceReceipt(task, options = {}) {
       criterion.evidence = [];
       const evidence = task?.workingTreeDigestAlgorithm === WORKING_TREE_DIGEST_ALGORITHM
         && isCurrentWorkingTreeDigest(currentWorkingTreeDigest)
-        ? evidenceForObligation(criterion.obligation, task, corpus, currentWorkingTreeDigest, criterion)
+        ? evidenceForObligation(criterion.obligation, task, corpus, currentWorkingTreeDigest, criterion, cwd)
         : undefined;
       if (evidence) addEvidence(criterion, evidence, recordedAt);
       const nextEvidence = (criterion.evidence ?? []).map(evidenceKey);
@@ -818,17 +857,16 @@ export function refreshAcceptanceReceipt(task, options = {}) {
       continue;
     }
     if (criterion.status === "satisfied") continue;
-    const evidence = evidenceForObligation(criterion.obligation, task, corpus, currentWorkingTreeDigest, criterion);
+    const evidence = evidenceForObligation(criterion.obligation, task, corpus, currentWorkingTreeDigest, criterion, cwd);
     if (evidence) changed = addEvidence(criterion, evidence, recordedAt) || changed;
   }
   const missing = receipt.criteria.filter((criterion) => criterion.status !== "satisfied");
-  const criticalMissing = missing.filter((criterion) => criterion.priority === "critical");
+  const passingVerifier = hasCurrentPassingVerifier(task, currentWorkingTreeDigest);
+  const adapterAbstained = missing.filter((criterion) => criterionBehaviorProofDisposition({ obligation: criterion.obligation, task, criterion, taskText: acceptanceTaskText(task), corpus, passingVerifier }) === "unknown");
+  const criticalMissing = missing.filter((criterion) => (criterion.priority === "critical" || criterionRequiresBehavioralProof(task, criterion, acceptanceTaskText(task))
+  ));
   return {
-    task: { ...task, acceptanceReceipt: receipt },
-    receipt,
-    missing,
-    criticalMissing,
-    changed
+    task: { ...task, acceptanceReceipt: receipt }, receipt, missing, criticalMissing, adapterAbstained, changed
   };
 }
 
@@ -850,9 +888,12 @@ export function acceptanceCriticalRecoveryProjection(task, options = {}) {
   const verifierCurrent = hasCurrentPassingVerifier(task, currentWorkingTreeDigest);
   const projections = [];
   for (const criterion of receipt.criteria.filter((item) => item.priority === "critical")) {
+    const disposition = criterionBehaviorProofDisposition({ obligation: criterion.obligation, task, criterion, taskText: acceptanceTaskText(task), corpus, passingVerifier: verifierCurrent });
     const criterionText = (Array.isArray(task?.acceptanceCriteria) ? task.acceptanceCriteria : [])
       .find((text) => typeof text === "string" && sha256(text) === criterion.hash && !GENERATED_ACCEPTANCE_TEXTS.has(text));
-    if (!criterionText || evidenceForObligation(criterion.obligation, task, corpus, currentWorkingTreeDigest, criterion)) continue;
+    if (!criterionText) continue;
+    if (disposition === "unknown") { projections.push({ criterionId: criterion.id, criterionHash: criterion.hash, criterionText: criterionText.slice(0, 700), targets: [], missingDimensions: ["adapter-linkage"], proofHints: ["Add a focused executable test with a direct relative import to the changed source, or configure a deterministic language adapter that resolves this helper/barrel path; then rerun the exact verifier."] }); continue; }
+    if (evidenceForObligation(criterion.obligation, task, corpus, currentWorkingTreeDigest, criterion, cwd)) continue;
     const targets = namedCodeTargets(task, criterion, corpus.sourceText);
     const missingDimensions = [];
     if (!verifierCurrent) missingDimensions.push("current-verifier");
@@ -902,7 +943,7 @@ export function acceptanceReceiptValidationErrors(value) {
   }
   if (value.helperUsage !== undefined) {
     const usage = value.helperUsage;
-    if (!isRecord(usage) || hasUnsupportedField(usage, HELPER_USAGE_FIELDS) || !["off", "recommend", "on"].includes(usage.mode) || typeof usage.used !== "boolean" || !Array.isArray(usage.reasonCodes) || usage.reasonCodes.length > 16 || usage.reasonCodes.some((item) => typeof item !== "string" || compactId(item) !== item) || !Array.isArray(usage.helpers) || usage.helpers.length > 3 || !validTimestamp(usage.recordedAt)) errors.push("acceptanceReceipt helperUsage is invalid");
+    if (!isRecord(usage) || hasUnsupportedField(usage, HELPER_USAGE_FIELDS) || !["off", "recommend", "on"].includes(usage.mode) || typeof usage.used !== "boolean" || (usage.decision !== undefined && !["dispatch", "skip"].includes(usage.decision)) || (usage.projectedSavingsRatio !== undefined && usage.projectedSavingsRatio !== null && (typeof usage.projectedSavingsRatio !== "number" || !Number.isFinite(usage.projectedSavingsRatio) || usage.projectedSavingsRatio < -10 || usage.projectedSavingsRatio > 1)) || !Array.isArray(usage.reasonCodes) || usage.reasonCodes.length > 16 || usage.reasonCodes.some((item) => typeof item !== "string" || compactId(item) !== item) || !Array.isArray(usage.helpers) || usage.helpers.length > 3 || !validTimestamp(usage.recordedAt)) errors.push("acceptanceReceipt helperUsage is invalid");
     else for (const helper of usage.helpers) if (!isRecord(helper) || hasUnsupportedField(helper, HELPER_ENTRY_FIELDS) || !HELPER_ROLES.has(helper.role) || typeof helper.disposition !== "string" || compactId(helper.disposition) !== helper.disposition || !HASH.test(String(helper.requestRef)) || (helper.outputDigest !== null && !HASH.test(String(helper.outputDigest))) || !Number.isInteger(helper.calls) || helper.calls < 0 || helper.calls > 100 || !Number.isInteger(helper.tokens) || helper.tokens < 0 || helper.tokens > 100_000_000) errors.push("acceptanceReceipt helper entry is invalid");
   }
   if (!Array.isArray(value.criteria) || value.criteria.length === 0 || value.criteria.length > MAX_CRITERIA) {

package/packages/piagent-core/extensions/context-engine.js

@@ -14,6 +14,7 @@ import { contextMetricPartition } from "./context-efficiency-metrics.js";
 import { writeContextEfficiencyReport } from "./context-efficiency-report.js";
 import { inspectContextTelemetryIntegrity } from "./context-telemetry-integrity.js";
 import { directExplicitImportLinks, extractJavaScriptModuleImports } from "./context-import-links.js";
+import { queryPathCandidates } from "./context-query-paths.js";
 import { redactSensitiveProjectFileText } from "../security/sensitive-data.js";
 const INDEX_SCHEMA_VERSION = 2;
 const TELEMETRY_SCHEMA_VERSION = 2;
@@ -492,17 +493,6 @@ function tokenizeQuery(query) {
   return [...new Set(terms.map((term) => term.toLowerCase()).filter((term) => !STOP_TERMS.has(foldSearchSignal(term))))].slice(0, 16);
 }
 
-function queryPathCandidates(query) {
-  const pattern = /(?:^|[\s"'`(])((?:\.{0,2}\/)?[\p{L}\p{N}_.@-]+(?:\/[\p{L}\p{N}_.@-]+)+|[\p{L}\p{N}_.@-]+\.[\p{L}\p{N}]{1,8}|\.[\p{L}\p{N}_@-]{1,32})(?=$|[\s"'`),:])/gu;
-  const explicitRoots = /^(?:\.github|app|apps|backend|bin|config|docs|examples|frontend|lib|logs|packages|pages|public|scripts|services|spec|src|test|tests|vendor|__tests__)\//i;
-  return [...String(query ?? "").matchAll(pattern)].flatMap((match) => {
-    const raw = match[1], candidate = normalizeRelative(raw);
-    const explicit = candidate && (raw.startsWith("./") || raw.startsWith("../") || explicitRoots.test(candidate)
-      || candidate.split("/").length >= 3 || /(?:^|\/)(?:\.[^/]+|[^/]+\.[\p{L}\p{N}]{1,8})$/u.test(candidate));
-    return explicit ? [candidate] : [];
-  });
-}
-
 function ftsQuery(terms) {
   return terms.map((term) => `"${term.replaceAll('"', '""')}"`).join(" OR ");
 }

package/packages/piagent-core/extensions/context-index-policy.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { resolveProjectProfileDocument } from "../capabilities/project-profile.js";
+import { WORKSPACE_PRIVATE_STATE_PATTERNS } from "./workspace-evidence-roots.js";
 
 const DEFAULT_CONTEXT_INDEX_PATH = ".pi/context-index.json";
 const CONTEXT_ENGINE_STATE_PATTERN = ".pi/piagent-state/**";
@@ -67,17 +68,20 @@ export function effectiveProtectedPaths(policy = {}, profile = {}) {
   const contextIndexPath = contextIndexStatePath(profile);
   return {
     readProtectedPaths: uniqueStrings([
+      ...WORKSPACE_PRIVATE_STATE_PATTERNS,
       ...baseReadProtectedPaths,
       ...profileProtectedPaths,
       contextIndexPath
     ]),
     writeProtectedPaths: uniqueStrings([
+      ...WORKSPACE_PRIVATE_STATE_PATTERNS,
       ...policyProtectedPaths,
       ...profileProtectedPaths,
       ...readOnlyPaths,
       contextIndexPath
     ]),
     shellProtectedPaths: uniqueStrings([
+      ...WORKSPACE_PRIVATE_STATE_PATTERNS,
       ...baseReadProtectedPaths,
       ...profileShellProtectedPaths,
       ...readOnlyPaths,

package/packages/piagent-core/extensions/context-query-paths.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+
+function normalizeRelative(value) {
+  return String(value ?? "").replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+/g, "/");
+}
+
+function safeProjectRelativeQueryPath(raw) {
+  const candidate = normalizeRelative(raw);
+  if (!candidate || candidate.length > 512 || path.posix.isAbsolute(candidate)) return undefined;
+  if (candidate.split("/").some((segment) => !segment || segment === "." || segment === "..")) return undefined;
+  return candidate;
+}
+
+function safeGlobSegment(segment) {
+  let bracketDepth = 0;
+  let braceDepth = 0;
+  for (const character of segment) {
+    if (character === "[") {
+      if (++bracketDepth > 1) return false;
+    } else if (character === "]") {
+      if (--bracketDepth < 0) return false;
+    } else if (character === "{") {
+      if (++braceDepth > 1) return false;
+    } else if (character === "}") {
+      if (--braceDepth < 0) return false;
+    } else if ((character === "," && braceDepth === 0) || (character === "!" && bracketDepth === 0)) {
+      return false;
+    }
+  }
+  return bracketDepth === 0 && braceDepth === 0;
+}
+
+function safeProjectRelativeGlob(raw) {
+  const candidate = safeProjectRelativeQueryPath(String(raw ?? "").replace(/[.,]+$/u, ""));
+  if (!candidate || !candidate.includes("/") || !/[*?\[\]{}]/u.test(candidate)) return undefined;
+  if (!/^[\p{L}\p{N}_.@*?{}\[\]!,-]+(?:\/[\p{L}\p{N}_.@*?{}\[\]!,-]+)+$/u.test(candidate)) return undefined;
+  return candidate.split("/").every(safeGlobSegment) ? candidate : undefined;
+}
+
+export function queryPathCandidates(query) {
+  const pattern = /(?:^|[\s"'`(])((?:\.{0,2}\/)?[\p{L}\p{N}_.@-]+(?:\/[\p{L}\p{N}_.@-]+)+|[\p{L}\p{N}_.@-]+\.[\p{L}\p{N}]{1,8}|\.[\p{L}\p{N}_@-]{1,32})(?=$|[\s"'`),:])/gu;
+  const globPattern = /(?:^|[\s"'(\x60=,:])((?:\.\/)?[\p{L}\p{N}_.@*?{}\[\]!,-]+(?:\/[\p{L}\p{N}_.@*?{}\[\]!,-]+)+)(?=$|[\s"'\x60),:;])/gu;
+  const explicitRoots = /^(?:\.github|app|apps|backend|bin|config|docs|examples|frontend|lib|logs|packages|pages|public|scripts|services|spec|src|test|tests|vendor|__tests__)\//i;
+  const text = String(query ?? "");
+  const candidates = [...text.matchAll(pattern)].flatMap((match) => {
+    const raw = match[1], candidate = safeProjectRelativeQueryPath(raw);
+    const explicit = candidate && (raw.startsWith("./") || explicitRoots.test(candidate)
+      || candidate.split("/").length >= 3 || /(?:^|\/)(?:\.[^/]+|[^/]+\.[\p{L}\p{N}]{1,8})$/u.test(candidate));
+    return explicit ? [{ candidate, index: match.index ?? 0 }] : [];
+  });
+  for (const match of text.matchAll(globPattern)) {
+    const candidate = safeProjectRelativeGlob(match[1]);
+    if (candidate) candidates.push({ candidate, index: match.index ?? 0 });
+  }
+  candidates.sort((left, right) => left.index - right.index);
+  return [...new Set(candidates.map((entry) => entry.candidate))];
+}

package/packages/piagent-core/extensions/criterion-context-pack.js

@@ -36,7 +36,20 @@ function executablePlannedTest(candidate, plannedPaths, plannedSelectionComplete
     && plannedSelectionComplete
     && acceptanceLanguageAdapterForPath(candidate.path).disposition === "supported"
     && !/\.d\.[cm]?ts$/i.test(candidate.path)
-    && /(?:^|[._-])(?:test|tests|spec)(?:[._-]|$)/i.test(basename);
+    && /(?:^|[._-])(?:assertions?|test|tests|spec)(?:[._-]|$)/i.test(basename);
+}
+
+function explicitFocusedTestNavigation(text) {
+  const clauses = String(text ?? "").split(/(?:[;\n]+|(?<=[.!?])\s+)/).map((clause) => clause.trim()).filter(Boolean);
+  return clauses.some((clause) => {
+    const positive = /\b(?:add|author|create|include|prove|update|write)\b.{0,80}\b(?:assertions?|coverage|specs?|tests?)\b/i.test(clause)
+      || /\b(?:behavioral|deterministic|directly[- ]linked|durable|executable|focused|integration|live|nearest|scoped)\s+(?:assertions?|coverage|specs?|tests?)\b/i.test(clause)
+      || /\bensure\b.{0,100}\b(?:cover(?:ed|age)?|test(?:ed|s)?|specs?|assert(?:ed|ions?))\b/i.test(clause)
+      || /\bensure\b.{0,80}\b(?:assertions?|coverage|specs?|tests?)\b.{0,60}\bcover(?:ed|s|age)?\b/i.test(clause);
+    const negative = /\b(?:do\s+not|don't|dont|never|without)\b.{0,100}\b(?:assertions?|coverage|specs?|tests?)\b/i.test(clause)
+      || /\b(?:assertions?|coverage|specs?|tests?)\b.{0,30}\b(?:not|never|unchanged|untouched)\b/i.test(clause);
+    return positive && !negative;
+  });
 }
 
 const DIRECT_EXPLICIT_LINK_KINDS = new Set(["explicit-imports-candidate", "candidate-imports-explicit"]);
@@ -281,9 +294,9 @@ export function composeCriterionContextEntries(input = {}, options = {}) {
   // establish singleton cardinality, and only a test-shaped JS/TS filename is
   // eligible. This remains navigation context; acceptance still depends on a
   // changed live assertion and final verification.
-  if (!selected.some((entry) => testPath(entry.path))) {
+  if (!selected.some((entry) => testPath(entry.path)) && explicitFocusedTestNavigation(criteriaText)) {
     const scopedTests = values.filter((candidate) => executablePlannedTest(candidate, plannedPaths, input.plannedSelectionComplete === true));
-    if (scopedTests.length === 1) add(scopedTests[0], "Sole proven scoped test target (navigation context; not acceptance proof)");
+    if (scopedTests.length === 1) add(scopedTests[0], "Operator-requested sole scoped test target (navigation context; not acceptance proof)");
   }
 
   relatedTests

package/packages/piagent-core/extensions/criterion-graph.js

@@ -114,7 +114,10 @@ function targetHintsFor(obligation, scope, mode) {
     const stem = basename.replace(/\.[a-z0-9]+$/i, "");
     return text.includes(normalized) || (basename.length >= 3 && text.includes(basename)) || (stem.length >= 4 && text.includes(stem));
   });
-  return (matched.length > 0 ? matched : scope).slice(0, 4);
+  const requestedTestScopes = /\btests?\b/i.test(text)
+    ? scope.filter((candidate) => /(?:^|\/)(?:test|tests|spec|__tests__)(?:\/|$)|[._-](?:test|spec)\.[cm]?[jt]sx?$/i.test(candidate))
+    : [];
+  return (matched.length > 0 ? [...new Set([...matched, ...requestedTestScopes])] : scope).slice(0, 4);
 }
 
 function criterionLabel(obligation) {

package/packages/piagent-core/extensions/fallback-base-policy.ts

@@ -0,0 +1,101 @@
+import type { BasePolicy, ResolvedOrchestrationPolicy } from "./guard-types.ts";
+
+/**
+ * Fail-closed policy used only when the packaged JSON policy cannot be read.
+ * Tests lock this copy to the file-backed policy so recovery never becomes the
+ * less restrictive path.
+ */
+export function fallbackBasePolicy(
+  contextIndexFile: string,
+  orchestrationPolicy: ResolvedOrchestrationPolicy
+): BasePolicy {
+  return {
+    protectedPaths: [
+      ".git/**", "**/.git/**", "**/.hg/**", "**/.svn/**", "**/.pi/**",
+      "**/.aws/**", "**/.azure/**", "**/.docker/**", "**/.gnupg/**", "**/.kube/**", "**/.ssh/**",
+      "**/.git-credentials", "**/.netrc", "**/.npmrc", "**/.pypirc",
+      "**/auth.json", "**/credential.json", "**/credentials.json", "**/secret.json", "**/secrets.json", "**/token.json", "**/tokens.json",
+      "**/.env", "**/.env.*", "**/node_modules/**", "**/dist/**", ".pi/piagent-state/**", ".pi/settings.json",
+      ".pi/piagent-profile.json", ".pi/piagent-profile.lock.json", contextIndexFile
+    ],
+    shellProtectedPaths: [
+      ".git/**", "**/.git/**", "**/.hg/**", "**/.svn/**", "**/.pi/**",
+      "**/.aws/**", "**/.azure/**", "**/.docker/**", "**/.gnupg/**", "**/.kube/**", "**/.ssh/**",
+      "**/.git-credentials", "**/.netrc", "**/.npmrc", "**/.pypirc",
+      "**/auth.json", "**/credential.json", "**/credentials.json", "**/secret.json", "**/secrets.json", "**/token.json", "**/tokens.json",
+      "**/.env", "**/.env.*", ".pi/piagent-state/**", ".pi/settings.json", ".pi/piagent-profile.json",
+      ".pi/piagent-profile.lock.json", contextIndexFile
+    ],
+    blockedCommandPatterns: ["rm -rf /", "rm -rf ~", "rm -rf $HOME", "git reset --hard", "git clean -fd", "sudo ", "chmod -R 777"],
+    requireConfirmationPatterns: ["deploy", "release", "publish", "migration", "gh pr merge", "git push"],
+    defaultRequiredContext: ["AGENTS.md", "README.md"],
+    permissionProfiles: {
+      defaultMode: "workspace-write",
+      allowedModes: ["read-only", "workspace-write", "trusted-full-access"]
+    },
+    execPolicy: {
+      defaultMode: "enforce",
+      bannedPrefixSuggestions: [
+        ["python"], ["python3"], ["node"], ["node", "-e"], ["bash"], ["bash", "-lc"],
+        ["sh"], ["sh", "-c"], ["zsh"], ["zsh", "-lc"], ["git"], ["sudo"], ["env"]
+      ],
+      rules: [{
+        id: "prompt-git-add-broad",
+        action: "prompt",
+        match: "regex",
+        value: "(?:^|\\s)git\\s+(?:-C\\s+\\S+\\s+)?add\\s+(?:(?:--all|-A)(?:\\s+(?:\\.|:/))?|--\\s+(?:\\.|:/)|(?:\\.|:/))(?:\\s|$)",
+        reason: "Broad git staging can include unrelated or sensitive changes; inspect git status/diff and confirm the exact scope first."
+      }]
+    },
+    contextBudget: {
+      defaultMode: "enforce",
+      contextDeltaShadow: "sample",
+      maxContextFileChars: 50000,
+      maxMemoryFileChars: 20000,
+      maxManifestFiles: 80,
+      warnFragmentChars: 4000
+    },
+    toolRegistry: {
+      defaultMode: "advisory",
+      alwaysAllowedTools: [
+        "piagent_tools", "piagent_context_engine", "piagent_context", "piagent_permission_status",
+        "piagent_exec_policy_check", "piagent_context_budget", "piagent_tool_policy_check",
+        "piagent_task_gate_check", "piagent_usage_snapshot", "piagent_orchestration_policy",
+        "piagent_memory_status", "piagent_memory_note", "piagent_memory_search",
+        "piagent_memory_citation_record", "piagent_context_index_status", "piagent_context_index_record",
+        "piagent_context_index_search", "piagent_profile_options", "piagent_profile_apply",
+        "piagent_profile_tech_options", "piagent_profile_tech_apply", "piagent_profile_tech_context_record",
+        "piagent_project_onboarding_record", "piagent_task_start", "piagent_task_progress",
+        "piagent_source_checkout", "piagent_context_record", "piagent_verify_record", "piagent_trace_record"
+      ],
+      toolCapabilities: {
+        bash: ["shell"], shell: ["shell"], exec: ["shell"],
+        read: ["filesystem-readonly"], grep: ["filesystem-readonly"], find: ["filesystem-readonly"], ls: ["filesystem-readonly"],
+        write: ["filesystem-write"], edit: ["filesystem-write"], apply_patch: ["filesystem-write"],
+        browser: ["browser"], github: ["github"]
+      }
+    },
+    externalActionPolicy: {
+      defaultMode: "enforce",
+      providerKeywords: [
+        "github", "gitlab", "bitbucket", "vercel", "netlify", "cloudflare", "aws", "gcp", "azure",
+        "slack", "teams", "jira", "linear", "notion", "figma", "stripe", "supabase", "firebase"
+      ],
+      writeVerbs: [
+        "add", "approve", "archive", "assign", "close", "comment", "create", "delete", "deploy",
+        "dispatch", "merge", "open", "post", "publish", "push", "release", "remove", "reopen", "run",
+        "send", "submit", "trigger", "update", "upload", "write"
+      ],
+      safeVerbs: ["fetch", "find", "get", "inspect", "list", "read", "search", "show", "view"]
+    },
+    finalGate: {
+      defaultMode: "enforce",
+      requireTaskContract: true,
+      requireContextManifest: true,
+      requireVerifyEvidence: true,
+      requireTrace: true,
+      requirePassingVerify: true
+    },
+    orchestrationPolicy
+  };
+}