@piagent/platform 1.6.0 → 1.7.1

package/packages/piagent-core/extensions/acceptance-test-binding-evidence.js

@@ -23,7 +23,13 @@ export function boundRejectionTestEvidence(input) {
     || input.requestedErrors.some((name) => assertion.errorClasses.includes(name));
   const bindingGroups = input.bindings.map((binding) => {
     const allAssertions = (binding.testBindings ?? []).flatMap(assertionsForBinding);
-    return { binding, allAssertions, assertions: allAssertions.filter(requestedError) };
+    const assertions = allAssertions.filter(requestedError);
+    return {
+      binding, allAssertions, assertions,
+      invalidArgumentIndices: [...new Set(assertions.flatMap((item) => item.invalidArgumentIndices ?? []))]
+        .sort((left, right) => left - right),
+      invalidArgumentPartitions: assertions.flatMap((item) => item.invalidArgumentPartitions ?? [])
+    };
   });
   const testCodes = input.testCodeEntries.length > 0
     ? input.testCodeEntries.map((entry) => entry.code) : [input.fallbackTestCode];
@@ -56,5 +62,17 @@ export function boundRejectionTestEvidence(input) {
     const matches = [...input.bodyMaps.values()].filter((bodies) => bodies.has(target));
     return assertionModesMatch(items, [`*.${target}`], matches.length === 1 ? callableAssertionMode(matches[0], target) : undefined);
   });
-  return { assertions, mappingOk, modeOk, targetOk };
+  return {
+    assertions, mappingOk, modeOk, targetOk,
+    bindingArgumentRequirements: bindingGroups.map(({ binding, invalidArgumentIndices, invalidArgumentPartitions }) => ({
+      sourcePath: binding.sourcePath,
+      sourceName: binding.sourceName,
+      invalidArgumentIndices,
+      invalidArgumentPartitions: [...new Set(invalidArgumentPartitions.map((item) => item.index))].map((index) => ({
+        index,
+        partitions: [...new Set(invalidArgumentPartitions.filter((item) => item.index === index)
+          .flatMap((item) => item.partitions ?? []))].sort()
+      }))
+    }))
+  };
 }

package/packages/piagent-core/extensions/acceptance-test-bindings.js

@@ -0,0 +1,86 @@
+function escapeRegex(value) {
+  return String(value ?? "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function assertionCarrierBindings(testText) {
+  const bindings = [];
+  const add = (name, start, end) => {
+    if (name) bindings.push({ name: name.toLowerCase(), start, end });
+  };
+  for (const match of testText.matchAll(/\bimport\s+([a-z_$][a-z0-9_$]*)\s+from\s+__pi_node_assert_module_literal__\s*;?/gi)) {
+    add(match[1], match.index, match.index + match[0].length);
+  }
+  for (const match of testText.matchAll(/\bimport\s+\*\s+as\s+([a-z_$][a-z0-9_$]*)\s+from\s+__pi_node_assert_module_literal__\s*;?/gi)) {
+    add(match[1], match.index, match.index + match[0].length);
+  }
+  for (const match of testText.matchAll(/\bimport\s*\{([^}]{1,500})\}\s*from\s+__pi_node_assert_module_literal__\s*;?/gi)) {
+    for (const item of match[1].split(",")) {
+      const strict = item.trim().match(/^strict(?:\s+as\s+([a-z_$][a-z0-9_$]*))?$/i);
+      if (strict) add(strict[1] ?? "strict", match.index, match.index + match[0].length);
+    }
+  }
+  for (const match of testText.matchAll(/\bconst\s+([a-z_$][a-z0-9_$]*)\s*=\s*require\s*\(\s*__pi_node_assert_module_literal__\s*\)(?:\s*\.\s*strict)?\s*;?/gi)) {
+    add(match[1], match.index, match.index + match[0].length);
+  }
+  for (const match of testText.matchAll(/\bconst\s*\{\s*strict\s*:\s*([a-z_$][a-z0-9_$]*)\s*\}\s*=\s*require\s*\(\s*__pi_node_assert_module_literal__\s*\)\s*;?/gi)) {
+    add(match[1], match.index, match.index + match[0].length);
+  }
+  return bindings.slice(0, 8);
+}
+
+export const TEST_RUNNER_EXPORT_KINDS = new Map([
+  ["test", "test"], ["it", "test"], ["describe", "suite"], ["suite", "suite"]
+]);
+
+export function testRunnerBindings(testText) {
+  const bindings = [];
+  const add = (name, kind, start, end) => {
+    if (name && kind) bindings.push({ name: name.toLowerCase(), kind, start, end });
+  };
+  for (const match of testText.matchAll(/\bimport\s+([a-z_$][a-z0-9_$]*)(?:\s*,\s*\{[^}]{1,500}\})?\s+from\s+__pi_node_test_module_literal__\s*;?/gi)) {
+    add(match[1], "test", match.index, match.index + match[0].length);
+  }
+  for (const match of testText.matchAll(/\bimport\s+(?:[a-z_$][a-z0-9_$]*\s*,\s*)?\{([^}]{1,500})\}\s+from\s+__pi_node_test_module_literal__\s*;?/gi)) {
+    for (const raw of match[1].split(",")) {
+      const item = raw.trim().match(/^(test|it|describe|suite)(?:\s+as\s+([a-z_$][a-z0-9_$]*))?$/i);
+      if (item) add(item[2] ?? item[1], TEST_RUNNER_EXPORT_KINDS.get(item[1].toLowerCase()), match.index, match.index + match[0].length);
+    }
+  }
+  for (const match of testText.matchAll(/\bconst\s+([a-z_$][a-z0-9_$]*)\s*=\s*require\s*\(\s*__pi_node_test_module_literal__\s*\)\s*;?/gi)) {
+    add(match[1], "test", match.index, match.index + match[0].length);
+  }
+  for (const match of testText.matchAll(/\bconst\s+([a-z_$][a-z0-9_$]*)\s*=\s*require\s*\(\s*__pi_node_test_module_literal__\s*\)\s*\.\s*(test|it|describe|suite)\s*;?/gi)) {
+    add(match[1], TEST_RUNNER_EXPORT_KINDS.get(match[2].toLowerCase()), match.index, match.index + match[0].length);
+  }
+  for (const match of testText.matchAll(/\bconst\s*\{([^}]{1,500})\}\s*=\s*require\s*\(\s*__pi_node_test_module_literal__\s*\)\s*;?/gi)) {
+    for (const raw of match[1].split(",")) {
+      const item = raw.trim().match(/^(test|it|describe|suite)(?:\s*:\s*([a-z_$][a-z0-9_$]*))?$/i);
+      if (item) add(item[2] ?? item[1], TEST_RUNNER_EXPORT_KINDS.get(item[1].toLowerCase()), match.index, match.index + match[0].length);
+    }
+  }
+  return bindings.slice(0, 16);
+}
+
+export function importedCallableBindingIsStable(testText, binding, bindings) {
+  const escaped = escapeRegex(binding.name);
+  const withoutDeclaration = `${testText.slice(0, binding.start)}${" ".repeat(binding.end - binding.start)}${testText.slice(binding.end)}`;
+  if (bindings.filter((candidate) => candidate.name === binding.name).length !== 1) return false;
+  if (new RegExp(`\\b(?:const|let|var|function|class)\\s+${escaped}\\b|\\bfunction\\b[^({]{0,200}\\([^)]*\\b${escaped}\\b|\\bcatch\\s*\\([^)]*\\b${escaped}\\b|(?:\\([^)]*\\b${escaped}\\b[^)]*\\)|\\b${escaped})\\s*=>`, "i").test(withoutDeclaration)) return false;
+  if (new RegExp(`(?<![.$a-z0-9_])${escaped}\\b\\s*(?:(?<![=!<>])=(?!=|>)|\\+\\+|--|[+*/%&|^-]=)|(?:\\+\\+|--)\\s*\\b${escaped}\\b`, "i").test(withoutDeclaration)) return false;
+  if (new RegExp(`\\b(?:const|let|var)\\s+[a-z_$][a-z0-9_$]*\\s*=\\s*${escaped}\\b|\\b(?:const|let|var)\\s*\\{[^}\\n]{0,500}\\}\\s*=\\s*${escaped}\\b`, "i").test(withoutDeclaration)) return false;
+  if (new RegExp(`(?<![.$a-z0-9_])[a-z_$][a-z0-9_$]*\\s*(?<![=!<>])=(?!=|>)\\s*${escaped}\\b`, "i").test(withoutDeclaration)) return false;
+  const member = `${escaped}\\s*(?:\\.\\s*[a-z_$][a-z0-9_$]*|\\[[^\\]]{1,300}\\])`;
+  if (new RegExp(`\\b${member}\\s*(?:=|\\+\\+|--|[+*/%&|^-]=|(?:&&|\\|\\||\\?\\?)=)|(?:\\+\\+|--)\\s*\\b${member}|\\bdelete\\s+${escaped}\\s*(?:\\.|\\[)|\\b${escaped}\\s*\\.\\s*__(?:definegetter|definesetter)__\\s*\\(`, "i").test(withoutDeclaration)) return false;
+  if (new RegExp(`(?:\\{[^}\\n]{0,500}\\b${member}[^}\\n]{0,500}\\}|\\[[^\\]\\n]{0,500}\\b${member}[^\\]\\n]{0,500}\\])\\s*=|\\bfor(?:\\s+await)?\\s*\\(\\s*(?:${member}|\\{[^}\\n]{0,500}\\b${member}[^}\\n]{0,500}\\}|\\[[^\\]\\n]{0,500}\\b${member}[^\\]\\n]{0,500}\\])\\s+(?:of|in)\\b`, "i").test(withoutDeclaration)) return false;
+  if (new RegExp(`\\b(?:object|reflect)\\s*\\.\\s*[a-z_$][a-z0-9_$]*\\s*\\(\\s*${escaped}\\s*[,)]|\\b[a-z_$][a-z0-9_$.]*\\s*\\(\\s*${escaped}\\s*[,)]`, "i").test(withoutDeclaration)) return false;
+  for (const match of withoutDeclaration.matchAll(new RegExp(`\\b${escaped}\\b`, "gi"))) {
+    const suffix = withoutDeclaration.slice(match.index + match[0].length);
+    if (/^\s*\(/.test(suffix) || /^\s*\.\s*[a-z_$][a-z0-9_$]*\s*\(/i.test(suffix)) continue;
+    return false;
+  }
+  return true;
+}
+
+export function assertionCarrierIsStable(testText, binding) {
+  return importedCallableBindingIsStable(testText, binding, assertionCarrierBindings(testText));
+}

package/packages/piagent-core/extensions/acceptance-tuple-shapes.js

@@ -0,0 +1,12 @@
+// Closed literal shapes used by the tuple evidence reader. These inspect
+// already-sanitized text and parsed argument ranges; they never run test code.
+export const INVALID_DATE_CONSTRUCTION = /^new\s+date\s*\(\s*(?:undefined|-?(?:number\.)?(?:nan|positive_infinity|negative_infinity|infinity)|__pi_(?:empty|whitespace|unparseable_date)_string_literal__)\s*\)$/i;
+
+export function tupleRegistrationIsClosed(args) {
+  if (!/^(?:async\s+)?\(\s*\)\s*=>/.test(args.at(-1)?.text ?? "")) return false;
+  if (args.length === 2) return true;
+  if (args.length !== 3 || !/^\{[^{}]*\}$/.test(args[1].text)) return false;
+  const fields = args[1].text.slice(1, -1).split(",").map((value) => value.trim());
+  if (fields.at(-1) === "") fields.pop();
+  return new Set(fields).size === fields.length && fields.every((field) => /^(?:skip|todo)\s*:\s*false$/.test(field));
+}

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

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { resolveWorkflowId, workflowIdFromCommand, workflowOption } from "./workflow-catalog.ts";
 import {
   contextIndexExcludeDigest,
   contextIndexExcludePolicyVersion,
@@ -14,6 +15,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 +494,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 ");
 }
@@ -525,20 +516,24 @@ export function classifyContextTask(prompt) {
   const folded = foldSearchSignal(text);
   const paths = queryPathCandidates(text);
   const terms = tokenizeQuery(text);
-  let workflow = "task";
-  if (/^\/?(?:scout|review|plan|discuss)\b/.test(lower)) workflow = lower.match(/^\/?([a-z-]+)/)?.[1] ?? "task";
-  if (/\b(onboard|profile setup|first-read|cau hinh profile|khoi tao project)\b/.test(folded)) workflow = "onboard";
-  if (/^\/?(?:commit|release|publish|deploy)\b/.test(folded) || /\b(?:pull request|publish|deploy|phat hanh|trien khai)\b/.test(folded)
-    || /\b(?:after|before|create|cut|merge|open|prepare|push|run|ship|tag|version)\b.{0,40}\b(?:commit|pr|release)\b/.test(folded)) workflow = "release";
+  const leadingWorkflow = resolveWorkflowId(lower.match(/^\/?([a-z][a-z-]*)\b/)?.[1]);
+  const workflowId = workflowIdFromCommand(text) ?? leadingWorkflow;
+  const explicitWorkflow = workflowOption(workflowId);
+  let workflow = explicitWorkflow?.contextWorkflow ?? "task";
+  if (!explicitWorkflow && /\b(onboard|profile setup|first-read|cau hinh profile|khoi tao project)\b/.test(folded)) workflow = "onboard";
+  if (!explicitWorkflow && (/^\/?(?:release|publish|deploy)\b/.test(folded) || /\b(?:pull request|publish|deploy|phat hanh|trien khai)\b/.test(folded)
+    || /\b(?:after|before|create|cut|merge|open|prepare|push|run|ship|tag|version)\b.{0,40}\b(?:commit|pr|release)\b/.test(folded))) workflow = "release";
   const usageIntent = /^\/?(?:usage|session)\b/.test(lower)
     || /\b(?:show|check|view|report|current|session|how many)\b.{0,48}\b(?:usage|tokens?|cost|context stats|efficiency)\b/.test(lower)
     || /\b(?:usage|tokens?|cost|context stats|efficiency)\b.{0,48}\b(?:show|check|view|report|current|session)\b/.test(lower)
     || /\b(?:xem|kiem tra|bao cao|hien tai|phien)\b.{0,48}\b(?:usage|token|chi phi|context)\b/.test(folded);
-  if (usageIntent) workflow = "usage";
+  if (!explicitWorkflow && usageIntent) workflow = "usage";
   const highRisk = /\b(auth|authorization|credential|database|deploy|encryption|migration|payment|permission|production|release|secret|security|token|bao mat|phan quyen|xac thuc|du lieu|co so du lieu|thanh toan|ma hoa|trien khai|phat hanh)\b/.test(folded);
   const tiny = text.length < 220 && (paths.length > 0 || /\b(rename|typo|label|copy|one line|small|doi ten|sua chu|nhan|mot dong|nho)\b/.test(folded));
   return {
     workflow,
+    workflowId,
+    changeMode: explicitWorkflow?.changeMode ?? "unknown",
     lane: highRisk ? "high-risk" : tiny ? "tiny" : "normal",
     terms,
     paths,

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,97 @@ 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 GENERIC_TEST_CONSTRAINT_TERMS = new Set([
+  "all", "any", "assertion", "assertions", "change", "changing", "coverage", "current", "do", "dont", "edit", "editing",
+  "existing", "inspect", "inspecting", "keep", "leave", "modify", "modifying", "never", "not", "our", "please", "read", "reading",
+  "run", "running", "spec", "specs", "test", "tests", "the", "these", "those", "touch", "touching", "update", "updating", "without",
+  "write", "writing"
+]);
+
+function normalizedConstraintTerm(value) {
+  const term = String(value ?? "").toLowerCase();
+  if (term.endsWith("ies") && term.length > 4) return `${term.slice(0, -3)}y`;
+  if (term.endsWith("s") && term.length > 4) return term.slice(0, -1);
+  return term;
+}
+
+function testConstraintAppliesToPath(scope, filePath) {
+  if (textExplicitlyReferencesPath(scope, filePath)) return true;
+  const qualifierGroups = String(scope ?? "").split(/\b(?:or|and)\b/iu).map((group) => (
+    group.match(/[\p{L}\p{N}_-]+/gu)?.map(normalizedConstraintTerm)
+      .filter((term) => term && !GENERIC_TEST_CONSTRAINT_TERMS.has(term)) ?? []
+  ));
+  if (qualifierGroups.some((qualifiers) => qualifiers.length === 0)) return true;
+  const targetTerms = new Set(String(filePath ?? "").match(/[\p{L}\p{N}_-]+/gu)?.flatMap((part) => (
+    part.split(/[_-]+/).map(normalizedConstraintTerm)
+  )) ?? []);
+  return qualifierGroups.some((qualifiers) => qualifiers.every((term) => targetTerms.has(term)));
+}
+
+function immediateTestStateScope(clause, nounIndex) {
+  const prefix = clause.slice(0, nounIndex);
+  const segment = prefix.split(/[,;:.!?]/u).at(-1)?.trim() ?? "";
+  const afterControl = segment.match(/\b(?:keep|leave)\b(?<scope>.*)$/iu)?.groups?.scope?.trim() ?? segment;
+  const connectorTail = afterControl.match(/(?<scope>[\p{L}\p{N}_-]+(?:\s+(?:or|and)\s+[\p{L}\p{N}_-]+)+)\s*$/iu)?.groups?.scope;
+  if (connectorTail) return connectorTail;
+  return afterControl.match(/([\p{L}\p{N}_-]+)\s*$/u)?.[1] ?? "";
+}
+
+function explicitTestNavigationProhibited(text, filePath) {
+  const clauses = String(text ?? "").split(/(?:[;\n]+|(?<=[.!?])\s+)/).map((clause) => clause.trim()).filter(Boolean);
+  return clauses.some((clause) => {
+    const negativeAction = /\b(?:do\s+not|don't|dont|never|must\s+not|cannot|can't)\s+(?:(?:also|directly|ever|just)\s+){0,2}(?:change|edit|inspect|modify|read|run|touch|update|write)\w*\b(?<scope>.{0,50}?)\b(?:assertions?|coverage|specs?|tests?)\b/giu;
+    for (const match of clause.matchAll(negativeAction)) {
+      if (testConstraintAppliesToPath(match.groups?.scope ?? "", filePath)) return true;
+    }
+    const withoutAction = /\bwithout\s+(?:(?:also|directly|ever|just)\s+){0,2}(?:changing|editing|inspecting|modifying|reading|running|touching|updating|writing)\b(?<scope>.{0,50}?)\b(?:assertions?|coverage|specs?|tests?)\b/giu;
+    for (const match of clause.matchAll(withoutAction)) {
+      const localPrefix = clause.slice(0, match.index).split(/[,;:]|\b(?:but|while|whereas|and\s+then)\b/iu).at(-1) ?? "";
+      if (/\b(?:do\s+not|don't|dont|never|must\s+not|cannot|can't)\b/iu.test(localPrefix)) continue;
+      if (testConstraintAppliesToPath(match.groups?.scope ?? "", filePath)) return true;
+    }
+    const withoutTestChanges = /\bwithout\s+(?:any\s+)?(?<scope>.{0,40}?)\b(?:assertion|coverage|spec|test)s?\s+changes?\b/giu;
+    for (const match of clause.matchAll(withoutTestChanges)) {
+      const localPrefix = clause.slice(0, match.index).split(/[,;:]|\b(?:but|while|whereas|and\s+then)\b/iu).at(-1) ?? "";
+      if (/\b(?:do\s+not|don't|dont|never|must\s+not|cannot|can't)\b/iu.test(localPrefix)) continue;
+      if (testConstraintAppliesToPath(match.groups?.scope ?? "", filePath)) return true;
+    }
+    const noTestChanges = [
+      /\bno\s+changes?\s+to\s+(?<scope>.{0,40}?)\b(?:assertion|coverage|spec|test)s?\b/giu,
+      /\bno\s+(?<scope>.{0,40}?)\b(?:assertion|coverage|spec|test)s?\s+changes?\b/giu
+    ];
+    for (const pattern of noTestChanges) {
+      for (const match of clause.matchAll(pattern)) {
+        if (testConstraintAppliesToPath(match.groups?.scope ?? "", filePath)) return true;
+      }
+    }
+    const testStatePatterns = [
+      /\b(?:assertions?|coverage|specs?|tests?)\b.{0,30}\b(?:unchanged|untouched)\b/giu,
+      /\b(?:assertions?|coverage|specs?|tests?)\b.{0,30}\b(?:not|never)\b.{0,15}\b(?:change|edit|inspect|modify|read|run|touch|update|write)\w*\b/giu
+    ];
+    for (const pattern of testStatePatterns) {
+      for (const match of clause.matchAll(pattern)) {
+        if (testConstraintAppliesToPath(immediateTestStateScope(clause, match.index), filePath)) return true;
+      }
+    }
+    return false;
+  });
 }
 
 const DIRECT_EXPLICIT_LINK_KINDS = new Set(["explicit-imports-candidate", "candidate-imports-explicit"]);
@@ -144,14 +234,19 @@ export function composeCriterionContextEntries(input = {}, options = {}) {
   const limit = integer(options.limit, 6, 1, 12);
   const criteriaText = uniqueStrings(input.criteria, 20).join("\n");
   const explicitPaths = uniqueStrings(input.explicitPaths, 20).map(relativePath).filter(Boolean);
-  const plannedPaths = new Set((Array.isArray(input.plannedEntries) ? input.plannedEntries : [])
+  const plannedEntries = Array.isArray(input.plannedEntries) ? input.plannedEntries : [];
+  const plannedPaths = new Set(plannedEntries
     .map((entry) => relativePath(entry?.path)).filter(Boolean));
+  const plannedReasons = new Map(plannedEntries.map((entry) => [
+    relativePath(entry?.path),
+    typeof entry?.reason === "string" ? entry.reason.trim() : ""
+  ]).filter(([filePath]) => Boolean(filePath)));
   const candidates = [];
   (Array.isArray(input.retrievedItems) ? input.retrievedItems : []).forEach((entry, order) => {
     const normalized = normalizedCandidate(entry, "retrieval", order);
     if (normalized) candidates.push(normalized);
   });
-  (Array.isArray(input.plannedEntries) ? input.plannedEntries : []).forEach((entry, order) => {
+  plannedEntries.forEach((entry, order) => {
     const normalized = normalizedCandidate(entry, "criterion", order);
     if (normalized) candidates.push(normalized);
   });
@@ -283,7 +378,17 @@ export function composeCriterionContextEntries(input = {}, options = {}) {
   // changed live assertion and final verification.
   if (!selected.some((entry) => testPath(entry.path))) {
     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)");
+    const testNavigationProhibited = scopedTests.length === 1
+      && explicitTestNavigationProhibited(criteriaText, scopedTests[0].path);
+    const soleCriterionPlannedTest = scopedTests.length === 1
+      && /^criterion-\d+ (?:behavior|boundary) target$/i.test(plannedReasons.get(scopedTests[0].path) ?? "")
+      && !testNavigationProhibited;
+    if (scopedTests.length === 1 && !testNavigationProhibited
+      && (explicitFocusedTestNavigation(criteriaText) || soleCriterionPlannedTest)) {
+      add(scopedTests[0], soleCriterionPlannedTest
+        ? "Sole criterion-planned executable test (navigation context; not acceptance proof)"
+        : "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/failure-types.ts

@@ -5,8 +5,8 @@ export const FAILURE_PARSER_VERSION = "failure-parser-v1" as const;
 export const FAILURE_POLICY_VERSION = "failure-policy-v1" as const;
 export const FAILURE_CATEGORIES = Object.freeze(["passed", "compile-typecheck", "test-assertion", "lint-format", "dependency-config", "environment", "provider-network", "permission-policy", "scope-protected-path", "flaky-infrastructure", "unknown"] as const);
 export const FAILURE_OWNERS = Object.freeze(["none", "source", "test-expectation", "dependency", "environment", "provider", "permission", "policy", "scope", "infrastructure", "unknown"] as const);
-export const FAILURE_STRUCTURED_EVENTS = Object.freeze(["scope-violation", "protected-path", "permission-denied", "policy-block", "provider-network", "environment", "flaky-infrastructure", "stale-verifier", "missing-verifier"] as const);
-export const FAILURE_REASON_CODES = Object.freeze(["exit-zero", "structured-scope", "structured-protected-path", "structured-permission", "structured-policy", "structured-provider", "structured-environment", "structured-flaky-infrastructure", "structured-stale-verifier", "structured-missing-verifier", "typescript-diagnostic", "python-type-diagnostic", "go-compile-diagnostic", "rust-compile-diagnostic", "generic-compile-diagnostic", "test-assertion-diagnostic", "lint-format-diagnostic", "dependency-config-diagnostic", "environment-diagnostic", "provider-rate-limit", "provider-transport", "permission-diagnostic", "policy-diagnostic", "scope-diagnostic", "local-port-conflict", "transient-infrastructure", "unknown-diagnostic"] as const);
+export const FAILURE_STRUCTURED_EVENTS = Object.freeze(["scope-violation", "protected-path", "permission-denied", "policy-block", "provider-network", "environment", "flaky-infrastructure", "stale-verifier", "missing-verifier", "verification-gap"] as const);
+export const FAILURE_REASON_CODES = Object.freeze(["exit-zero", "structured-scope", "structured-protected-path", "structured-permission", "structured-policy", "structured-provider", "structured-environment", "structured-flaky-infrastructure", "structured-stale-verifier", "structured-missing-verifier", "structured-verification-gap", "typescript-diagnostic", "python-type-diagnostic", "go-compile-diagnostic", "rust-compile-diagnostic", "generic-compile-diagnostic", "test-assertion-diagnostic", "lint-format-diagnostic", "dependency-config-diagnostic", "environment-diagnostic", "provider-rate-limit", "provider-transport", "permission-diagnostic", "policy-diagnostic", "scope-diagnostic", "local-port-conflict", "transient-infrastructure", "unknown-diagnostic"] as const);
 
 export type FailureCategory = typeof FAILURE_CATEGORIES[number];
 export type FailureOwner = typeof FAILURE_OWNERS[number];

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
+  };
+}

package/packages/piagent-core/extensions/guard-types.ts

@@ -236,6 +236,8 @@ export type AcceptanceReceipt = {
   helperUsage?: {
     mode: "off" | "recommend" | "on";
     used: boolean;
+    decision?: "dispatch" | "skip";
+    projectedSavingsRatio?: number | null;
     reasonCodes: string[];
     helpers: Array<{
       role: "retriever" | "scout" | "planner" | "worker" | "reviewer" | "oracle" | "researcher";
@@ -364,11 +366,13 @@ export type TaskContract = {
   sessionId: string;
   sessionName?: string;
   changeMode: "source-change" | "read-only";
-  mutationPolicy?: "required" | "forbidden";
+  mutationPolicy?: "required" | "allowed" | "forbidden";
   attempt: number;
   maxAttempts: number;
   previousAttempts: TaskAttemptSummary[];
   summary: string;
+  operatorRequest?: string;
+  operatorRequestDigest?: string;
   riskLane: "tiny" | "normal" | "high-risk";
   intakeMode?: "model" | "runtime";
   expectedOutput: string;
@@ -413,9 +417,12 @@ export type TaskContract = {
     matchedProfileCommand?: boolean;
     preWorkingTreeDigest?: string;
     workingTreeDigest?: string;
+    preWorkspaceRevisionDigest?: string;
+    workspaceRevisionDigest?: string;
   }>;
   trace: {
     outcome: "pending" | "completed" | "blocked" | "partial" | "failed";
+    terminalDisposition?: "refused";
     friction?: string;
     notes?: string;
     recordedAt?: string;
@@ -481,6 +488,7 @@ export type ExternalActionPolicyConfig = {
 };
 
 export type FinalGateConfig = {
+  acceptanceProofMode?: "enforce" | "diagnostic";
   defaultMode?: "advisory" | "enforce";
   requireTaskContract?: boolean;
   requireContextManifest?: boolean;