@lazyingart/agintiflow 0.20.298 → 0.20.300

package/docs/perception-and-web-research.md

@@ -6,7 +6,7 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 
 | Tool | Purpose | Evidence |
 | --- | --- | --- |
-| `read_image` | Read workspace screenshots, plots, scanned text, diagrams, or allowed remote image URLs. | Saves JSON and Markdown reports under `artifacts/perception/`, records image hashes, and sends the Markdown report to the canvas when used by an agent run. |
+| `read_image` | Read workspace screenshots, plots, scanned text, diagrams, or allowed remote image URLs. | Saves canonical JSON/Markdown evidence in the session artifact store, keeps the workspace-relative canvas copy under ignored `.aginti/artifacts/perception/`, and records image hashes. |
 | `web_search` | Cheap raw search snippets or a bounded multi-provider ensemble. | Returns compact titles, canonical URLs, snippets, provider attempts, and per-provider discovery evidence. |
 | `read_web_page` | Read one exact public source instead of relying on a snippet. | Returns bounded article/PDF text, metadata, canonical URL, relevant passages, retrieval time, and content hash. |
 | `web_research` | Sourced research unit for current or external information. | Saves `artifacts/research/*-web-research.json` with query, mode, source list, and answer. |
@@ -18,6 +18,7 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 - In a LocalLLM session, `read_image provider=auto` sends bounded image data to the loopback LocalLLM Chat Completions endpoint with `AGINTI_LOCALLLM_VISION_MODEL` or `localllm-vision-xl`. It does not try OpenAI or a wrapper after a local failure.
 - In an OpenAI session, `read_image provider=auto` uses OpenAI Responses vision. A non-OpenAI session must set `allowHostedImagePerception=true` before `provider=openai` is accepted. `OPENAI_API_KEY` by itself grants no permission.
 - Codex image reading requires both `provider=codex` and explicitly enabled wrapper tools. It is not an automatic fallback.
+- Visual verification never creates a task-owned `artifacts/perception/` tree. Its workspace-relative Markdown copy stays under ignored `.aginti/` storage so a successful review cannot dirty an otherwise clean repository.
 - OpenAI image reading defaults to `AGINTI_PERCEPTION_MODEL=gpt-5.4-mini` and `AGINTI_PERCEPTION_REASONING=medium`, with fallback models remaining inside the same explicitly selected OpenAI provider.
 - `web_research` defaults to lightweight snippet mode. The active LocalLLM can synthesize those returned snippets and sources during the next agent step without a second provider call.
 - `web_search provider=auto` falls back from DuckDuckGo HTML to Bing RSS. `provider=multi` merges both indexes and adds Brave only when explicitly configured. Standard/deep research defaults to this ensemble; quick research stays on auto.

package/docs/runtime-modes-and-autonomy.md

@@ -132,6 +132,10 @@ This starts interactive chat with Docker workspace mode, file tools, shell tools
 
 Docker workspace mode also mounts common host data roots, such as the user's home parent, read-only at their original absolute paths. This lets a task in `/home/lachlan/ProjectsLFS/aginti-test` inspect a sibling dataset such as `/home/lachlan/ProjectsLFS/ProteinStructure` without switching to host-write mode. Outputs and edits still belong under `/workspace` unless the user explicitly approves stronger host permissions. Set `AGINTI_DOCKER_READONLY_HOST_MOUNTS=/path/a:/path/b` to override the read-only mounts, or set it to `off` to disable them.
 
+For a linked Git worktree, bounded Git mutation commands such as the runtime's path-enumerated `git add` plus `git commit` also receive a writable mount for the validated shared Git common directory. The mount is not added to ordinary shell commands or read-only Git inspection. This lets Docker workspace mode commit the current worktree without granting broad host-write access.
+
+Outstanding exact project commands always run before Git completion. A pending producer, test, or user-declared validation command cannot be preempted by a commit merely because the current artifacts already exist.
+
 Direct trusted host mode:
 
 ```bash

package/docs/supervision-campaign-ledger.md

@@ -56,6 +56,29 @@ in `evidence_json` and `events`.
 
 ## Current Campaign Findings
 
+### Retained dependencies, linked-worktree commits, and clean visual evidence
+
+`data-analysis-retained-dependencies-060` resumed the original DeepSeek session
+after an imperfect data-analysis repair had narrowed its context too far. The
+agent retained the immutable configuration and CSV inputs referenced by the
+mutable Python source, regenerated every required output, ran the canonical
+producer and all four unit tests, inspected the 900 x 600 plot, and committed
+target revision `55cadcd` from Docker workspace mode. Independent verification
+confirmed 11 raw rows, one duplicate removal, two invalid-signal removals,
+eight clean rows, the expected condition means, valid CSV/JSON/Markdown/PNG
+artifacts, and a clean target worktree.
+
+The run established three reusable runtime contracts:
+
+- Failed-test recovery keeps bounded, previously read immutable dependencies
+  when the mutable source names them, while mutation scope remains limited to
+  the canonical repair paths.
+- An outstanding exact producer or validation command runs before artifact Git
+  completion. In a linked worktree, only bounded Git mutation commands receive
+  a writable mount for the validated shared Git common directory.
+- `read_image` stores its task-relative review copy under ignored `.aginti/`
+  runtime storage, so visual verification cannot dirty a completed repository.
+
 ### Data analysis retained-state recovery
 
 `data-analysis-local-011` passed after reusable runtime fixes. AgInTi completed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.298",
+  "version": "0.20.300",
   "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-docker-command.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import {
+  dockerWritableGitMounts,
   dockerWorkspaceAliasMounts,
   ensureDockerGitIdentity,
 } from "../src/docker-sandbox.js";
@@ -52,6 +53,47 @@ try {
   assert.equal(storedEmail.stdout.trim(), "aginti-test@example.invalid");
   assert.equal((await fs.stat(identityConfig)).mode & 0o777, 0o600, "Docker author config should be private");
 
+  const worktreeRoot = path.join(tempRoot, "worktree-root");
+  const linkedWorktree = path.join(tempRoot, "linked-worktree");
+  await execFileAsync("git", ["init", worktreeRoot]);
+  await execFileAsync("git", ["-C", worktreeRoot, "config", "user.name", "AgInTi Test Author"]);
+  await execFileAsync("git", ["-C", worktreeRoot, "config", "user.email", "aginti-test@example.invalid"]);
+  await fs.writeFile(path.join(worktreeRoot, "seed.txt"), "seed\n", "utf8");
+  await execFileAsync("git", ["-C", worktreeRoot, "add", "seed.txt"]);
+  await execFileAsync("git", ["-C", worktreeRoot, "commit", "-m", "seed"]);
+  await execFileAsync("git", ["-C", worktreeRoot, "worktree", "add", "-b", "linked-test", linkedWorktree]);
+  const linkedCommonDir = (await execFileAsync(
+    "git",
+    ["-C", linkedWorktree, "rev-parse", "--path-format=absolute", "--git-common-dir"]
+  )).stdout.trim();
+  assert.deepEqual(
+    dockerWritableGitMounts(
+      "git add -- changed.txt && git commit -m 'linked worktree change'",
+      { commandCwd: linkedWorktree, sandboxMode: "docker-workspace" },
+      { gitOnly: true }
+    ),
+    [linkedCommonDir],
+    "Docker Git mutation did not mount validated linked-worktree metadata writable"
+  );
+  assert.deepEqual(
+    dockerWritableGitMounts(
+      "git status --short",
+      { commandCwd: linkedWorktree, sandboxMode: "docker-workspace" },
+      { gitOnly: true }
+    ),
+    [],
+    "read-only Git inspection received an unnecessary writable metadata mount"
+  );
+  assert.deepEqual(
+    dockerWritableGitMounts(
+      "git add -- seed.txt",
+      { commandCwd: worktreeRoot, sandboxMode: "docker-workspace" },
+      { gitOnly: true }
+    ),
+    [],
+    "ordinary repositories should rely on the existing writable workspace mount"
+  );
+
   const { stdout } = await execFileAsync(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), "docker", "status", "--json", "--cwd", tempRoot], {
     cwd: tempRoot,
     env: {

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

@@ -572,6 +572,98 @@ try {
       duplicateFocus?.duplicateDeclarations?.[0]?.name === "status_service",
     "duplicate production declarations were not promoted into a focused failed-test repair"
   );
+  const dependencyRecoveryWorkspace = path.join(tempRoot, "dependency-recovery-workspace");
+  await fs.mkdir(path.join(dependencyRecoveryWorkspace, "config"), { recursive: true });
+  await fs.mkdir(path.join(dependencyRecoveryWorkspace, "raw"), { recursive: true });
+  await fs.mkdir(path.join(dependencyRecoveryWorkspace, "tests"), { recursive: true });
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "analysis.py"),
+    [
+      "from pathlib import Path",
+      "import json",
+      "",
+      "ROOT = Path(__file__).resolve().parent",
+      "config = json.loads((ROOT / 'config' / 'experiment.json').read_text())",
+      "for source_file in ('run_a.csv', 'run_b.csv'):",
+      "    print((ROOT / 'raw' / source_file).read_text())",
+      "",
+    ].join("\n"),
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "tests", "test_analysis.py"),
+    "from analysis import config\n",
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "config", "experiment.json"),
+    '{"offset":10}\n',
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "raw", "run_a.csv"),
+    "sample,signal\nA,100\n",
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "raw", "run_b.csv"),
+    "sample,signal\nB,90\n",
+    "utf8"
+  );
+  await fs.writeFile(
+    path.join(dependencyRecoveryWorkspace, "raw", "unrelated.csv"),
+    "private,unrelated\nno,1\n",
+    "utf8"
+  );
+  const dependencyRecoveryState = {
+    meta: {
+      projectVerification: {
+        mutationRevision: 2,
+        lastMutation: {
+          revision: 2,
+          toolName: "apply_patch",
+          paths: ["analysis.py"],
+        },
+        discoveredTests: ["tests/test_analysis.py"],
+        testRuns: [{
+          command: "python analysis.py",
+          mutationRevision: 2,
+          passed: false,
+          failureEvidenceVersion: 2,
+          failureSignature: "source-dependency-schema-mismatch",
+          failureSummary: "File \"analysis.py\", line 7, in <module>: KeyError: signal_mv",
+        }],
+      },
+      toolLoop: {
+        recent: [
+          "config/experiment.json",
+          "raw/run_a.csv",
+          "raw/run_b.csv",
+          "raw/unrelated.csv",
+        ].map((readPath) => ({
+          toolName: "read_file",
+          path: readPath,
+          ok: true,
+          blocked: false,
+        })),
+      },
+    },
+  };
+  const dependencyRecoveryPacket = await buildFailedTestRecoveryPacket(
+    { commandCwd: dependencyRecoveryWorkspace },
+    dependencyRecoveryState
+  );
+  assert(
+    [
+      "analysis.py",
+      "config/experiment.json",
+      "raw/run_a.csv",
+      "raw/run_b.csv",
+    ].every((item) => dependencyRecoveryPacket.paths.includes(item)) &&
+      !dependencyRecoveryPacket.paths.includes("raw/unrelated.csv") &&
+      JSON.stringify(dependencyRecoveryPacket.repairPaths) === JSON.stringify(["analysis.py"]),
+    `failed-test recovery dropped previously read immutable dependencies or widened mutation scope: ${JSON.stringify(dependencyRecoveryPacket)}`
+  );
   const baselineWorkspace = path.join(tempRoot, "baseline-recovery-workspace");
   await fs.mkdir(baselineWorkspace, { recursive: true });
   const trackedBaselineSource = [

package/scripts/smoke-perception-research.js

@@ -343,6 +343,10 @@ async function main() {
   assert(image.artifactPath, "read_image did not persist a perception artifact");
   assert(image.markdownArtifactPath, "read_image did not persist a Markdown perception artifact");
   assert(image.markdownPath, "read_image did not persist a workspace Markdown report");
+  assert(
+    image.markdownPath.startsWith(".aginti/artifacts/perception/"),
+    `read_image dirtied the task-owned artifact tree: ${image.markdownPath}`
+  );
   assert(
     path.basename(image.markdownPath).includes("tiny-image-analysis"),
     `read_image emitted a generic artifact filename: ${image.markdownPath}`

package/scripts/smoke-progressive-tool-selection.js

@@ -1584,6 +1584,30 @@ assertStrict.deepEqual(
   "task-owned Git completion delegated path selection back to the model"
 );
 
+const requiredCommandBeforeCommitTools = selectProgressiveTools(allTools, {
+  config: {
+    provider: "localllm",
+    artifactValidationPhase: true,
+    artifactValidationNeedsCommand: true,
+    requiredProjectCommandPending: true,
+    requiredProjectCommand: "python analysis.py",
+    artifactValidationPendingGitActions: ["commit"],
+    artifactValidationCommitPaths: ["analysis.py", "AGINTI.md"],
+  },
+  goal: "Regenerate the outputs, validate them, and commit the intended repair.",
+  profile: "data",
+});
+sameNames(
+  requiredCommandBeforeCommitTools,
+  ["run_command", "finish"],
+  "artifact Git completion preempted an outstanding exact project command"
+);
+assertStrict.deepEqual(
+  requiredCommandBeforeCommitTools[0].function.parameters.properties.command.enum,
+  ["python analysis.py"],
+  "artifact recovery exposed an open-ended command instead of the retained requirement"
+);
+
 const resumedArtifactRuntime = nextStepRuntimeConfig(
   {
     goal: "Perform a visual screenshot inspection of the generated plot and commit the intentional changes.",

package/scripts/smoke-truthful-completion.js

@@ -309,6 +309,11 @@ try {
     String(explanation.state.messages.find((message) => message.role === "system")?.content || "").length < 10_000,
     "focused runtime prompt did not use progressive disclosure"
   );
+  assert.match(
+    String(explanation.state.messages.find((message) => message.role === "system")?.content || ""),
+    /run that command unchanged before probing --help, alternate wrappers/i,
+    "focused runtime did not prioritize exact established routine commands"
+  );
   assert(
     Math.max(
       ...explanation.state.messages

package/src/agent-runner.js

@@ -2801,6 +2801,7 @@ function focusedCapabilityContext(config = {}) {
       ? `Advisory wrapper: ${normalizeWrapperName(config.preferredWrapper)} (${wrapperStatusText()}).`
       : "Advisory wrappers: disabled.",
     config.allowAuxiliaryTools ? "Auxiliary generation tools: enabled when the requested artifact needs them." : "Auxiliary tools: disabled.",
+    "When the current request, project instructions, or routine contract names an exact established command, run that command unchanged before probing --help, alternate wrappers, process lists, or implementation source. If its result answers the request, stop discovery and finish.",
     "Discovery must be bounded: after a blocked path or search, change method once; never use recursive grep. Prefer exact manifests, workspace search, or targeted rg with an explicit path, globs, and result limit.",
     isRetainedWorkspaceProfile(config)
       ? isRetainedVisionWorkspaceProfile(config)
@@ -8494,7 +8495,7 @@ export function taskForbidsExternalValidatorSourceRead(config = {}, state = {})
 function recoveryEvidenceDependencies(
   sourcePath = "",
   content = "",
-  { commandCwd = "" } = {}
+  { commandCwd = "", knownReadPaths = [] } = {}
 ) {
   const explicitDependencies = [];
   const importCandidates = [];
@@ -8530,7 +8531,7 @@ function recoveryEvidenceDependencies(
     append(explicitDependencies, path.posix.normalize(raw));
   }
   for (const match of String(content || "").matchAll(
-    /^\s*[A-Za-z_][A-Za-z0-9_]*\s*=\s*[A-Za-z_][A-Za-z0-9_]*(?<segments>(?:\s*\/\s*["'][^"'\r\n]+["']){1,8})\s*$/gm
+    /\b[A-Za-z_][A-Za-z0-9_]*(?<segments>(?:\s*\/\s*["'][^"'\r\n]+["']){1,8})/g
   )) {
     const segments = [...String(match.groups?.segments || "").matchAll(/["']([^"'\r\n]+)["']/g)]
       .map((segment) => String(segment[1] || "").trim())
@@ -8539,6 +8540,22 @@ function recoveryEvidenceDependencies(
       append(explicitDependencies, path.posix.normalize(segments.join("/")));
     }
   }
+  const sourceText = String(content || "");
+  for (const item of Array.isArray(knownReadPaths) ? knownReadPaths : []) {
+    const candidate = safeRecoveryEvidencePath(item);
+    if (!candidate || safeTaskOwnedCommitPath(candidate) !== candidate) continue;
+    const basename = path.posix.basename(candidate);
+    const parentBasename = path.posix.basename(path.posix.dirname(candidate));
+    if (!basename || !sourceText.includes(basename)) continue;
+    if (
+      parentBasename &&
+      parentBasename !== "." &&
+      !sourceText.includes(parentBasename)
+    ) {
+      continue;
+    }
+    append(explicitDependencies, candidate);
+  }
   if (path.posix.extname(sourcePath).toLowerCase() === ".java") {
     const normalizedSource = String(sourcePath || "").replace(/\\/g, "/");
     const packageMatch = String(content || "").match(
@@ -8959,6 +8976,19 @@ export async function buildFailedTestRecoveryPacket(config = {}, state = {}) {
     state,
     testRun
   );
+  const knownReadPaths = (Array.isArray(state.meta?.toolLoop?.recent)
+    ? state.meta.toolLoop.recent
+    : [])
+    .filter(
+      (entry) =>
+        entry?.ok === true &&
+        entry?.blocked !== true &&
+        String(entry?.toolName || "") === "read_file"
+    )
+    .map((entry) => safeRecoveryEvidencePath(toolLoopReadEvidencePath(entry) || entry?.path))
+    .filter((item) => item && safeTaskOwnedCommitPath(item) === item)
+    .filter((item, index, items) => items.indexOf(item) === index)
+    .slice(-24);
   const queue = [
     ...failureMentionedPaths.filter(failedTestPathIsTestEvidence),
     ...(Array.isArray(verification.discoveredTests) ? verification.discoveredTests : []),
@@ -9535,7 +9565,10 @@ export async function buildFailedTestRecoveryPacket(config = {}, state = {}) {
         );
       }
     }
-    for (const dependency of recoveryEvidenceDependencies(relativePath, raw, { commandCwd })) {
+    for (const dependency of recoveryEvidenceDependencies(relativePath, raw, {
+      commandCwd,
+      knownReadPaths,
+    })) {
       if (!seen.has(dependency) && !queue.includes(dependency)) queue.push(dependency);
     }
   }

package/src/docker-sandbox.js

@@ -196,6 +196,63 @@ export function dockerWorkspaceAliasMounts(
   return workspace === DOCKER_WORKSPACE ? [] : [workspace];
 }
 
+function pathIsWithin(parentPath, candidatePath) {
+  const relative = path.relative(parentPath, candidatePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function linkedWorktreeCommonGitDir(workspace) {
+  const dotGitPath = path.join(workspace, ".git");
+  let dotGit;
+  try {
+    if (!fsSync.statSync(dotGitPath).isFile()) return "";
+    dotGit = fsSync.readFileSync(dotGitPath, "utf8");
+  } catch {
+    return "";
+  }
+  const match = String(dotGit).match(/^gitdir:\s*(.+?)\s*$/im);
+  if (!match?.[1]) return "";
+  const gitDir = path.resolve(workspace, match[1]);
+  let commonDir = gitDir;
+  try {
+    const commonPath = path.join(gitDir, "commondir");
+    if (fsSync.existsSync(commonPath)) {
+      commonDir = path.resolve(gitDir, fsSync.readFileSync(commonPath, "utf8").trim());
+    }
+    const resolvedGitDir = fsSync.realpathSync(gitDir);
+    const resolvedCommonDir = fsSync.realpathSync(commonDir);
+    if (
+      !pathIsWithin(resolvedCommonDir, resolvedGitDir) ||
+      !fsSync.existsSync(path.join(resolvedCommonDir, "HEAD")) ||
+      !fsSync.existsSync(path.join(resolvedCommonDir, "objects"))
+    ) {
+      return "";
+    }
+    return resolvedCommonDir;
+  } catch {
+    return "";
+  }
+}
+
+export function dockerWritableGitMounts(
+  command = "",
+  config = {},
+  policy = {},
+  sandboxMode = normalizeSandboxMode(config.sandboxMode)
+) {
+  if (
+    sandboxMode !== "docker-workspace" ||
+    policy.gitOnly !== true ||
+    !/\bgit\s+(?:add|commit|rm|mv)\b/i.test(String(command || ""))
+  ) {
+    return [];
+  }
+  const workspace = path.resolve(String(config.commandCwd || process.cwd()));
+  const commonDir = linkedWorktreeCommonGitDir(workspace);
+  if (!commonDir || pathIsWithin(workspace, commonDir)) return [];
+  return uniqueHostMounts([commonDir]);
+}
+
 async function ensurePersistentDockerDirs(config) {
   const dirs = persistentDockerDirs(config);
   await Promise.all([fs.mkdir(dirs.home, { recursive: true }), fs.mkdir(dirs.cache, { recursive: true }), fs.mkdir(dirs.env, { recursive: true })]);
@@ -381,6 +438,12 @@ function dockerRunArgs(command, config, policy = evaluateCommandPolicy(command,
     "-v",
     `${mount}:${mount}:${mountMode}`,
   ]);
+  const writableGitMountArgs = dockerWritableGitMounts(
+    command,
+    config,
+    policy,
+    sandboxMode
+  ).flatMap((mount) => ["-v", `${mount}:${mount}:rw`]);
   const readOnlyArgs =
     mountMode === "ro"
       ? ["--read-only", "--tmpfs", "/tmp:rw,nosuid,nodev,size=128m"]
@@ -412,6 +475,7 @@ function dockerRunArgs(command, config, policy = evaluateCommandPolicy(command,
       ? ["-e", `GIT_CONFIG_GLOBAL=${DOCKER_GIT_CONFIG}`]
       : []),
     ...readOnlyHostMountArgs,
+    ...writableGitMountArgs,
     ...workspaceAliasMountArgs,
     "-v",
     `${config.commandCwd}:${DOCKER_WORKSPACE}:${mountMode}`,

package/src/perception-tools.js

@@ -302,7 +302,10 @@ async function persistMarkdownArtifact(store, config, subdir, stem, payload) {
   }
 
   if (config?.commandCwd) {
-    const workspaceDir = path.join(config.commandCwd, "artifacts", subdir);
+    // Perception reports are runtime evidence, not task-owned source. Keep the
+    // workspace-relative copy under the standard ignored AgInTi directory so
+    // visual validation cannot dirty an otherwise completed repository.
+    const workspaceDir = path.join(config.commandCwd, ".aginti", "artifacts", subdir);
     await fs.mkdir(workspaceDir, { recursive: true });
     const workspacePath = path.join(workspaceDir, filename);
     await fs.writeFile(workspacePath, content, "utf8");

package/src/progressive-tool-selection.js

@@ -2304,7 +2304,8 @@ export function selectProgressiveTools(
   if (
     config.taskOwnedCommitPending === true &&
     config.testFailureRepairActive !== true &&
-    config.testVerificationPending !== true
+    config.testVerificationPending !== true &&
+    config.requiredProjectCommandPending !== true
   ) {
     const available = new Map(enabled.map(({ name, tool }) => [name, tool]));
     const pendingGitActions = Array.isArray(config.taskOwnedPendingGitActions)
@@ -2332,6 +2333,18 @@ export function selectProgressiveTools(
     config.testVerificationPending !== true
   ) {
     const available = new Map(enabled.map(({ name, tool }) => [name, tool]));
+    if (
+      config.requiredProjectCommandPending === true &&
+      typeof config.requiredProjectCommand === "string" &&
+      config.requiredProjectCommand.trim()
+    ) {
+      const requiredCommand = constrainRunCommand(
+        available.get("run_command"),
+        config.requiredProjectCommand,
+        "Run this exact outstanding project command before Git completion or final artifact acceptance. Preserve the generated outputs and do not substitute another status, commit, or discovery command."
+      );
+      return [requiredCommand, finish].filter(Boolean);
+    }
     const pendingGitActions = Array.isArray(config.artifactValidationPendingGitActions)
       ? config.artifactValidationPendingGitActions.map((item) => String(item || "").toLowerCase())
       : [];