@cassiomc1/forgeloop 0.1.15 → 1.0.0

package/src/commands/doctor.js

@@ -1,4 +1,4 @@
-import { assertSafePath, fileExists, ensureWithin, readBytes } from "../core/filesystem.js";
+import { assertSafePath, fileExists, ensureWithin, readBytes, writeFileAtomic } from "../core/filesystem.js";
 import { readManifest, sha256, writeManifest } from "../core/manifest.js";
 import { readTemplateEntries } from "../core/templates.js";
 import { createEvidence } from "../core/evidence.js";
@@ -113,9 +113,10 @@ async function adoptAdapters({ target, manifest, adoptPaths, findings }) {
   return nextManifest;
 }
 
-export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false }) {
+export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false, fix = false }) {
   const findings = [];
   let manifest = null;
+  let manifestChanged = false;
   try {
     manifest = await readManifest(target);
     if (!manifest) {
@@ -186,6 +187,16 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
         ));
         continue;
       }
+      if (fix && manifest && (layoutVersion >= LAYOUT_VERSION || managedPath.startsWith(".forgeloop/"))) {
+        await writeFileAtomic(destination, entry.bytes);
+        manifest.files[managedPath] = {
+          sha256: sha256(entry.bytes),
+          preserve: entry.sourcePath === "PROJECT_PROFILE.md",
+        };
+        manifestChanged = true;
+        findings.push(finding("file-restored", "info", managedPath, "Restored missing managed template file.", "No action required."));
+        continue;
+      }
       findings.push(finding("file-missing", "error", managedPath, "Managed file is missing."));
       continue;
     }
@@ -280,6 +291,10 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
     }
   }
 
+  if (manifestChanged && manifest) {
+    await writeManifest(target, manifest);
+  }
+
   const ok = findings.every((item) => item.severity !== "error")
     && (!strict || findings.every((item) => item.severity !== "warning"));
   return {

package/src/commands/reconcile-continuity.js

@@ -0,0 +1,23 @@
+import { reconcileContinuity } from "../core/continuity-reconciliation.js";
+
+export async function runReconcileContinuity({ target, packageRoot } = {}) {
+  return reconcileContinuity({ target, packageRoot });
+}
+
+export function formatReconcileContinuityResult(result) {
+  const lines = [
+    `Continuity: ${result.path ?? ".forgeloop/continuity.json"}`,
+    `Classification: ${result.classification}`,
+    `Task matches: ${result.taskMatches ?? "not-verified"}`,
+    `Work state matches: ${result.workStateMatches ?? "not-verified"}`,
+    `Contract matches: ${result.contractMatches ?? "not-verified"}`,
+    `Phase matches: ${result.phaseMatches ?? "not-verified"}`,
+    `Repository: ${result.repositoryComparison}`,
+    `Changed paths: ${result.changedPathComparison}`,
+    "Authority: OPERATIONAL_CONTEXT_ONLY",
+    "Evidence: NONE",
+  ];
+  if (result.reasonCodes?.length) lines.push(`Reason codes: ${result.reasonCodes.join(", ")}`);
+  if (result.reasons?.length) lines.push(`Reasons: ${result.reasons.join(", ")}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/record-continuity.js

@@ -0,0 +1,63 @@
+import { writeContinuity } from "../core/continuity.js";
+
+function parseWorkItem(value, label) {
+  if (typeof value !== "string") throw new Error(`${label} must use <id>:<summary>`);
+  const separator = value.indexOf(":");
+  if (separator <= 0 || separator === value.length - 1) {
+    throw new Error(`${label} must use <id>:<summary>`);
+  }
+  return {
+    id: value.slice(0, separator).trim(),
+    summary: value.slice(separator + 1).trim(),
+  };
+}
+
+export async function runRecordContinuity({
+  target,
+  packageRoot,
+  focusId,
+  focusSummary,
+  remaining = [],
+  knownIssues = [],
+  changedAreas = [],
+  inspectFirst = [],
+  resumeNote,
+  state,
+  contract,
+  repositoryFingerprint,
+  now,
+  dryRun = false,
+} = {}) {
+  if ((focusId && !focusSummary) || (!focusId && focusSummary)) {
+    throw new Error("record-continuity requires --focus-id and --focus-summary together");
+  }
+  return writeContinuity(target, {
+    ...(focusId ? { currentFocus: { id: focusId, summary: focusSummary } } : {}),
+    remainingWork: remaining.map((item) => parseWorkItem(item, "--remaining")),
+    knownIssues: knownIssues.map((item) => parseWorkItem(item, "--known-issue")),
+    changedAreas,
+    inspectFirst,
+    ...(resumeNote ? { resumeNote } : {}),
+  }, {
+    packageRoot,
+    ...(state ? { state } : {}),
+    ...(contract ? { contract } : {}),
+    ...(repositoryFingerprint ? { repositoryFingerprint } : {}),
+    ...(now ? { now } : {}),
+    dryRun,
+  });
+}
+
+export function formatRecordContinuityResult(result) {
+  const value = result.value;
+  return [
+    `Continuity: ${result.path}`,
+    `Task: ${value.taskId}`,
+    `Phase: ${value.phase}`,
+    `Focus: ${value.currentFocus?.id ?? "none"}`,
+    `Remaining: ${value.remainingWork.length}`,
+    `Known issues: ${value.knownIssues.length}`,
+    "Authority: OPERATIONAL_CONTEXT_ONLY",
+    "Evidence: NONE",
+  ].join("\n") + "\n";
+}

package/src/commands/status.js

@@ -1,12 +1,17 @@
 import { readAndClassifyWorkState } from "../core/work-state.js";
 import { inspectSchemaHealth } from "../core/schema-validation.js";
+import { reconcileContinuity } from "../core/continuity-reconciliation.js";
 
 export async function runStatus({ target, packageRoot, contractFile = null }) {
   const state = await readAndClassifyWorkState({ target, packageRoot, contractFile });
-  const protocol = await inspectSchemaHealth(target);
+  const [protocol, continuity] = await Promise.all([
+    inspectSchemaHealth(target),
+    reconcileContinuity({ target, packageRoot }),
+  ]);
   return {
     ...state,
     protocol,
+    continuity,
     evidence: [...(state.evidence ?? []), ...(protocol.evidence ?? [])],
   };
 }
@@ -24,6 +29,14 @@ export function formatStatusResult(result) {
   if (result.contractComparison) lines.push(`Contract: ${result.contractComparison}`);
   if (result.artifactComparison) lines.push(`Artifacts: ${result.artifactComparison}`);
   if (result.protocol) lines.push(`Schemas: ${result.protocol.status}`);
+  if (result.continuity) {
+    const continuity = result.continuity.continuity;
+    lines.push(`Continuity: ${result.continuity.classification}`);
+    lines.push(`Continuity focus: ${continuity?.currentFocus?.id ?? "none"}`);
+    lines.push(`Continuity remaining: ${continuity?.remainingWork?.length ?? 0}`);
+    lines.push(`Continuity known issues: ${continuity?.knownIssues?.length ?? 0}`);
+    lines.push(`Continuity authority: ${result.continuity.authority ?? "OPERATIONAL_CONTEXT_ONLY"}`);
+  }
   if (result.error) lines.push(`Error: ${result.error}`);
   return `${lines.join("\n")}\n`;
 }

package/src/commands/update.js

@@ -9,9 +9,8 @@ import {
   writeManifest,
 } from "../core/manifest.js";
 import { readTemplateEntries } from "../core/templates.js";
-import { isNativeAdapterPath, LAYOUT_VERSION } from "../core/target-layout.js";
+import { isNativeAdapterPath, LAYOUT_VERSION, LEGACY_PROFILE_PATH } from "../core/target-layout.js";
 
-const PROFILE_PATH = "PROJECT_PROFILE.md";
 const LEGACY_CLEANUP_DIRECTORIES = Object.freeze(["ENG", "schemas"]);
 
 function migrationConflict(code, path, message) {
@@ -169,7 +168,7 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
       const legacyHash = legacyBytes ? sha256(legacyBytes) : null;
       const unchangedManagedLegacy = Boolean(legacyRecord) && legacyHash === legacyRecord.sha256;
 
-      if (entry.sourcePath === PROFILE_PATH
+      if (entry.sourcePath === LEGACY_PROFILE_PATH
         && legacyExists
         && legacyRecord
         && currentHash === legacyHash) {
@@ -179,7 +178,7 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
         continue;
       }
 
-      if (!hiddenMatchesSource && !destinationRecord && entry.sourcePath !== PROFILE_PATH) {
+      if (!hiddenMatchesSource && !destinationRecord && entry.sourcePath !== LEGACY_PROFILE_PATH) {
         conflicts.push(migrationConflict(
           "E_HIDDEN_KIT_MIGRATION_CONFLICT",
           entry.relativePath,
@@ -191,12 +190,12 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
         addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath, legacyHash);
         nextManifest.files[entry.relativePath] = manifestRecord(
           sourceHash,
-          entry.sourcePath === PROFILE_PATH,
+          entry.sourcePath === LEGACY_PROFILE_PATH,
           legacyHash,
         );
         continue;
       } else if (hiddenMatchesSource && legacyExists) {
-        const conflict = entry.sourcePath === PROFILE_PATH
+        const conflict = entry.sourcePath === LEGACY_PROFILE_PATH
           ? migrationConflict(
             "E_PROFILE_MIGRATION_CONFLICT",
             entry.legacyRelativePath,
@@ -214,7 +213,7 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
       }
       nextManifest.files[entry.relativePath] = manifestRecord(
         currentHash,
-        entry.sourcePath === PROFILE_PATH
+        entry.sourcePath === LEGACY_PROFILE_PATH
           || !destinationRecord
           || Boolean(destinationRecord.preserve),
       );
@@ -224,7 +223,7 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
     if (!legacyExists) {
       addAction(actions, dryRun, "create", entry.relativePath);
       writes.push({ destination, bytes: entry.bytes });
-      nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, entry.sourcePath === PROFILE_PATH);
+      nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, entry.sourcePath === LEGACY_PROFILE_PATH);
       continue;
     }
 
@@ -232,7 +231,7 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
     const legacyHash = sha256(legacyBytes);
     const unchangedManaged = Boolean(legacyRecord) && legacyHash === legacyRecord.sha256;
 
-    if (entry.sourcePath === PROFILE_PATH && legacyRecord) {
+    if (entry.sourcePath === LEGACY_PROFILE_PATH && legacyRecord) {
       addAction(actions, dryRun, "move-profile", entry.legacyRelativePath, { to: entry.relativePath });
       writes.push({ destination, bytes: legacyBytes });
       addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath, legacyHash);
@@ -256,7 +255,7 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
       continue;
     }
 
-    const conflict = entry.sourcePath === PROFILE_PATH
+    const conflict = entry.sourcePath === LEGACY_PROFILE_PATH
       ? migrationConflict(
         "E_PROFILE_MIGRATION_CONFLICT",
         entry.legacyRelativePath,
@@ -275,7 +274,7 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
       reason: legacyRecord ? "managed-modified" : "unmanaged",
     });
     writes.push({ destination, bytes: entry.bytes });
-    nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, entry.sourcePath === PROFILE_PATH);
+    nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, entry.sourcePath === LEGACY_PROFILE_PATH);
   }
 
   // Apply all hidden writes and verify their bytes before changing manifest authority.
@@ -364,7 +363,7 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion, h
         entry,
         record: {
           sha256: sourceHash,
-          preserve: entry.sourcePath === PROFILE_PATH,
+          preserve: entry.sourcePath === LEGACY_PROFILE_PATH,
           ...(record?.legacySha256 ? { legacySha256: record.legacySha256 } : {}),
         },
       });
@@ -376,7 +375,7 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion, h
       continue;
     }
 
-    if (record.preserve || entry.sourcePath === PROFILE_PATH) {
+    if (record.preserve || entry.sourcePath === LEGACY_PROFILE_PATH) {
       actions.push({ action: "skip", path: entry.relativePath, reason: "preserved" });
       continue;
     }

package/src/commands/validate-protocol.js

@@ -10,6 +10,8 @@ import { ARTIFACT_PATHS, readJsonArtifact } from "../core/artifacts.js";
 import { evaluatePreflight, validateReadyProtocolConsistency } from "../core/preflight.js";
 import { validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
 import { validateChecksExecutionProvenance } from "../core/completion-artifacts.js";
+import { assertContinuitySemantics } from "../core/continuity.js";
+import { currentChangedPaths, currentRepositoryFingerprint } from "../core/repository.js";
 
 async function readArtifact(target, relativePath, label) {
   if (!relativePath) return null;
@@ -48,6 +50,7 @@ export async function runValidateProtocol({
   stateFile = null,
   receiptFile = null,
   contractFile = null,
+  continuityFile = null,
   taskBriefFiles = [],
   delegatedResultFiles = [],
 }) {
@@ -55,6 +58,7 @@ export async function runValidateProtocol({
     ["route", routeFile],
     ["state", stateFile],
     ["receipt", receiptFile],
+    ["continuity", continuityFile],
     ...taskBriefFiles.map((file) => [`task brief:${file}`, file]),
     ...delegatedResultFiles.map((file) => [`delegated result:${file}`, file]),
   ];
@@ -68,6 +72,7 @@ export async function runValidateProtocol({
   const route = loaded.find((item) => item.label === "route")?.value ?? null;
   const state = loaded.find((item) => item.label === "state")?.value ?? null;
   const receipt = loaded.find((item) => item.label === "receipt")?.value ?? null;
+  const continuity = loaded.find((item) => item.label === "continuity")?.value ?? null;
   const taskBriefs = loaded.filter((item) => item.label.startsWith("task brief:") && item.value).map((item) => item.value);
   const delegatedResults = loaded.filter((item) => item.label.startsWith("delegated result:") && item.value).map((item) => item.value);
   const schemaErrors = [];
@@ -88,6 +93,7 @@ export async function runValidateProtocol({
   await validateLoaded(loaded.find((item) => item.label === "route"), "routing-result", async (value) => assertRouteInvariants(value));
   await validateLoaded(loaded.find((item) => item.label === "state"), "work-state", async (value) => assertWorkStateSemantics(value));
   await validateLoaded(loaded.find((item) => item.label === "receipt"), "execution-receipt", async (value) => validateReceipt(value, packageRoot));
+  await validateLoaded(loaded.find((item) => item.label === "continuity"), "continuity", async (value) => assertContinuitySemantics(value));
   for (const [value, artifactPath] of [
     [state, stateFile],
     [receipt, receiptFile],
@@ -142,11 +148,20 @@ export async function runValidateProtocol({
       })),
     ];
   }
+  const continuityContext = continuity && state && !stateValidationError
+    ? {
+      contractFingerprint: state.contractFingerprint,
+      repositoryFingerprint: await currentRepositoryFingerprint(target),
+      changedPaths: await currentChangedPaths(target),
+    }
+    : {};
   const result = validateTaskArtifactSet({
     route,
     state,
     stateClassification,
     receipt,
+    continuity,
+    continuityContext,
     taskBriefs,
     delegatedResults,
     events: ledgerEvents,
@@ -164,6 +179,10 @@ export async function runValidateProtocol({
 
 export function formatValidateProtocolResult(result) {
   const lines = [`Protocol: ${result.status}`];
+  if (result.continuity) {
+    lines.push(`Continuity: ${result.continuity.status}`);
+    lines.push(`Continuity authority: ${result.continuity.authority}`);
+  }
   if (result.stale) {
     lines.push(`Repository: ${result.stale.repositoryComparison}`);
     lines.push(`Contract: ${result.stale.contractComparison}`);

package/src/core/artifacts.js

@@ -16,6 +16,7 @@ export const ARTIFACT_PATHS = Object.freeze({
   config: ".forgeloop/config.json",
   gates: ".forgeloop/gates",
   state: ".forgeloop/work-state.json",
+  continuity: ".forgeloop/continuity.json",
   receipt: ".forgeloop/execution-receipt.json",
   executionDirectory: ".forgeloop/executions",
 });

package/src/core/bundles.js

@@ -6,6 +6,7 @@ import { assertSafePath, ensureWithin, fileExists, readBytes, writeFileAtomic }
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { validateChecksExecutionProvenance } from "./completion-artifacts.js";
 import { readExecutionArtifact } from "./execution.js";
+import { assertContinuitySemantics } from "./continuity.js";
 
 export const BUNDLE_SCHEMA_VERSION = 1;
 const BUNDLE_ROOT = ".forgeloop/tasks";
@@ -89,6 +90,7 @@ export async function exportTaskBundle(target, taskId, packageRoot) {
     [ARTIFACT_PATHS.receipt, "receipt.json", "execution-receipt"],
     [ARTIFACT_PATHS.sources, "sources.json", "source-registry"],
     [ARTIFACT_PATHS.config, "config.json", "config"],
+    [ARTIFACT_PATHS.continuity, "continuity.json", "continuity"],
   ];
   for (const [sourcePath, destinationName, schemaName] of optional) {
     const copied = await copyJson(target, sourcePath, `${directory}/${destinationName}`, schemaName, packageRoot, artifacts, destinationName);
@@ -146,6 +148,7 @@ export async function readTaskBundle(target, taskId, packageRoot) {
     "receipt.json": ["receipt", "execution-receipt"],
     "sources.json": ["sources", "source-registry"],
     "config.json": ["config", "config"],
+    "continuity.json": ["continuity", "continuity"],
   };
   const executions = {};
   for (const artifact of manifest.value.artifacts) {
@@ -160,6 +163,9 @@ export async function readTaskBundle(target, taskId, packageRoot) {
     if (mapping[1] === "current-contract") {
       await validateContract(loadedArtifact.value, packageRoot);
     }
+    if (mapping[1] === "continuity") {
+      assertContinuitySemantics(loadedArtifact.value);
+    }
     loaded[mapping[0]] = loadedArtifact.value;
   }
   if (Object.keys(executions).length > 0) loaded.executions = executions;

package/src/core/command-resolution.js

@@ -0,0 +1,295 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  extractToolFromArgs,
+  normalizeExecutableName,
+  splitCommandPipeline,
+  tokenizeCommand,
+} from "./command-tokenizer.js";
+import {
+  classifyNpmInvocation,
+  getNpmLifecycleCandidates,
+  getNpmScriptName,
+  parseNpmInvocation,
+  parseNpmInvocationArgs,
+} from "./npm-classifier.js";
+import {
+  classifyPnpmInvocation,
+  classifyYarnInvocation,
+} from "./package-manager-classifiers.js";
+
+function classifySingleCommand(commandInput) {
+  const tokens = Array.isArray(commandInput) ? [...commandInput] : tokenizeCommand(commandInput);
+  if (tokens.length === 0) return { resolutionMode: "UNKNOWN", mayInstall: false, installer: null, tool: null };
+
+  let i = 0;
+  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
+  if (i >= tokens.length) return { resolutionMode: "UNKNOWN", mayInstall: false, installer: null, tool: null };
+
+  const binaryToken = tokens[i];
+  const binary = normalizeExecutableName(binaryToken);
+  const rest = tokens.slice(i + 1);
+
+  if (binary === "call") return classifyCommandResolution(rest);
+
+  if (binaryToken.includes("node_modules/.bin/") || binaryToken.startsWith("./node_modules/")) {
+    return { resolutionMode: "LOCAL_PACKAGE_BINARY", mayInstall: false, installer: null, tool: binary };
+  }
+
+  if (binary === "npx") {
+    if (rest.some((arg) => arg === "--no-install" || arg === "--no")) {
+      const nonInstallArgs = rest.filter((arg) => arg !== "--no-install" && arg !== "--no");
+      return {
+        resolutionMode: "NON_INSTALLING_RESOLUTION",
+        mayInstall: false,
+        installer: "npx",
+        tool: extractToolFromArgs(nonInstallArgs),
+      };
+    }
+    return {
+      resolutionMode: "INSTALL_CAPABLE_RESOLUTION",
+      mayInstall: true,
+      installer: "npx",
+      tool: extractToolFromArgs(rest),
+    };
+  }
+
+  if (binary === "pnpx" || binary === "bunx" || binary === "uvx") {
+    return {
+      resolutionMode: "INSTALL_CAPABLE_RESOLUTION",
+      mayInstall: true,
+      installer: binary,
+      tool: extractToolFromArgs(rest),
+    };
+  }
+
+  if (binary === "pnpm") return classifyPnpmInvocation(rest);
+  if (binary === "yarn") return classifyYarnInvocation(rest);
+
+  if (binary === "bun") {
+    if (rest[0] === "x") {
+      return {
+        resolutionMode: "INSTALL_CAPABLE_RESOLUTION",
+        mayInstall: true,
+        installer: "bun x",
+        tool: extractToolFromArgs(rest.slice(1)),
+      };
+    }
+    if (["add", "install", "i"].includes(rest[0])) {
+      return {
+        resolutionMode: "EXPLICIT_INSTALLATION",
+        mayInstall: true,
+        installer: "bun",
+        tool: extractToolFromArgs(rest.slice(1)),
+      };
+    }
+    return { resolutionMode: "LOCAL_PACKAGE_BINARY", mayInstall: false, installer: null, tool: null };
+  }
+
+  if (binary === "uv") {
+    if (rest[0] === "tool" && rest[1] === "run") {
+      return {
+        resolutionMode: "INSTALL_CAPABLE_RESOLUTION",
+        mayInstall: true,
+        installer: "uv tool run",
+        tool: extractToolFromArgs(rest.slice(2)),
+      };
+    }
+    if (rest[0] === "pip" && rest[1] === "install") {
+      return {
+        resolutionMode: "EXPLICIT_INSTALLATION",
+        mayInstall: true,
+        installer: "uv pip install",
+        tool: extractToolFromArgs(rest.slice(2)),
+      };
+    }
+    if (rest[0] === "add") {
+      return {
+        resolutionMode: "EXPLICIT_INSTALLATION",
+        mayInstall: true,
+        installer: "uv add",
+        tool: extractToolFromArgs(rest.slice(1)),
+      };
+    }
+    return { resolutionMode: "LOCAL_EXECUTABLE", mayInstall: false, installer: null, tool: null };
+  }
+
+  if (binary === "pipx") {
+    if (rest[0] === "run") {
+      return {
+        resolutionMode: "INSTALL_CAPABLE_RESOLUTION",
+        mayInstall: true,
+        installer: "pipx run",
+        tool: extractToolFromArgs(rest.slice(1)),
+      };
+    }
+    if (rest[0] === "install") {
+      return {
+        resolutionMode: "EXPLICIT_INSTALLATION",
+        mayInstall: true,
+        installer: "pipx install",
+        tool: extractToolFromArgs(rest.slice(1)),
+      };
+    }
+    return { resolutionMode: "LOCAL_EXECUTABLE", mayInstall: false, installer: null, tool: null };
+  }
+
+  if (binary === "npm") return classifyNpmInvocation(parseNpmInvocationArgs(rest));
+
+  if (binary === "pip" || binary === "pip3") {
+    if (rest[0] === "install") {
+      return {
+        resolutionMode: "EXPLICIT_INSTALLATION",
+        mayInstall: true,
+        installer: binary,
+        tool: extractToolFromArgs(rest.slice(1)),
+      };
+    }
+  }
+  if (binary === "python" || binary === "python3") {
+    if (rest[0] === "-m" && rest[1] === "pip" && rest[2] === "install") {
+      return {
+        resolutionMode: "EXPLICIT_INSTALLATION",
+        mayInstall: true,
+        installer: `${binary} -m pip install`,
+        tool: extractToolFromArgs(rest.slice(3)),
+      };
+    }
+  }
+
+  if (binary === "cargo") {
+    if (rest[0] === "install" || rest[0] === "binstall") {
+      return {
+        resolutionMode: "EXPLICIT_INSTALLATION",
+        mayInstall: true,
+        installer: binary,
+        tool: extractToolFromArgs(rest.slice(1)),
+      };
+    }
+  }
+
+  if (["brew", "apt", "apt-get", "apk", "dnf", "pacman"].includes(binary)) {
+    if (["install", "add", "-S"].includes(rest[0])) {
+      return {
+        resolutionMode: "EXPLICIT_INSTALLATION",
+        mayInstall: true,
+        installer: binary,
+        tool: extractToolFromArgs(rest.slice(1)),
+      };
+    }
+  }
+
+  return { resolutionMode: "LOCAL_EXECUTABLE", mayInstall: false, installer: null, tool: null };
+}
+
+export function classifyCommandResolution(commandInput) {
+  if (Array.isArray(commandInput)) {
+    if (commandInput.length === 0 || commandInput.some((item) => typeof item !== "string" || item.trim() === "")) {
+      return { resolutionMode: "UNKNOWN", mayInstall: false, installer: null, tool: null };
+    }
+    const binary = normalizeExecutableName(commandInput[0]);
+    if (["sh", "bash", "zsh", "dash", "ksh"].includes(binary)) {
+      const shellFlagIndex = commandInput.findIndex((item, index) => index > 0 && /^-.*c/.test(item));
+      const shellCommand = shellFlagIndex >= 0 ? commandInput[shellFlagIndex + 1] : null;
+      if (shellCommand) return classifyCommandResolution(shellCommand);
+    }
+    if (binary === "cmd") {
+      const shellFlagIndex = commandInput.findIndex((item, index) => index > 0 && /^\/c$/iu.test(item));
+      const shellCommand = shellFlagIndex >= 0 ? commandInput.slice(shellFlagIndex + 1).join(" ") : null;
+      if (shellCommand) return classifyCommandResolution(shellCommand);
+    }
+    return classifySingleCommand(commandInput);
+  }
+
+  if (typeof commandInput !== "string" || commandInput.trim() === "") {
+    return { resolutionMode: "UNKNOWN", mayInstall: false, installer: null, tool: null };
+  }
+
+  const subcommands = splitCommandPipeline(commandInput);
+  for (const subcommand of subcommands) {
+    const result = classifySingleCommand(subcommand);
+    if (result.mayInstall) return result;
+  }
+  return classifySingleCommand(subcommands[0] || commandInput);
+}
+
+export const MAX_NPM_SCRIPT_DEPTH = 16;
+
+async function resolveNpmScriptRisk({ scriptName, packageJson, visited = new Set(), depth = 0 } = {}) {
+  if (depth > MAX_NPM_SCRIPT_DEPTH) {
+    return { resolutionMode: "UNKNOWN", mayInstall: true, installer: "npm-script", tool: null, reason: "MAX_SCRIPT_DEPTH" };
+  }
+  if (visited.has(scriptName)) {
+    return { resolutionMode: "UNKNOWN", mayInstall: true, installer: "npm-script", tool: null, reason: "SCRIPT_CYCLE" };
+  }
+
+  const nextVisited = new Set(visited);
+  nextVisited.add(scriptName);
+  const candidates = getNpmLifecycleCandidates({ scriptName, scripts: packageJson?.scripts ?? {} });
+  for (const candidate of candidates) {
+    const scriptBody = packageJson?.scripts?.[candidate];
+    if (typeof scriptBody !== "string" || scriptBody.trim() === "") continue;
+
+    const direct = classifyCommandResolution(scriptBody);
+    if (direct.mayInstall) {
+      return {
+        resolutionMode: direct.resolutionMode,
+        mayInstall: true,
+        installer: direct.installer ?? "npm-script",
+        tool: direct.tool,
+        dispatch: { kind: "npm-script", scriptName: candidate },
+      };
+    }
+
+    for (const subcommand of splitCommandPipeline(scriptBody)) {
+      const nestedScriptName = getNpmScriptName(subcommand);
+      if (!nestedScriptName) continue;
+      const nested = await resolveNpmScriptRisk({
+        scriptName: nestedScriptName,
+        packageJson,
+        visited: nextVisited,
+        depth: depth + 1,
+      });
+      if (nested?.mayInstall) return nested;
+    }
+  }
+  return null;
+}
+
+async function readPackageJsonIfPresent(cwd) {
+  if (!cwd || typeof cwd !== "string") return null;
+  try {
+    const raw = await fs.readFile(path.resolve(cwd, "package.json"), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function resolveExecutionResolution({ argv, cwd } = {}) {
+  const direct = classifyCommandResolution(argv);
+  if (direct.mayInstall && direct.resolutionMode !== "UNKNOWN") return direct;
+
+  const npmInvocation = parseNpmInvocation(argv);
+  const scriptName = getNpmScriptName(argv);
+  if (scriptName && (npmInvocation.workspace || npmInvocation.workspaces)) {
+    return {
+      resolutionMode: "UNKNOWN",
+      mayInstall: true,
+      installer: "npm-workspace",
+      tool: null,
+      reason: "NPM_WORKSPACE_SCRIPT_UNRESOLVED",
+      dispatch: { kind: "npm-workspace-script", scriptName },
+    };
+  }
+
+  if (direct.mayInstall) return direct;
+  if (!scriptName) return direct;
+
+  const packageJson = await readPackageJsonIfPresent(cwd);
+  if (!packageJson || typeof packageJson.scripts !== "object" || packageJson.scripts === null) return direct;
+
+  const nestedRisk = await resolveNpmScriptRisk({ scriptName, packageJson });
+  return nestedRisk?.mayInstall ? nestedRisk : direct;
+}