@lazyingart/agintiflow 0.20.282 → 0.20.283

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.282",
+  "version": "0.20.283",
   "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-coding-tools.js

@@ -25,7 +25,11 @@ import { createToolContract, resolveDispatchableToolCallBatch } from "../src/too
 import { formatBehaviorContractForPrompt } from "../src/behavior-contract.js";
 import { resolveRuntimeConfig } from "../src/config.js";
 import { readCodebaseMap } from "../src/codebase-map.js";
-import { classifyCommand, evaluateCommandPolicy } from "../src/command-policy.js";
+import {
+  classifyCommand,
+  evaluateCommandPolicy,
+  externalValidatorCommandContract,
+} from "../src/command-policy.js";
 import { checkToolUse } from "../src/guardrails.js";
 import { shouldReviewToolResult } from "../src/scs-controller.js";
 import {
@@ -96,6 +100,52 @@ async function runMock(goal, sessionId, { resume = false } = {}) {
 }
 
 try {
+  const externalValidatorPath = path.join(
+    tempRoot,
+    "private-acceptance",
+    "spreadsheet_contract.py"
+  );
+  const externalValidatorCommand = `python3 ${externalValidatorPath}`;
+  assert(
+    externalValidatorCommandContract(externalValidatorCommand, {
+      commandCwd: workspace,
+    })?.path === externalValidatorPath,
+    "an exact external validator command did not produce an opaque contract"
+  );
+  assert(
+    externalValidatorCommandContract("python3 tests/local_contract.py", {
+      commandCwd: workspace,
+    }) === null,
+    "an in-workspace project test was incorrectly treated as an opaque external validator"
+  );
+  const opaqueValidatorPolicy = {
+    commandCwd: workspace,
+    allowShellTool: true,
+    sandboxMode: "host",
+    packageInstallPolicy: "block",
+    opaqueExternalValidatorPaths: [externalValidatorPath],
+    opaqueExternalValidatorCommands: [externalValidatorCommand],
+  };
+  assert(
+    evaluateCommandPolicy(externalValidatorCommand, opaqueValidatorPolicy).allowed === true,
+    "the exact declared external validator execution was blocked"
+  );
+  for (const inspectionCommand of [
+    `cat ${externalValidatorPath}`,
+    `sed -n '1,160p' ${externalValidatorPath}`,
+    `cat ${path.relative(workspace, externalValidatorPath)}`,
+    `V=${externalValidatorPath}; grep -n expected "$V"`,
+    `echo validator; cat ${externalValidatorPath}; git status --short`,
+  ]) {
+    const decision = evaluateCommandPolicy(inspectionCommand, opaqueValidatorPolicy);
+    assert(
+      decision.allowed === false &&
+        decision.category === "opaque-external-validator-inspection" &&
+        decision.recoverable === true,
+      `external validator source inspection escaped the opaque contract: ${inspectionCommand}`
+    );
+  }
+
   const genericArtifactBlock = await genericArtifactFilenameBlock(
     "write_file",
     { path: "report.md", content: "summary" },

package/scripts/smoke-document-artifact-quality.js

@@ -8,6 +8,43 @@ import {
   evaluatePdfTextBounds,
   extractSupersededLiterals,
 } from "../src/document-artifact-quality.js";
+import { evaluateSpreadsheetStructure } from "../src/spreadsheet-artifact-quality.js";
+
+const workbookWithPlaceholder = evaluateSpreadsheetStructure({
+  sheets: [
+    { name: "Sheet", state: "visible", cellCount: 0, formulaCount: 0 },
+    { name: "Raw Inventory", state: "visible", cellCount: 30, formulaCount: 0 },
+    { name: "Reorder Plan", state: "visible", cellCount: 20, formulaCount: 8 },
+  ],
+  chartCount: 1,
+  externalLinkCount: 0,
+  hasMacros: false,
+});
+assert.equal(workbookWithPlaceholder.ok, false, "an empty default workbook sheet was accepted");
+assert.equal(workbookWithPlaceholder.defects[0]?.code, "unused-default-worksheet");
+
+const emptyWorkbook = evaluateSpreadsheetStructure({
+  sheets: [{ name: "Sheet", state: "visible", cellCount: 0, formulaCount: 0 }],
+  chartCount: 0,
+  externalLinkCount: 0,
+  hasMacros: false,
+});
+assert.equal(emptyWorkbook.ok, false, "a completely empty workbook was accepted");
+assert.equal(emptyWorkbook.defects[0]?.code, "workbook-has-no-content");
+
+const purposefulWorkbook = evaluateSpreadsheetStructure({
+  sheets: [
+    { name: "Raw Inventory", state: "visible", cellCount: 30, formulaCount: 0 },
+    { name: "Reorder Plan", state: "visible", cellCount: 20, formulaCount: 8 },
+    { name: "Dashboard", state: "visible", cellCount: 12, formulaCount: 3 },
+  ],
+  chartCount: 1,
+  externalLinkCount: 0,
+  hasMacros: false,
+});
+assert.equal(purposefulWorkbook.ok, true, "a workbook with only purposeful sheets was rejected");
+assert.equal(purposefulWorkbook.formulaCount, 11);
+assert.equal(purposefulWorkbook.chartCount, 1);
 
 const source = [
   "Initial plan: the demonstration date was September 12.",

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

@@ -5539,6 +5539,43 @@ try {
   );
   const generatedDeckValidator =
     `python3 ${generatedDeckValidatorPath} --root .`;
+  const opaqueExternalValidatorState = {
+    goal: [
+      "Create the requested workbook from the local inputs.",
+      `Run exactly: \`${generatedDeckValidator}\``,
+      "Do not edit that external validator.",
+    ].join("\n"),
+    meta: {
+      taskProfile: "data",
+      goalContract: {
+        revision: 1,
+        currentRequest: "Create the requested workbook and run the exact validator.",
+      },
+      projectVerification: {
+        mutationRevision: 0,
+        mutationHistory: [],
+        commandRuns: [],
+        testRuns: [],
+      },
+      toolLoop: { recent: [] },
+    },
+  };
+  const opaqueExternalValidatorRuntime = nextStepRuntimeConfig(
+    {
+      provider: "deepseek",
+      taskProfile: "data",
+      commandCwd: workspace,
+      goal: opaqueExternalValidatorState.goal,
+    },
+    opaqueExternalValidatorState
+  );
+  assert(
+    JSON.stringify(opaqueExternalValidatorRuntime.opaqueExternalValidatorPaths) ===
+      JSON.stringify([generatedDeckValidatorPath]) &&
+      JSON.stringify(opaqueExternalValidatorRuntime.opaqueExternalValidatorCommands) ===
+        JSON.stringify([generatedDeckValidator]),
+    "an exact external validator was not retained as an opaque execute-only contract before its first run"
+  );
   await fs.writeFile(
     path.join(workspace, "build_deck.py"),
     "print('build canonical deck')\n",

package/src/agent-runner.js

@@ -38,6 +38,7 @@ import { normalizeWrapperName, runAgentWrapper, wrapperStatusText } from "./tool
 import {
   classifyCommand,
   evaluateCommandPolicy,
+  externalValidatorCommandContract,
   normalizeCommandForPolicy,
 } from "./command-policy.js";
 import {
@@ -59,6 +60,7 @@ import {
 import { normalizeCanvasPayload, persistCanvasPayloadFile } from "./artifact-tunnel.js";
 import { getTaskProfile } from "./task-profiles.js";
 import { validateWordDocumentArtifacts } from "./document-artifact-quality.js";
+import { validateSpreadsheetArtifacts } from "./spreadsheet-artifact-quality.js";
 import { generateImage, listAuxiliarySkills } from "./auxiliary-tools.js";
 import {
   engineeringGuidanceForTask,
@@ -6756,11 +6758,13 @@ export function completionExternalBlockerCanClose({
   projectTestBlock = null,
   sourceQuality = { ok: true },
   documentQuality = null,
+  spreadsheetQuality = null,
 } = {}) {
   return Boolean(
     !projectTestBlock &&
       sourceQuality?.ok !== false &&
       (!documentQuality || documentQuality.ok !== false) &&
+      (!spreadsheetQuality || spreadsheetQuality.ok !== false) &&
       finishResultClaimsBlocker(candidateResult) &&
       hasScsBlockerEvidence(evidenceLedger)
   );
@@ -11613,6 +11617,25 @@ export function nextStepRuntimeConfig(config = {}, state = {}) {
     runtimeConfig.testFailureRequiredSymbolRepair = requiredSymbolRepair;
   }
   const verification = state.meta?.projectVerification || {};
+  const externalValidatorContracts = effectiveRequiredProjectCommands(
+    state,
+    verification,
+    config
+  )
+    .map((command) =>
+      externalValidatorCommandContract(command, {
+        commandCwd: config.commandCwd || state.commandCwd || process.cwd(),
+      })
+    )
+    .filter(Boolean);
+  if (externalValidatorContracts.length) {
+    runtimeConfig.opaqueExternalValidatorPaths = [
+      ...new Set(externalValidatorContracts.map((item) => item.path)),
+    ];
+    runtimeConfig.opaqueExternalValidatorCommands = [
+      ...new Set(externalValidatorContracts.map((item) => item.command)),
+    ];
+  }
   const mutationRevision = Number(verification.mutationRevision || 0);
   const privateMutationRevision = verificationPrivateMutationRevision(verification);
   const implementationOpen = currentTurnImplementationOpen(state);
@@ -16544,6 +16567,8 @@ export function completionRepairMutationRequirement({
   contract = {},
   evaluation = {},
   sourceQuality = {},
+  documentQuality = null,
+  spreadsheetQuality = null,
   projectMutationRevision = 0,
 } = {}) {
   const sourceQualityRepairRequired = Boolean(
@@ -16559,15 +16584,28 @@ export function completionRepairMutationRequirement({
       (Array.isArray(evaluation?.missing) ? evaluation.missing : [])
         .some((item) => item?.category === "file")
   );
+  const artifactQualityRepairRequired = [documentQuality, spreadsheetQuality]
+    .some((quality) => Boolean(
+      quality?.checked === true &&
+      quality?.ok === false &&
+      Array.isArray(quality?.defects) &&
+      quality.defects.length > 0
+    ));
   const revision = Math.max(0, Number(projectMutationRevision || 0));
   return {
-    requiresFreshFileMutation: sourceQualityRepairRequired || missingFileEvidence,
+    requiresFreshFileMutation:
+      sourceQualityRepairRequired ||
+      missingFileEvidence ||
+      artifactQualityRepairRequired,
     requiredFreshMutationRevision: Math.max(
       0,
       Number(contract?.requiredFreshMutationRevision || 0),
-      sourceQualityRepairRequired ? revision + 1 : 0
+      sourceQualityRepairRequired || artifactQualityRepairRequired
+        ? revision + 1
+        : 0
     ),
     sourceQualityRepairRequired,
+    artifactQualityRepairRequired,
   };
 }
 
@@ -16686,6 +16724,68 @@ async function completionEvidenceDecision({ config, state, store, observers, ste
       };
     }
   }
+  let spreadsheetQuality = null;
+  try {
+    spreadsheetQuality = await validateSpreadsheetArtifacts({
+      commandCwd: config.commandCwd || state.commandCwd || process.cwd(),
+      candidateResult,
+      goal: completionContractGoal(config, state),
+      exactOutputPaths: [
+        ...(assessment.contract?.exactOutputPaths || []),
+        ...exactOutputPathsForState(state),
+      ],
+    });
+  } catch (error) {
+    spreadsheetQuality = {
+      ok: false,
+      checked: true,
+      artifacts: [],
+      defects: [{
+        code: "spreadsheet-quality-check-failed",
+        message: String(error?.message || error),
+      }],
+      reason: `Independent spreadsheet-quality validation failed: ${String(error?.message || error)}`,
+    };
+  }
+  if (spreadsheetQuality.checked) {
+    state.meta = state.meta || {};
+    state.meta.spreadsheetArtifactQuality = spreadsheetQuality;
+    const qualityEvent = {
+      step,
+      mode,
+      ok: spreadsheetQuality.ok,
+      reason: spreadsheetQuality.reason,
+      artifacts: spreadsheetQuality.artifacts || [],
+      defects: spreadsheetQuality.defects || [],
+    };
+    await store.appendEvent("spreadsheet.quality_assessed", qualityEvent);
+    observers.event("spreadsheet.quality_assessed", qualityEvent);
+    if (!spreadsheetQuality.ok) {
+      const priorSemanticReason = assessment.semantic?.checked && !assessment.semantic?.ok
+        ? String(assessment.semantic.reason || "")
+        : "";
+      const qualityReason = String(
+        spreadsheetQuality.reason ||
+          "The spreadsheet artifact failed independent structure checks."
+      );
+      assessment = {
+        ...assessment,
+        ok: false,
+        spreadsheetQuality,
+        evaluation: {
+          ...assessment.evaluation,
+          ok: false,
+          reason: qualityReason,
+        },
+        semantic: {
+          ...assessment.semantic,
+          checked: true,
+          ok: false,
+          reason: [priorSemanticReason, qualityReason].filter(Boolean).join(" "),
+        },
+      };
+    }
+  }
   const sourceQuality = await validateMutatedPythonSourceQuality(config, state);
   state.meta = state.meta || {};
   state.meta.sourceCodeQuality = {
@@ -16735,6 +16835,7 @@ async function completionEvidenceDecision({ config, state, store, observers, ste
     projectTestBlock,
     sourceQuality,
     documentQuality,
+    spreadsheetQuality,
   });
   if (assessment.ok && !claimsIncompleteWork) return { action: "accept", assessment };
   if (claimsIncompleteWork) {
@@ -16763,6 +16864,8 @@ async function completionEvidenceDecision({ config, state, store, observers, ste
     contract: assessment.contract,
     evaluation: assessment.evaluation,
     sourceQuality,
+    documentQuality,
+    spreadsheetQuality,
     projectMutationRevision: verificationDeficits.revision,
   });
   const baseDetail = {
@@ -16781,6 +16884,8 @@ async function completionEvidenceDecision({ config, state, store, observers, ste
     requiresFreshFileMutation: freshMutationRequirement.requiresFreshFileMutation,
     requiredFreshMutationRevision: freshMutationRequirement.requiredFreshMutationRevision,
     sourceQualityRepairRequired: freshMutationRequirement.sourceQualityRepairRequired,
+    artifactQualityRepairRequired:
+      freshMutationRequirement.artifactQualityRepairRequired,
     missingToolCalls: assessment.evaluation.missingToolCalls || [],
     pendingProjectCommands: verificationDeficits.pendingCommands,
     pendingProjectTests: verificationDeficits.testsCurrent ? [] : verificationDeficits.discoveredTests,
@@ -16801,6 +16906,13 @@ async function completionEvidenceDecision({ config, state, store, observers, ste
           defects: documentQuality.defects || [],
         }
       : null,
+    spreadsheetQuality: spreadsheetQuality?.checked
+      ? {
+          ok: Boolean(spreadsheetQuality.ok),
+          reason: spreadsheetQuality.reason || "",
+          defects: spreadsheetQuality.defects || [],
+        }
+      : null,
     sourceQuality: sourceQuality.checked
       ? {
           ok: Boolean(sourceQuality.ok),

package/src/command-policy.js

@@ -732,6 +732,115 @@ function structuredValidationCommand(command = "") {
   return null;
 }
 
+const EXTERNAL_VALIDATOR_BASENAME_PATTERN =
+  /(?:^|[._-])(?:acceptance|audit|check|contract|spec|test|validat(?:e|ion)?|validator|verif(?:y|ication))(?:[._-]|$)/i;
+
+function commandScriptOperand(tokens = []) {
+  const executable = path.basename(String(tokens[0] || "")).toLowerCase();
+  if (/^python(?:3(?:\.\d+)*)?$/.test(executable)) {
+    let index = 1;
+    while (index < tokens.length && String(tokens[index] || "").startsWith("-")) {
+      const option = String(tokens[index] || "");
+      if (/^-(?:B|E|I|O|OO|P|q|s|S|u|v|x)$/.test(option)) {
+        index += 1;
+        continue;
+      }
+      if (/^-(?:W|X)$/.test(option) && tokens[index + 1]) {
+        index += 2;
+        continue;
+      }
+      if (/^-(?:W|X).+/.test(option)) {
+        index += 1;
+        continue;
+      }
+      return "";
+    }
+    return String(tokens[index] || "");
+  }
+  if (["bash", "sh", "node"].includes(executable)) {
+    return String(tokens[1] || "");
+  }
+  return "";
+}
+
+export function externalValidatorCommandContract(command = "", config = {}) {
+  const normalized = String(command || "").trim();
+  const sequence = parseTopLevelShellSequence(normalized);
+  if (
+    !normalized ||
+    sequence.commands.length !== 1 ||
+    sequence.separators.length > 0 ||
+    sequence.trailingSeparator ||
+    sequence.openQuote ||
+    sequence.trailingEscape ||
+    hasActiveShellExpansion(normalized)
+  ) {
+    return null;
+  }
+  const tokens = tokenizeShellWords(normalized);
+  const operand = commandScriptOperand(tokens);
+  if (!operand || !/\.(?:c?js|mjs|py|sh)$/i.test(operand)) return null;
+  const basename = path.basename(operand, path.extname(operand));
+  if (!EXTERNAL_VALIDATOR_BASENAME_PATTERN.test(basename)) return null;
+
+  const commandCwd = path.resolve(config.commandCwd || process.cwd());
+  const absolutePath = path.resolve(commandCwd, operand);
+  const relativePath = path.relative(commandCwd, absolutePath);
+  if (
+    !relativePath ||
+    (!relativePath.startsWith("..") && !path.isAbsolute(relativePath))
+  ) {
+    return null;
+  }
+  return {
+    command: normalized,
+    path: absolutePath,
+  };
+}
+
+function commandReferencesOpaqueValidator(command = "", config = {}) {
+  const paths = (Array.isArray(config.opaqueExternalValidatorPaths)
+    ? config.opaqueExternalValidatorPaths
+    : [])
+    .map((item) => path.resolve(String(item || "")))
+    .filter(Boolean);
+  if (!paths.length) return "";
+  const normalized = String(command || "");
+  const commandCwd = path.resolve(config.commandCwd || process.cwd());
+  return paths.find((candidate) => {
+    if (normalized.includes(candidate)) return true;
+    const relative = path.relative(commandCwd, candidate);
+    return Boolean(relative && normalized.includes(relative));
+  }) || "";
+}
+
+function exactOpaqueValidatorExecution(command = "", config = {}) {
+  const requestedTokens = tokenizeShellWords(String(command || "").trim());
+  if (!requestedTokens.length) return false;
+  return (Array.isArray(config.opaqueExternalValidatorCommands)
+    ? config.opaqueExternalValidatorCommands
+    : []).some((candidate) => {
+      const candidateTokens = tokenizeShellWords(String(candidate || "").trim());
+      return candidateTokens.length > 0 &&
+        JSON.stringify(candidateTokens) === JSON.stringify(requestedTokens);
+    });
+}
+
+function opaqueExternalValidatorInspectionBlock(command = "", config = {}) {
+  const referencedPath = commandReferencesOpaqueValidator(command, config);
+  if (!referencedPath || exactOpaqueValidatorExecution(command, config)) return null;
+  return {
+    allowed: false,
+    category: "opaque-external-validator-inspection",
+    recoverable: true,
+    needsApproval: false,
+    writesWorkspace: false,
+    mayMutateProject: false,
+    reason:
+      "The exact external acceptance script is opaque verification evidence. Run its declared command unchanged before inspecting implementation details. If that run fails and its diagnostics are insufficient, the runtime will expose one bounded read-only source view.",
+  };
+}
+
 function classifyBackgroundShell(normalized = "") {
   const sequence = parseTopLevelShellSequence(normalized);
   if (!sequence.separators.includes("&") && sequence.trailingSeparator !== "&") return null;
@@ -2694,6 +2803,19 @@ export function classifyCommand(command) {
 
 export function evaluateCommandPolicy(command, config = {}) {
   const normalizedForPolicy = normalizeCommandForPolicy(command, config);
+  const opaqueValidatorBlock = opaqueExternalValidatorInspectionBlock(
+    normalizedForPolicy,
+    config
+  );
+  if (opaqueValidatorBlock) {
+    return {
+      ...opaqueValidatorBlock,
+      sandboxMode: normalizeSandboxMode(config.sandboxMode),
+      packageInstallPolicy: normalizePackageInstallPolicy(
+        config.packageInstallPolicy
+      ),
+    };
+  }
   const classification = classifyBackgroundShell(normalizedForPolicy) ||
     classifyReadOnlyRootCd(normalizedForPolicy, config) ||
     classifyReadOnlyRootSequence(normalizedForPolicy, config) ||

package/src/engineering-guidance.js

@@ -160,6 +160,7 @@ export function engineeringGuidanceForTask(goal = "", taskProfile = "auto") {
     "Never send sudo passwords or wait at interactive password prompts. If host-level permission is truly required, stop that path, explain the blocker, and provide a manual command instead of hanging.",
     "Shell commands already start in the configured workspace. Prefer workspace-relative commands such as python3 scripts/check.py or cd subdir && make; do not prefix commands with absolute host cd paths unless the tool explicitly requires it.",
     "When you create or fix scripts, reports, tables, generated files, or analysis outputs, inspect the actual output. If it contains obvious duplicates, noisy rows, stale names, broken markdown, or contradictions, patch the source/output and rerun the check rather than merely explaining the defect in the report.",
+    "Treat an exact external acceptance or validator command as opaque verification evidence. Implement from the user request and project-owned instructions, run that command unchanged, and use its diagnostics. Do not read, grep, cat, or reconstruct the external validator before its first failed run; if diagnostics are insufficient, use only the one bounded source view the runtime exposes.",
     "Before claiming a coding task is finished, run git status --short when git is available. Leave the worktree clean, or explicitly report and justify each remaining untracked/unstaged artifact.",
     "Do not claim there are no transient artifacts unless you checked recursively for the relevant stack, such as find . -type d -name __pycache__ -o -name '*.pyc' for Python. A clean git status means tracked work is clean; ignored caches such as __pycache__ may still exist and should be removed or described accurately if relevant.",
     "For generated screenshots, images, PDFs, reports, archives, and app packages, choose a descriptive non-conflicting workspace path when the user did not specify one. Verify the file still exists after cleanup before claiming it was saved.",

package/src/scs-evidence.js

@@ -1616,7 +1616,8 @@ function inferBareRequestedVerifierCommands(goal = "") {
 
 function inferExplicitRequestedCommands(goal = "") {
   const source = stripForbiddenLanguage(goal);
-  const commands = inferBareRequestedVerifierCommands(source);
+  const inferredBareCommands = inferBareRequestedVerifierCommands(source);
+  const explicitCommands = [];
   const inlineCode = /(?<!`)`([^`\r\n]+)`(?!`)/g;
   for (const match of source.matchAll(inlineCode)) {
     const index = Number(match.index || 0);
@@ -1660,9 +1661,18 @@ function inferExplicitRequestedCommands(goal = "") {
       const tokens = tokenizeShellWords(segment);
       return Boolean(tokens.length && !String(tokens[0] || "").startsWith("-"));
     });
-    if (executableSegments) commands.push(command);
-  }
-  return unique(commands).slice(0, 8);
+    if (executableSegments) explicitCommands.push(command);
+  }
+  const explicitTokenSets = explicitCommands.map((command) => tokenizeShellWords(command));
+  const nonShadowedBareCommands = inferredBareCommands.filter((command) => {
+    const bareTokens = tokenizeShellWords(command);
+    return !explicitTokenSets.some(
+      (tokens) =>
+        tokens.length > bareTokens.length &&
+        bareTokens.every((token, index) => tokens[index] === token)
+    );
+  });
+  return unique([...nonShadowedBareCommands, ...explicitCommands]).slice(0, 8);
 }
 
 export function deriveScsTaskContract({ goal = "", taskProfile = "", acceptanceCriteria = [] } = {}) {

package/src/spreadsheet-artifact-quality.js

@@ -0,0 +1,228 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_SHEET_NAME_PATTERN = /^Sheet\d*$/i;
+const OUTPUT_DIRECTORY_NAMES = ["artifacts", "deliverables", "output", "outputs"];
+const XLSX_INSPECTOR = String.raw`
+import json, posixpath, sys, zipfile
+import xml.etree.ElementTree as ET
+
+MAIN = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+DOC_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+PKG_REL = "http://schemas.openxmlformats.org/package/2006/relationships"
+
+path = sys.argv[1]
+with zipfile.ZipFile(path) as archive:
+    names = set(archive.namelist())
+    workbook = ET.fromstring(archive.read("xl/workbook.xml"))
+    relationships = ET.fromstring(archive.read("xl/_rels/workbook.xml.rels"))
+    targets = {
+        item.attrib.get("Id", ""): item.attrib.get("Target", "")
+        for item in relationships.findall(f"{{{PKG_REL}}}Relationship")
+    }
+    sheets = []
+    for item in workbook.findall(f".//{{{MAIN}}}sheet"):
+        relation_id = item.attrib.get(f"{{{DOC_REL}}}id", "")
+        target = targets.get(relation_id, "")
+        if target.startswith("/"):
+            worksheet_path = target.lstrip("/")
+        else:
+            worksheet_path = posixpath.normpath(posixpath.join("xl", target))
+        cells = []
+        formulas = []
+        rows = []
+        if worksheet_path in names:
+            worksheet = ET.fromstring(archive.read(worksheet_path))
+            cells = worksheet.findall(f".//{{{MAIN}}}c")
+            formulas = worksheet.findall(f".//{{{MAIN}}}f")
+            rows = worksheet.findall(f".//{{{MAIN}}}row")
+        sheets.append({
+            "name": item.attrib.get("name", ""),
+            "state": item.attrib.get("state", "visible"),
+            "path": worksheet_path,
+            "cellCount": len(cells),
+            "formulaCount": len(formulas),
+            "rowCount": len(rows),
+        })
+    print(json.dumps({
+        "sheets": sheets,
+        "chartCount": sum(1 for name in names if name.startswith("xl/charts/") and name.endswith(".xml")),
+        "externalLinkCount": sum(1 for name in names if name.startswith("xl/externalLinks/") and name.endswith(".xml")),
+        "hasMacros": "xl/vbaProject.bin" in names,
+    }, ensure_ascii=False))
+`;
+
+function portablePath(value = "") {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function isInsideRoot(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function workbookPathsFromText(value = "") {
+  const paths = [];
+  const pattern = /(?:^|[\s`'"(])((?:[A-Za-z0-9_.-]+\/)*[A-Za-z0-9_.-]+\.xlsx)(?=$|[\s`'"),.;:])/gi;
+  for (const match of String(value || "").matchAll(pattern)) {
+    const candidate = portablePath(match[1]).replace(/^\.\//, "");
+    if (candidate && !paths.includes(candidate)) paths.push(candidate);
+  }
+  return paths;
+}
+
+async function shallowWorkbookCandidates(workspace) {
+  const results = [];
+  for (const relativeDirectory of ["", ...OUTPUT_DIRECTORY_NAMES]) {
+    const directory = path.join(workspace, relativeDirectory);
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".xlsx")) continue;
+      results.push(portablePath(path.join(relativeDirectory, entry.name)));
+    }
+  }
+  return results;
+}
+
+async function inspectWorkbook(absolutePath) {
+  const result = await execFileAsync("python3", ["-c", XLSX_INSPECTOR, absolutePath], {
+    encoding: "utf8",
+    maxBuffer: 4 * 1024 * 1024,
+    timeout: 20_000,
+  });
+  return JSON.parse(String(result.stdout || "{}"));
+}
+
+export function evaluateSpreadsheetStructure(report = {}) {
+  const sheets = Array.isArray(report.sheets) ? report.sheets : [];
+  const defects = [];
+  if (!sheets.length) {
+    defects.push({
+      code: "workbook-has-no-worksheets",
+      message: "The workbook does not contain a readable worksheet.",
+    });
+  } else if (sheets.every((sheet) => Number(sheet?.cellCount || 0) === 0)) {
+    defects.push({
+      code: "workbook-has-no-content",
+      message: "The workbook contains no populated cells.",
+    });
+  }
+  if (sheets.length > 1) {
+    for (const sheet of sheets) {
+      if (
+        String(sheet?.state || "visible") === "visible" &&
+        DEFAULT_SHEET_NAME_PATTERN.test(String(sheet?.name || "")) &&
+        Number(sheet?.cellCount || 0) === 0
+      ) {
+        defects.push({
+          code: "unused-default-worksheet",
+          sheet: String(sheet.name || ""),
+          message: `The workbook retains an empty default worksheet named ${sheet.name}. Remove the placeholder in the canonical producer so every rebuild contains only purposeful sheets.`,
+        });
+      }
+    }
+  }
+  if (Number(report.externalLinkCount || 0) > 0) {
+    defects.push({
+      code: "external-workbook-links",
+      message: "The workbook contains external links, so its calculations are not self-contained and reproducible.",
+    });
+  }
+  if (report.hasMacros === true) {
+    defects.push({
+      code: "macro-payload-in-xlsx",
+      message: "The XLSX package unexpectedly contains a VBA macro payload.",
+    });
+  }
+  return {
+    ok: defects.length === 0,
+    checked: true,
+    sheets,
+    formulaCount: sheets.reduce((sum, sheet) => sum + Number(sheet?.formulaCount || 0), 0),
+    chartCount: Math.max(0, Number(report.chartCount || 0)),
+    defects,
+  };
+}
+
+export async function validateSpreadsheetArtifacts({
+  commandCwd = process.cwd(),
+  candidateResult = "",
+  goal = "",
+  exactOutputPaths = [],
+} = {}) {
+  const workspace = path.resolve(commandCwd || process.cwd());
+  const declared = (Array.isArray(exactOutputPaths) ? exactOutputPaths : [])
+    .map(portablePath)
+    .filter((item) => item.toLowerCase().endsWith(".xlsx"));
+  const mentioned = workbookPathsFromText(candidateResult);
+  const discovered = declared.length || mentioned.length || !/\b(?:excel|spreadsheet|workbook|xlsx)\b/i.test(goal)
+    ? []
+    : await shallowWorkbookCandidates(workspace);
+  const candidates = [...new Set([...declared, ...mentioned, ...discovered])];
+  if (!candidates.length) {
+    return {
+      ok: true,
+      checked: false,
+      artifacts: [],
+      defects: [],
+      reason: "No current XLSX artifact required structural validation.",
+    };
+  }
+
+  const artifacts = [];
+  const defects = [];
+  for (const candidate of candidates) {
+    const absolutePath = path.resolve(workspace, candidate);
+    if (!isInsideRoot(workspace, absolutePath)) {
+      defects.push({
+        code: "spreadsheet-outside-workspace",
+        path: candidate,
+        message: `The workbook ${candidate} is outside the configured workspace.`,
+      });
+      continue;
+    }
+    const stat = await fs.stat(absolutePath).catch(() => null);
+    if (!stat?.isFile()) {
+      defects.push({
+        code: "missing-spreadsheet-artifact",
+        path: candidate,
+        message: `The workbook ${candidate} does not exist.`,
+      });
+      continue;
+    }
+    try {
+      const structure = evaluateSpreadsheetStructure(await inspectWorkbook(absolutePath));
+      artifacts.push({
+        path: portablePath(path.relative(workspace, absolutePath)),
+        sheets: structure.sheets,
+        formulaCount: structure.formulaCount,
+        chartCount: structure.chartCount,
+      });
+      defects.push(...structure.defects.map((item) => ({
+        ...item,
+        path: portablePath(path.relative(workspace, absolutePath)),
+      })));
+    } catch (error) {
+      defects.push({
+        code: "spreadsheet-extraction-failed",
+        path: candidate,
+        message: `Could not independently inspect ${candidate}: ${String(error?.message || error).slice(0, 300)}.`,
+      });
+    }
+  }
+
+  return {
+    ok: defects.length === 0 && artifacts.length > 0,
+    checked: true,
+    artifacts,
+    defects,
+    reason: defects.length
+      ? defects.map((item) => `${item.path ? `${item.path}: ` : ""}${item.message}`).join(" ")
+      : artifacts.length
+        ? `Independent spreadsheet structure checks passed for ${artifacts.map((item) => item.path).join(", ")}.`
+        : "No readable workbook artifact was available for structural validation.",
+  };
+}

package/src/task-profiles.js

@@ -87,7 +87,7 @@ export const TASK_PROFILES = {
     id: "data",
     label: "Data analysis",
     prompt:
-      "Bias toward reproducible data analysis, cleanup, ETL, visualization, and report generation while staying able to write scripts or docs. Before touching data, inspect the project and read its AGINTI/AGENTS/README instructions plus relevant existing analysis code, configuration, and tests. Local mutation and command tools intentionally remain unavailable until this bounded discovery is complete. Treat raw/source/input exports as immutable evidence unless the user explicitly authorizes an in-place source change; implement normalization in reproducible code and write generated results under the project's declared output paths. Inspect data shape, schema, units, missing values, duplicates, aliases, and audit requirements before drawing conclusions. Run the existing analyzer and focused tests, save plots/reports as durable artifacts, verify requested paths and statistics externally, and explain assumptions, limitations, and data quality issues.",
+      "Bias toward reproducible data analysis, cleanup, ETL, visualization, spreadsheets, and report generation while staying able to write scripts or docs. Before touching data, inspect the project and read its AGINTI/AGENTS/README instructions plus relevant existing analysis code, configuration, and tests. Local mutation and command tools intentionally remain unavailable until this bounded discovery is complete. Treat raw/source/input exports as immutable evidence unless the user explicitly authorizes an in-place source change; implement normalization in reproducible code and write generated results under the project's declared output paths. Inspect data shape, schema, units, missing values, duplicates, aliases, and audit requirements before drawing conclusions. For editable XLSX workbooks, preserve purposeful raw and calculated sheets, use formulas where the workbook is meant to remain live, remove empty default Sheet/Sheet1 placeholders, and inspect the actual sheet names, formulas, charts, and rendered user-facing views. Do not invent extra deliverables during a bounded correction. Run the existing analyzer and focused tests, save plots/reports as durable artifacts, verify requested paths and statistics externally, and explain assumptions, limitations, and data quality issues.",
     tools: ["inspect_project", "files", "shell", "canvas", "sandbox"],
   },
   qa: {