@lazyingart/agintiflow 0.20.281 → 0.20.282

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.281",
+  "version": "0.20.282",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",

package/scripts/smoke-dynamic-step-budget.js

@@ -53,6 +53,7 @@ import {
   isSubstantiveTestCommand,
   mergeDurableGitEvidence,
   nextStepRuntimeConfig,
+  patchContextRefreshDecision,
   patchContextScopeMismatchAttemptCount,
   parseGitPorcelainStatus,
   pythonMainGuardOrderDefects,
@@ -1216,6 +1217,100 @@ try {
       Boolean(unrelatedInsertionBinding?.scopeIssue),
     "an unrelated missing declaration escaped the active failed-test symbol contract"
   );
+  const declarationBoundarySource = [
+    "def build_preview():",
+    "    path = 'preview.png'",
+    "    return path",
+    "",
+    "def main():",
+    "    return build_preview()",
+    "",
+  ].join("\n");
+  const declarationBoundaryOffset = declarationBoundarySource.indexOf("def main():");
+  const declarationBoundaryAnchor = declarationBoundarySource.slice(
+    0,
+    declarationBoundaryOffset
+  );
+  const declarationBoundaryState = {
+    meta: {
+      goalContract: { revision: 1 },
+      projectVerification: { mutationRevision: 1, privateMutationRevision: 0 },
+      toolLoop: {
+        patchContextRepair: {
+          version: 1,
+          path: "preview_builder.py",
+          goalRevision: 1,
+          mutationRevision: 1,
+          privateMutationRevision: 0,
+          search: declarationBoundaryAnchor,
+          searchHash: crypto
+            .createHash("sha256")
+            .update(declarationBoundaryAnchor)
+            .digest("hex"),
+          sourceHash: crypto
+            .createHash("sha256")
+            .update(declarationBoundarySource)
+            .digest("hex"),
+          anchorKind: "declaration-identity",
+          anchorIdentity: "build_preview",
+        },
+      },
+    },
+  };
+  const declarationBoundaryBinding = bindPatchContextRepairArguments(
+    declarationBoundaryState,
+    {
+      replace: [
+        "def build_preview():",
+        "    path = 'preview-fixed.png'",
+        "    return path",
+      ].join("\n"),
+    }
+  );
+  assert(
+    declarationBoundaryBinding?.boundaryWhitespacePreserved === true &&
+      declarationBoundaryBinding.args.replace.endsWith("\n") &&
+      /return path\n+def main\(\):/.test(
+        `${declarationBoundaryBinding.args.replace}${declarationBoundarySource.slice(declarationBoundaryOffset)}`
+      ),
+    "revision-bound declaration replacement did not preserve its Python declaration boundary"
+  );
+  await fs.writeFile(
+    path.join(workspace, "preview_builder.py"),
+    declarationBoundarySource,
+    "utf8"
+  );
+  assert(
+    (await prospectivePythonExactPatchSyntaxBlock(
+      "apply_patch",
+      declarationBoundaryBinding.args,
+      { commandCwd: workspace }
+    )) === null,
+    "the boundary-preserved declaration replacement still produced invalid Python"
+  );
+  const syntaxRefreshDecision = patchContextRefreshDecision(
+    {
+      meta: {
+        goalContract: { revision: 1 },
+        projectVerification: { mutationRevision: 1, privateMutationRevision: 0 },
+        toolLoop: { stagnationEpoch: 0, recent: [] },
+      },
+    },
+    {
+      toolName: "apply_patch",
+      ok: false,
+      category: "python-syntax-regression",
+      args: {
+        path: "preview_builder.py",
+        search: declarationBoundaryAnchor,
+      },
+    }
+  );
+  assert(
+    syntaxRefreshDecision?.triggerCategory === "python-syntax-regression" &&
+      syntaxRefreshDecision.path === "preview_builder.py",
+    "a prospective Python syntax regression did not force a fresh exact-source read"
+  );
   const semanticScopeMismatchState = {
     meta: {
       goalContract: { revision: 4 },
@@ -10364,6 +10459,60 @@ try {
   assert(resumedBudget?.extensionsUsed === 0, "runAgent retained stale extension usage after an explicit resumed max-steps patch");
   assert(resumedBudget?.resetFromExplicitOverride === true, "runAgent did not record the explicit budget reset boundary");
 
+  const educationWorkspace = path.join(tempRoot, "education-artifact-contract");
+  await fs.mkdir(path.join(educationWorkspace, "workshop"), { recursive: true });
+  await fs.writeFile(path.join(educationWorkspace, "workshop", "lesson-deck.md"), "# Lesson\n");
+  const educationGoal =
+    "Create an editable lesson deck, a separate practice sheet and answer key, printable materials, a helpful preview, and a reproducible build entrypoint. Verify and commit the work.";
+  const educationState = {
+    goal: educationGoal,
+    commandCwd: educationWorkspace,
+    plan: "Create every requested artifact, verify them, and commit the complete set.",
+    messages: [
+      {
+        role: "tool",
+        content: JSON.stringify({
+          ok: true,
+          toolName: "write_file",
+          path: "workshop/lesson-deck.md",
+          goalRevision: 1,
+          projectMutationRevision: 1,
+        }),
+      },
+    ],
+    meta: {
+      taskProfile: "education",
+      goalContract: {
+        revision: 1,
+        currentRequest: educationGoal,
+        taskGoal: educationGoal,
+        activeGoalRevision: 1,
+        lifecycle: [{ at: new Date(Date.now() - 2000).toISOString() }],
+      },
+      projectVerification: {
+        mutationRevision: 1,
+        mutationHistory: [
+          {
+            revision: 1,
+            at: new Date().toISOString(),
+            toolName: "write_file",
+            paths: ["workshop/lesson-deck.md"],
+            goalRevision: 1,
+          },
+        ],
+      },
+    },
+  };
+  const incompleteEducationRuntime = nextStepRuntimeConfig(
+    { goal: educationGoal, taskProfile: "education", commandCwd: educationWorkspace },
+    educationState
+  );
+  assert(
+    incompleteEducationRuntime.requestedArtifactRequirementsPending === true &&
+      incompleteEducationRuntime.taskOwnedCommitPending !== true,
+    "a partial multi-artifact task entered task-owned Git completion before its deliverables existed"
+  );
+
   await fs.rm(tempRoot, { recursive: true, force: true });
   console.log("smoke-dynamic-step-budget ok");
 } catch (error) {

package/scripts/smoke-scs-evidence-visibility.js

@@ -12,6 +12,7 @@ import {
 import {
   buildScsEvidenceLedger,
   deriveScsTaskContract,
+  evaluateRequestedArtifactRequirements,
   evaluateScsSemanticContract,
   extractMarkdownCommandEvidence,
   extractMarkdownPathEvidence,
@@ -19,6 +20,73 @@ import {
   finishResultClaimsIncompleteWork,
 } from "../src/scs-evidence.js";
 
+const educationArtifactGoal =
+  "Create an editable lesson deck, a separate practice sheet and answer key, printable materials, a helpful preview, and a reproducible build entrypoint.";
+const educationArtifactContract = deriveScsTaskContract({
+  goal: educationArtifactGoal,
+  taskProfile: "education",
+});
+assert.deepEqual(
+  educationArtifactContract.requiredArtifactKinds.map((item) => item.id).sort(),
+  [
+    "answer-material",
+    "editable-presentation",
+    "practice-material",
+    "printable-document",
+    "reproducible-build-entrypoint",
+    "visual-preview",
+  ],
+  "multi-artifact education request did not retain each semantic deliverable"
+);
+assert.deepEqual(
+  deriveScsTaskContract({
+    goal: "Create a canvas artifact preview for this smoke test.",
+    taskProfile: "auto",
+  }).requiredArtifactKinds,
+  [],
+  "a generic frontend canvas preview was incorrectly converted into a required image-file artifact"
+);
+const educationWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "aginti-education-artifacts-"));
+const educationState = {
+  meta: {
+    goalContract: {
+      lifecycle: [{ at: new Date(Date.now() - 2000).toISOString() }],
+    },
+    projectVerification: { mutationHistory: [] },
+  },
+};
+fs.mkdirSync(path.join(educationWorkspace, "workshop"), { recursive: true });
+fs.writeFileSync(path.join(educationWorkspace, "workshop", "lesson-deck.md"), "# Lesson deck\n");
+const incompleteEducationArtifacts = evaluateRequestedArtifactRequirements(
+  educationArtifactContract,
+  { commandCwd: educationWorkspace, state: educationState }
+);
+assert.equal(incompleteEducationArtifacts.ok, false);
+assert.ok(
+  incompleteEducationArtifacts.missing.some((item) => item.id === "editable-presentation"),
+  "Markdown-only deck incorrectly satisfied the editable presentation contract"
+);
+for (const [name, content] of [
+  ["lesson-deck.pptx", "pptx"],
+  ["practice-sheet.md", "practice"],
+  ["answer-key.md", "answers"],
+  ["practice-sheet.pdf", "pdf"],
+  ["lesson-preview.png", "png"],
+  ["build_materials.py", "print('build')\n"],
+]) {
+  fs.writeFileSync(path.join(educationWorkspace, "workshop", name), content);
+}
+const completeEducationArtifacts = evaluateRequestedArtifactRequirements(
+  educationArtifactContract,
+  { commandCwd: educationWorkspace, state: educationState }
+);
+assert.equal(
+  completeEducationArtifacts.ok,
+  true,
+  `complete semantic artifact set was rejected: ${completeEducationArtifacts.reason}`
+);
+fs.rmSync(educationWorkspace, { recursive: true, force: true });
+
 function fakeStudentClient(json) {
   return {
     chat: {

package/scripts/smoke-web-api.js

@@ -68,12 +68,23 @@ async function waitForHealth() {
 async function waitForRun(sessionId, terminalStatuses = ["finished", "failed"]) {
   const acceptedStatuses = new Set(terminalStatuses);
   const deadline = Date.now() + 20000;
+  let lastRun = null;
   while (Date.now() < deadline) {
     const run = await fetchJson(`/api/runs/${encodeURIComponent(sessionId)}`);
+    lastRun = run;
     if (acceptedStatuses.has(run.status)) return run;
     await delay(400);
   }
-  throw new Error(`run ${sessionId} did not finish in time`);
+  throw new Error(
+    `run ${sessionId} did not finish in time; ` +
+      `lastRun=${JSON.stringify(lastRun ? {
+        status: lastRun.status,
+        error: lastRun.error,
+        endedAt: lastRun.endedAt,
+        logs: Array.isArray(lastRun.logs) ? lastRun.logs.slice(-12) : [],
+      } : null)} ` +
+      `stdout=${stdout.slice(-1000)} stderr=${stderr.slice(-1000)}`
+  );
 }
 
 try {

package/src/agent-runner.js

@@ -128,6 +128,7 @@ import {
   deterministicFinishBlocker,
   evaluateScsEvidence,
   evaluateScsSemanticContract,
+  evaluateRequestedArtifactRequirements,
   augmentScsTaskContractWithProjectVerification,
   agintiEvidenceScopeLine,
   filterExplicitlyExcludedOutputPaths,
@@ -1754,6 +1755,11 @@ function buildCompactedRuntimeMessages(state, config, snapshot, step, options =
     title: snapshot?.title || "",
     url: snapshot?.url || "",
     plan: effectivePlan,
+    missingRequestedArtifactRequirements: Array.isArray(
+      config.missingRequestedArtifactRequirements
+    )
+      ? config.missingRequestedArtifactRequirements
+      : [],
   };
   const compactedContent = [
     options.heading || "Continue from this compacted, valid transcript.",
@@ -11507,6 +11513,21 @@ export function nextStepRuntimeConfig(config = {}, state = {}) {
       ? state.meta.activeExecutionContract || {}
       : {};
   const groundingTaskContract = completionTaskContract(config, state);
+  const requestedArtifactEvaluation = evaluateRequestedArtifactRequirements(
+    groundingTaskContract,
+    {
+      commandCwd: config.commandCwd || state.commandCwd || process.cwd(),
+      state,
+    }
+  );
+  if (!requestedArtifactEvaluation.ok) {
+    runtimeConfig.requestedArtifactRequirementsPending = true;
+    runtimeConfig.missingRequestedArtifactRequirements =
+      requestedArtifactEvaluation.missing.map((item) => ({
+        id: String(item?.id || ""),
+        description: String(item?.description || item?.id || ""),
+      }));
+  }
   const groundingMutationRevision = Math.max(
     0,
     Number(state.meta?.projectVerification?.mutationRevision || 0)
@@ -12263,7 +12284,12 @@ export function nextStepRuntimeConfig(config = {}, state = {}) {
     runtimeConfig.requiredProjectCommand = pendingRequiredProjectCommands[0];
     runtimeConfig.pendingRequiredProjectCommands = pendingRequiredProjectCommands;
   }
-  if (!state.meta?.artifactProgress && !retainedFailedTest && !implementationOpen) {
+  if (
+    !state.meta?.artifactProgress &&
+    !retainedFailedTest &&
+    !implementationOpen &&
+    requestedArtifactEvaluation.ok
+  ) {
     const completionContract = completionTaskContract(config, state);
     const completionEvaluation = evaluateScsEvidence(
       completionContract,
@@ -13293,6 +13319,25 @@ function comparablePatchContextText(value = "") {
     .trim();
 }
 
+function preservePatchContextBoundaryWhitespace(marker = {}, replacement = "") {
+  const value = String(replacement || "");
+  if (String(marker.anchorKind || "") === "complete-file") {
+    return { replacement: value, preserved: false };
+  }
+  const search = String(marker.search || "");
+  const trailingBoundary = search.match(/(?:(?:\r\n|\n|\r)[\t ]*)+$/)?.[0] || "";
+  if (!trailingBoundary) return { replacement: value, preserved: false };
+  const withoutTrailingBoundary = value.replace(
+    /(?:(?:\r\n|\n|\r)[\t ]*)+$/,
+    ""
+  );
+  const normalized = `${withoutTrailingBoundary}${trailingBoundary}`;
+  return {
+    replacement: normalized,
+    preserved: normalized !== value,
+  };
+}
+
 function patchContextDeclarationCounts(content = "") {
   const counts = new Map();
   for (const record of sourceLineRecords(content)) {
@@ -13520,6 +13565,11 @@ export function bindPatchContextRepairArguments(state = {}, requestedArgs = {})
         : patchContextReplacementScopeIssue(boundMarker, replace);
     }
   }
+  const boundaryWhitespace = preservePatchContextBoundaryWhitespace(
+    boundMarker,
+    replace
+  );
+  replace = boundaryWhitespace.replacement;
   if (boundedSubrange && state.meta?.toolLoop?.patchContextRepair) {
     state.meta.toolLoop.patchContextRepair.lastBoundSearchHash =
       boundedSubrange.searchHash;
@@ -13538,6 +13588,7 @@ export function bindPatchContextRepairArguments(state = {}, requestedArgs = {})
       : "",
     boundedRequestedSubrange: Boolean(boundedSubrange),
     incrementalDeclarationRecovery,
+    boundaryWhitespacePreserved: boundaryWhitespace.preserved,
     noOp:
       comparablePatchContextText(replace) ===
       comparablePatchContextText(boundMarker.search),
@@ -13613,8 +13664,21 @@ export function patchContextRefreshDecision(state = {}, toolResult = {}) {
       toolResult.ok === false &&
       toolResult.category === "patch-context-scope-mismatch"
   );
+  const pythonSyntaxRegression = Boolean(
+    String(toolResult.toolName || "") === "apply_patch" &&
+      toolResult.ok === false &&
+      toolResult.category === "python-syntax-regression"
+  );
   const missingSearch = patchSearchTextWasNotFound(toolResult);
-  if (!missingSearch && !idempotencyBlock && !topologyBlock && !scopeMismatch) return null;
+  if (
+    !missingSearch &&
+    !idempotencyBlock &&
+    !topologyBlock &&
+    !scopeMismatch &&
+    !pythonSyntaxRegression
+  ) {
+    return null;
+  }
   const targetPath = toolResultWorkspacePath(toolResult);
   if (!targetPath) return null;
   const toolLoop = state.meta?.toolLoop || {};
@@ -13642,6 +13706,7 @@ export function patchContextRefreshDecision(state = {}, toolResult = {}) {
     !idempotencyBlock &&
     !topologyBlock &&
     !scopeMismatch &&
+    !pythonSyntaxRegression &&
     stalePatchFailureCount < 1 &&
     !followedIdempotencyBlock
   ) {
@@ -13673,6 +13738,8 @@ export function patchContextRefreshDecision(state = {}, toolResult = {}) {
         ? "required-symbol-topology"
         : scopeMismatch
           ? "patch-context-scope-mismatch"
+          : pythonSyntaxRegression
+            ? "python-syntax-regression"
         : "stale-patch-search",
     failedSearchPreview,
     failedSearchHash: String(toolResult.args?.searchHash || ""),
@@ -14654,6 +14721,8 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
         patchContextBinding.boundedRequestedSubrange === true,
       incrementalDeclarationRecovery:
         Boolean(patchContextBinding.incrementalDeclarationRecovery),
+      boundaryWhitespacePreserved:
+        patchContextBinding.boundaryWhitespacePreserved === true,
     };
     await store.appendEvent("patch_context.anchor_injected", detail);
     observers.event("patch_context.anchor_injected", detail);

package/src/scs-controller.js

@@ -508,6 +508,11 @@ function formatHardContractForPrompt(contract = {}) {
   const requiredExecutableTerms = normalizeStringList(contract.requiredExecutableTerms, []);
   const forbiddenTextTerms = normalizeStringList(contract.forbiddenTextTerms, []);
   const forbiddenActions = normalizeStringList(contract.forbiddenActions, []);
+  const requiredArtifactKinds = (Array.isArray(contract.requiredArtifactKinds)
+    ? contract.requiredArtifactKinds
+    : [])
+    .map((item) => compact(item?.description || item?.id || "", 160))
+    .filter(Boolean);
   if (exactOutputPaths.length) lines.push(`Exact output path(s): ${exactOutputPaths.join(", ")}`);
   if (exactInputPaths.length) lines.push(`Exact input/reference path(s) to use: ${exactInputPaths.join(", ")}`);
   if (requiredTextTerms.length) lines.push(`Required text term(s) in the output: ${requiredTextTerms.join(", ")}`);
@@ -516,6 +521,9 @@ function formatHardContractForPrompt(contract = {}) {
   }
   if (forbiddenTextTerms.length) lines.push(`Forbidden text term(s) in the output: ${forbiddenTextTerms.join(", ")}`);
   if (forbiddenActions.length) lines.push(`Forbidden action(s): ${forbiddenActions.join("; ")}`);
+  if (requiredArtifactKinds.length) {
+    lines.push(`Required artifact deliverable(s): ${requiredArtifactKinds.join(", ")}`);
+  }
   return lines.length
     ? [
         "Inferred hard task contract. Preserve these literally; do not replace them with weaker or contradictory criteria:",
@@ -531,8 +539,19 @@ function deterministicPlanContractIssue(committee = {}, contract = {}) {
   const missingRequiredTerms = normalizeStringList(contract.requiredTextTerms, []).filter((item) => !planText.includes(item));
   const missingExecutableTerms = normalizeStringList(contract.requiredExecutableTerms, []).filter((item) => !planText.includes(item));
   const forbiddenTermsInPlan = normalizeStringList(contract.forbiddenTextTerms, []).filter((item) => planText.includes(item));
+  const missingArtifactKinds = (Array.isArray(contract.requiredArtifactKinds)
+    ? contract.requiredArtifactKinds
+    : []).filter((item) => {
+      const id = String(item?.id || "").replace(/^format:/, "");
+      const description = String(item?.description || "");
+      const terms = [id, description]
+        .flatMap((value) => value.toLocaleLowerCase("en-US").split(/[^a-z0-9.]+/))
+        .filter((value) => value.length >= 3);
+      const normalizedPlan = planText.toLocaleLowerCase("en-US");
+      return terms.length > 0 && !terms.some((term) => normalizedPlan.includes(term));
+    });
   const actionContradiction = deterministicPlanActionContradiction(planText, contract);
-  if (missingPath.length || missingInputPath.length || missingRequiredTerms.length || missingExecutableTerms.length || forbiddenTermsInPlan.length || actionContradiction) {
+  if (missingPath.length || missingInputPath.length || missingRequiredTerms.length || missingExecutableTerms.length || forbiddenTermsInPlan.length || missingArtifactKinds.length || actionContradiction) {
     return {
       decision: "veto_plan",
       confidence: 0.94,
@@ -542,6 +561,11 @@ function deterministicPlanContractIssue(committee = {}, contract = {}) {
         missingRequiredTerms.length ? `Plan omitted required text term(s): ${missingRequiredTerms.join(", ")}` : "",
         missingExecutableTerms.length ? `Plan omitted required executable source expression(s): ${missingExecutableTerms.join(", ")}` : "",
         forbiddenTermsInPlan.length ? `Plan includes forbidden text term(s): ${forbiddenTermsInPlan.join(", ")}` : "",
+        missingArtifactKinds.length
+          ? `Plan omitted requested artifact deliverable(s): ${missingArtifactKinds
+              .map((item) => item.description || item.id)
+              .join(", ")}`
+          : "",
         actionContradiction || "",
       ].filter(Boolean),
       reason:

package/src/scs-evidence.js

@@ -521,6 +521,120 @@ function inferExactOutputPaths(goal = "") {
   return uniqueLimited(filterShadowedBasenames(paths), 16);
 }
 
+const REQUESTED_ARTIFACT_FORMATS = [
+  { extension: ".pptx", pattern: /\b(?:pptx|powerpoint)\b/i, description: "editable PowerPoint deck" },
+  { extension: ".odp", pattern: /\b(?:odp|open(?:office|document) presentation)\b/i, description: "editable ODP deck" },
+  { extension: ".pdf", pattern: /\bpdf\b/i, description: "PDF document" },
+  { extension: ".docx", pattern: /\b(?:docx|word document)\b/i, description: "editable Word document" },
+  { extension: ".xlsx", pattern: /\b(?:xlsx|excel workbook)\b/i, description: "editable spreadsheet" },
+  { extension: ".png", pattern: /\bpng\b/i, description: "PNG image" },
+  { extension: ".svg", pattern: /\bsvg\b/i, description: "editable SVG image" },
+];
+
+function artifactRequestHasOutputIntent(goal = "", taskProfile = "") {
+  const source = stripForbiddenLanguage(String(goal || ""));
+  return Boolean(
+    goalRequestsFileMutation(source, taskProfile) ||
+      /\b(?:create|deliver|export|generate|leave|make|output|prepare|produce|save|write)\b/i.test(
+        source
+      ) ||
+      /\b(?:i|we)\s+(?:also\s+)?(?:need|want|would like)\b[^.\n;]{0,100}\b(?:answer|artifact|deck|document|handout|material|pdf|presentation|preview|report|sheet|slides?|workbook|worksheet)\b/i.test(
+        source
+      ) ||
+      /\b(?:give|provide|return|send)\b[^.\n;]{0,80}\b(?:answer|artifact|deck|document|handout|material|pdf|presentation|preview|report|sheet|slides?|workbook|worksheet)\b/i.test(
+        source
+      ) ||
+      /(?:创建|生成|输出|导出|保存|提供|需要|交付)/u.test(source)
+  );
+}
+
+export function inferRequestedArtifactRequirements(goal = "", taskProfile = "") {
+  const source = stripForbiddenLanguage(String(goal || ""));
+  if (!artifactRequestHasOutputIntent(source, taskProfile)) return [];
+
+  const requirements = [];
+  const add = (requirement) => {
+    if (!requirement?.id || requirements.some((item) => item.id === requirement.id)) return;
+    requirements.push(requirement);
+  };
+
+  for (const format of REQUESTED_ARTIFACT_FORMATS) {
+    if (!format.pattern.test(source)) continue;
+    add({
+      id: `format:${format.extension}`,
+      kind: "format",
+      extension: format.extension,
+      description: format.description,
+    });
+  }
+
+  const deckRequested = /\b(?:deck|presentation|slides?|slide deck|lecture deck)\b/i.test(source);
+  const editableRequested = /\b(?:editable|edit-friendly|native(?:ly)? editable)\b/i.test(source);
+  if (deckRequested && editableRequested) {
+    add({
+      id: "editable-presentation",
+      kind: "editable-presentation",
+      extensions: [".pptx", ".odp", ".key"],
+      description: "editable presentation deck",
+    });
+  }
+
+  if (
+    /\bprintable\b/i.test(source) &&
+    /\b(?:answer|deck|document|handout|material|practice|sheet|slides?|worksheet)\b/i.test(source)
+  ) {
+    add({
+      id: "printable-document",
+      kind: "printable-document",
+      extensions: [".pdf"],
+      description: "printable PDF material",
+    });
+  }
+
+  if (
+    /\b(?:helpful|high[- ]resolution|useful|visual)\s+preview\b|\b(?:image|png|rendered|screenshot)\s+preview\b|\bpreview\s+(?:image|png|render|screenshot)\b/i.test(
+      source
+    )
+  ) {
+    add({
+      id: "visual-preview",
+      kind: "visual-preview",
+      extensions: [".png", ".jpg", ".jpeg", ".webp"],
+      description: "visual preview image",
+    });
+  }
+
+  if (/\b(?:practice sheet|worksheet|exercise sheet|learner handout)\b/i.test(source)) {
+    add({
+      id: "practice-material",
+      kind: "practice-material",
+      description: "separate practice or worksheet material",
+    });
+  }
+
+  if (/\b(?:answer key|answers?|worked solutions?|solutions? sheet)\b/i.test(source)) {
+    add({
+      id: "answer-material",
+      kind: "answer-material",
+      description: "separate answer or solution material",
+    });
+  }
+
+  if (
+    /\b(?:reproducible|repeatable)\b[^.\n;]{0,80}\b(?:build|generation|export|render)\b|\b(?:build|generation|export|render)\s+(?:entrypoint|script|command)\b/i.test(
+      source
+    )
+  ) {
+    add({
+      id: "reproducible-build-entrypoint",
+      kind: "reproducible-build-entrypoint",
+      description: "reproducible build or export entrypoint",
+    });
+  }
+
+  return requirements.slice(0, 16);
+}
+
 function normalizedContractPath(value = "") {
   return String(value || "")
     .trim()
@@ -1581,6 +1695,10 @@ export function deriveScsTaskContract({ goal = "", taskProfile = "", acceptanceC
     excludedOutputPaths
   ).filter((item) => !inferredOutputPaths.includes(item) && !exactOutputPaths.includes(item));
   const declaredSourceRoots = inferDeclaredSourceRoots(evidenceGoal);
+  const requiredArtifactKinds = inferRequestedArtifactRequirements(
+    positiveEvidenceGoal,
+    taskProfile
+  );
   return {
     version: 1,
     outcome: compact(evidenceGoal || "Complete the requested task.", 500),
@@ -1589,6 +1707,7 @@ export function deriveScsTaskContract({ goal = "", taskProfile = "", acceptanceC
     requiredEvidence,
     forbiddenActions: inferForbiddenActions(evidenceGoal),
     exactOutputPaths,
+    requiredArtifactKinds,
     excludedOutputPaths,
     artifactRoot,
     exactInputPaths,
@@ -1817,6 +1936,190 @@ function resolveContractPath(commandCwd = process.cwd(), rawPath = "") {
   return path.resolve(commandCwd || process.cwd(), text);
 }
 
+const ARTIFACT_SCAN_IGNORED_DIRECTORIES = new Set([
+  ".aginti",
+  ".aginti-sessions",
+  ".git",
+  ".hg",
+  ".svn",
+  "__pycache__",
+  "node_modules",
+  "vendor",
+]);
+
+function taskArtifactFreshnessBoundary(state = {}) {
+  const lifecycle = Array.isArray(state.meta?.goalContract?.lifecycle)
+    ? state.meta.goalContract.lifecycle
+    : [];
+  const lifecycleTimes = lifecycle
+    .map((item) => Date.parse(String(item?.at || "")))
+    .filter(Number.isFinite);
+  if (lifecycleTimes.length) return Math.min(...lifecycleTimes) - 2000;
+  const mutationTimes = (Array.isArray(state.meta?.projectVerification?.mutationHistory)
+    ? state.meta.projectVerification.mutationHistory
+    : [])
+    .map((item) => Date.parse(String(item?.at || "")))
+    .filter(Number.isFinite);
+  return mutationTimes.length ? Math.min(...mutationTimes) - 2000 : 0;
+}
+
+function taskArtifactMutationPaths(state = {}) {
+  const paths = new Set();
+  for (const mutation of Array.isArray(state.meta?.projectVerification?.mutationHistory)
+    ? state.meta.projectVerification.mutationHistory
+    : []) {
+    for (const candidate of Array.isArray(mutation?.paths) ? mutation.paths : []) {
+      const normalized = normalizedContractPath(candidate);
+      if (normalized) paths.add(normalized.toLocaleLowerCase("en-US"));
+    }
+  }
+  return paths;
+}
+
+function collectRequestedArtifactCandidates(commandCwd = process.cwd(), state = {}) {
+  const root = path.resolve(commandCwd || process.cwd());
+  const freshnessBoundary = taskArtifactFreshnessBoundary(state);
+  const mutationPaths = taskArtifactMutationPaths(state);
+  const candidates = [];
+  const queue = [{ absolutePath: root, depth: 0 }];
+  let visited = 0;
+  while (queue.length && candidates.length < 3000 && visited < 6000) {
+    const current = queue.shift();
+    visited += 1;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current.absolutePath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const absolutePath = path.join(current.absolutePath, entry.name);
+      if (entry.isDirectory()) {
+        if (
+          current.depth < 7 &&
+          !ARTIFACT_SCAN_IGNORED_DIRECTORIES.has(entry.name) &&
+          !entry.name.startsWith(".cache")
+        ) {
+          queue.push({ absolutePath, depth: current.depth + 1 });
+        }
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      let stat;
+      try {
+        stat = fs.statSync(absolutePath);
+      } catch {
+        continue;
+      }
+      if (!stat.size) continue;
+      const relativePath = path.relative(root, absolutePath).replace(/\\/g, "/");
+      const normalized = normalizedContractPath(relativePath).toLocaleLowerCase("en-US");
+      const fresh = Boolean(
+        mutationPaths.has(normalized) ||
+          freshnessBoundary === 0 ||
+          Number(stat.mtimeMs || 0) >= freshnessBoundary
+      );
+      candidates.push({
+        path: relativePath,
+        extension: path.extname(entry.name).toLocaleLowerCase("en-US"),
+        basename: entry.name.toLocaleLowerCase("en-US"),
+        bytes: stat.size,
+        mtimeMs: Number(stat.mtimeMs || 0),
+        fresh,
+      });
+    }
+  }
+  return candidates;
+}
+
+function requestedArtifactRequirementMatches(requirement = {}, candidate = {}) {
+  const extension = String(candidate.extension || "").toLocaleLowerCase("en-US");
+  const basename = String(candidate.basename || "").toLocaleLowerCase("en-US");
+  if (requirement.kind === "format") {
+    return extension === String(requirement.extension || "").toLocaleLowerCase("en-US");
+  }
+  if (["editable-presentation", "printable-document", "visual-preview"].includes(requirement.kind)) {
+    const extensions = new Set(
+      (Array.isArray(requirement.extensions) ? requirement.extensions : [])
+        .map((item) => String(item || "").toLocaleLowerCase("en-US"))
+    );
+    if (!extensions.has(extension)) return false;
+    if (requirement.kind === "visual-preview") {
+      return /(?:preview|contact[-_ ]?sheet|overview|thumbnail|render)/i.test(basename);
+    }
+    return true;
+  }
+  if (requirement.kind === "practice-material") {
+    return /(?:practice|worksheet|exercise|handout|activity)/i.test(basename) &&
+      /\.(?:docx|html?|md|odt|pdf|tex|txt)$/i.test(extension);
+  }
+  if (requirement.kind === "answer-material") {
+    return /(?:answer|solution|worked[-_ ]?answers?)/i.test(basename) &&
+      /\.(?:docx|html?|md|odt|pdf|tex|txt)$/i.test(extension);
+  }
+  if (requirement.kind === "reproducible-build-entrypoint") {
+    return (
+      /^(?:makefile|justfile)$/i.test(basename) ||
+      /(?:^|[-_])(?:build|compile|export|generate|render)(?:[-_.]|$)/i.test(basename)
+    ) && /(?:^makefile$|^justfile$|\.(?:cjs|js|mjs|py|sh|ts)$)/i.test(basename);
+  }
+  return false;
+}
+
+export function evaluateRequestedArtifactRequirements(
+  contract = {},
+  { commandCwd = process.cwd(), state = {} } = {}
+) {
+  const requirements = Array.isArray(contract.requiredArtifactKinds)
+    ? contract.requiredArtifactKinds
+    : [];
+  if (!requirements.length) {
+    return {
+      ok: true,
+      checked: false,
+      requirements: [],
+      satisfied: [],
+      missing: [],
+      candidates: [],
+      reason: "No semantic artifact-set contract was inferred.",
+    };
+  }
+  const candidates = collectRequestedArtifactCandidates(commandCwd, state);
+  const requireFresh = contract.requiresFileMutation === true;
+  const usableCandidates = requireFresh
+    ? candidates.filter((candidate) => candidate.fresh)
+    : candidates;
+  const satisfied = [];
+  const missing = [];
+  for (const requirement of requirements) {
+    const matches = usableCandidates.filter((candidate) =>
+      requestedArtifactRequirementMatches(requirement, candidate)
+    );
+    if (matches.length) {
+      satisfied.push({
+        ...requirement,
+        paths: matches.map((candidate) => candidate.path).slice(0, 12),
+      });
+    } else {
+      missing.push(requirement);
+    }
+  }
+  return {
+    ok: missing.length === 0,
+    checked: true,
+    requirements,
+    satisfied,
+    missing,
+    candidates: usableCandidates.slice(0, 120),
+    reason: missing.length
+      ? `Missing requested artifact deliverables: ${missing
+          .map((item) => item.description || item.id)
+          .join(", ")}.`
+      : "Every requested artifact format and role has a fresh workspace deliverable.",
+  };
+}
+
 const PROJECT_SOURCE_PATH_PATTERN =
   /\.(?:c|cc|cpp|cxx|h|hh|hpp|cs|go|java|js|jsx|ts|tsx|mjs|cjs|kt|kts|php|py|r|rb|rs|scala|sh|sql|swift|vue|svelte|jl)$/i;
 const PROJECT_SOURCE_MANIFEST_PATTERN =
@@ -2993,11 +3296,16 @@ export function evaluateScsSemanticContract(
   const forbiddenTextTerms = Array.isArray(contract.forbiddenTextTerms) ? contract.forbiddenTextTerms : [];
   const projectTestVerification = evaluateProjectTestVerification(events);
   const executable = evaluateRequiredExecutableTerms(contract, { commandCwd, events, state });
+  const requestedArtifacts = evaluateRequestedArtifactRequirements(contract, {
+    commandCwd,
+    state,
+  });
   if (
     !exactOutputPaths.length &&
     !requiredTextTerms.length &&
     !requiredExecutableTerms.length &&
-    !forbiddenTextTerms.length
+    !forbiddenTextTerms.length &&
+    !requestedArtifacts.checked
   ) {
     return projectTestVerification.checked
       ? {
@@ -3009,18 +3317,23 @@ export function evaluateScsSemanticContract(
       : { ok: true, checked: false, projectTestVerification, reason: "No semantic file contract was inferred." };
   }
   if (!exactOutputPaths.length) {
-    const ok = executable.ok && projectTestVerification.ok;
+    const ok = executable.ok && projectTestVerification.ok && requestedArtifacts.ok;
     return {
       ok,
-      checked: executable.checked || projectTestVerification.checked,
-      reason: !executable.ok
+      checked: executable.checked || projectTestVerification.checked || requestedArtifacts.checked,
+      reason: !requestedArtifacts.ok
+        ? requestedArtifacts.reason
+        : !executable.ok
         ? executable.reason
         : !projectTestVerification.ok
           ? projectTestVerification.reason
-          : "Semantic text terms were inferred, but no exact output path was inferred for deterministic file inspection.",
+          : requestedArtifacts.checked
+            ? requestedArtifacts.reason
+            : "Semantic text terms were inferred, but no exact output path was inferred for deterministic file inspection.",
       requiredTextTerms,
       requiredExecutableTerms,
       forbiddenTextTerms,
+      requestedArtifacts,
       missingExecutableTerms: executable.missingExecutableTerms,
       executableSourcePaths: executable.executableSourcePaths,
       executable,
@@ -3048,7 +3361,8 @@ export function evaluateScsSemanticContract(
     presentForbiddenText.length === 0 &&
     executable.ok &&
     sourceGrounding.ok &&
-    projectTestVerification.ok;
+    projectTestVerification.ok &&
+    requestedArtifacts.ok;
   return {
     ok,
     checked: true,
@@ -3056,6 +3370,7 @@ export function evaluateScsSemanticContract(
     requiredTextTerms,
     requiredExecutableTerms,
     forbiddenTextTerms,
+    requestedArtifacts,
     missingFiles,
     missingRequiredText,
     missingExecutableTerms: executable.missingExecutableTerms,
@@ -3085,6 +3400,7 @@ export function evaluateScsSemanticContract(
           presentForbiddenText.length ? `Forbidden text terms present: ${presentForbiddenText.join(", ")}` : "",
           !sourceGrounding.ok ? sourceGrounding.reason : "",
           !projectTestVerification.ok ? projectTestVerification.reason : "",
+          !requestedArtifacts.ok ? requestedArtifacts.reason : "",
         ]
           .filter(Boolean)
           .join("; "),
@@ -3619,6 +3935,7 @@ export function summarizeScsContractEvidence({ contract = {}, ledger = {}, evalu
       })),
       forbiddenActions: contract.forbiddenActions || [],
       exactOutputPaths: contract.exactOutputPaths || [],
+      requiredArtifactKinds: contract.requiredArtifactKinds || [],
       exactInputPaths: contract.exactInputPaths || [],
       requiredToolCalls: contract.requiredToolCalls || [],
       requiredGitActions: contract.requiredGitActions || [],