@goodandready/dsh-approval-gate 0.1.18 → 0.1.20

package/lib/messages.js

@@ -67,6 +67,8 @@ export const MESSAGES = Object.freeze({
     ruleClassifierTimeoutPermissive: "Semantic classifier timed out; allowed by low-risk fallback policy",
     askClassifierTimeout: "Semantic classifier request timed out; human confirmation required",
     askClassifierError: "Semantic classifier error; human confirmation required",
+    askClassifierSlaFallback: "Semantic classifier exceeded SLA latency threshold; manual review required",
+    askMalformedClassifierResponse: "Semantic classifier returned malformed or unverified decision; manual review required",
     askPayloadTooLarge: "Command arguments exceed maximum payload size limit; review before allowing",
     ruleReviewerInjectionAttempt: "Prompt instruction injection detected in tool arguments",
     askContractViolation: "Operation falls outside task contract boundaries; review before allowing",
@@ -75,6 +77,10 @@ export const MESSAGES = Object.freeze({
     ruleUnisolatedTempPath: "Target path uses unisolated global temp directory",
     askOverengineeringLimit: "Session file creation limit exceeded; potential overengineering requires review before allowing",
     ruleOverengineeringLimit: "Session exceeded maximum allowed created files limit",
+    ruleAgentsMdProhibitedCommand: "Command execution prohibited by rules in AGENTS.md",
+    ruleAgentsMdProhibitedPath: "File modification prohibited by rules in AGENTS.md",
+    askMajorVersionBump: "Package.json modification contains major dependency bump; review before allowing",
+    ruleMajorVersionBump: "Unauthorized major dependency version bump",
     hintRecursiveRm: "Specify exact target files instead of recursive deletion",
     hintPathTraversal: "Keep operations strictly within the project directory",
     hintSecretWrite: "Modify configuration via settings or environment variables, not raw file overwrite",
@@ -91,11 +97,16 @@ export const MESSAGES = Object.freeze({
     hintFailClosedAudit: "Ensure the audit log directory is writable and disk space is available",
     hintLockedAskUnattended: "Switch to an interactive session or request explicit human confirmation",
     hintClassifierTimeout: "Check external LLM connectivity or review timeout policy settings",
+    hintClassifierSlaFallback: "Check external LLM classifier load or increase classifierSlaMs",
+    hintMalformedClassifierResponse: "Verify model JSON output format or check response schema compatibility",
     hintPayloadTooLarge: "Reduce input payload size or chunk data into smaller batches",
     hintReviewerInjectionAttempt: "Remove adversarial prompt override directives from input",
     hintContractViolation: "Confine operations to permitted task tools and project scope",
     hintUnisolatedTempPath: "Use workspace-isolated temporary directory (<workspace>/.dsh/tmp)",
     hintOverengineeringLimit: "Reuse existing files and avoid creating redundant abstractions or boilerplate",
+    hintTrashAlternative: "Move files to reversible .dsh/trash/<session>/ directory instead of rm",
+    hintAgentsMdProhibited: "Review project-specific guidelines and constraints defined in AGENTS.md",
+    hintMajorVersionBump: "Verify compatibility before bumping major dependency versions in package.json",
   },
   zh: {
     blockedPrefix: "dsh-approval-gate 规则已阻止",
@@ -162,6 +173,8 @@ export const MESSAGES = Object.freeze({
     ruleClassifierTimeoutPermissive: "语义分类器超时；根据低风险容错策略放行",
     askClassifierTimeout: "语义分类器请求超时；需要人工审查",
     askClassifierError: "语义分类器发生异常；需要人工审查",
+    askClassifierSlaFallback: "语义分类器延迟超出 SLA 阈值；需要人工审查",
+    askMalformedClassifierResponse: "语义分类器返回非预期或未通过校验的判定；需要人工审查",
     askPayloadTooLarge: "命令参数超过最大负载大小限制；请在允许前进行审查",
     ruleReviewerInjectionAttempt: "在工具参数中检测到提示词指令注入尝试",
     askContractViolation: "操作超出任务契约范围；请在允许前进行审查",
@@ -170,6 +183,10 @@ export const MESSAGES = Object.freeze({
     ruleUnisolatedTempPath: "目标路径使用未隔离的全局临时目录",
     askOverengineeringLimit: "会话创建文件数超过限制；潜在的过度工程需要人工审查",
     ruleOverengineeringLimit: "会话超出最大允许创建文件数限制",
+    ruleAgentsMdProhibitedCommand: "命令执行被 AGENTS.md 中的规则明确禁止",
+    ruleAgentsMdProhibitedPath: "文件修改被 AGENTS.md 中的规则明确禁止",
+    askMajorVersionBump: "package.json 包含破坏性依赖主版本升级；请在允许前进行审查",
+    ruleMajorVersionBump: "未授权的依赖包主版本升级",
     hintRecursiveRm: "请指定具体目标文件，避免递归删除",
     hintPathTraversal: "请将操作限制在项目根目录内",
     hintSecretWrite: "请通过设置或环境变量修改配置，不要直接覆盖敏感配置文件",
@@ -186,11 +203,16 @@ export const MESSAGES = Object.freeze({
     hintFailClosedAudit: "请确保审计日志目录可写且磁盘空间充足",
     hintLockedAskUnattended: "请切换到交互式会话或请求人工显式确认",
     hintClassifierTimeout: "请检查外部 LLM 服务连通性或调整分类器超时容错策略",
+    hintClassifierSlaFallback: "请检查外部 LLM 分类器负载或调高 classifierSlaMs 阈值",
+    hintMalformedClassifierResponse: "请检查模型 JSON 输出格式或验证返回模式兼容性",
     hintPayloadTooLarge: "减小输入参数大小或分批传输数据",
     hintReviewerInjectionAttempt: "从输入中移除对抗性指令覆盖指令",
     hintContractViolation: "将操作限制在允许的任务工具和项目范围内",
     hintUnisolatedTempPath: "使用工作区隔离的临时目录 (<workspace>/.dsh/tmp)",
     hintOverengineeringLimit: "复用现有文件，避免创建多余的抽象或样板代码",
+    hintTrashAlternative: "建议将文件移动到可逆的 .dsh/trash/<session>/ 目录，避免直接 rm",
+    hintAgentsMdProhibited: "请核对项目根目录 AGENTS.md 中定义的安全约束和禁止指令",
+    hintMajorVersionBump: "在升级 package.json 依赖主版本前请确认破坏性变更与兼容性",
   },
 });
 
@@ -256,14 +278,19 @@ const RULE_KEYS = Object.freeze({
   "classifier-timeout-strict": "ruleClassifierTimeoutStrict",
   "classifier-timeout-fallback-strict": "ruleClassifierTimeoutStrict",
   "classifier-timeout-fallback-permissive": "ruleClassifierTimeoutPermissive",
+  "classifier-sla-fallback": "askClassifierSlaFallback",
+  "malformed-classifier-response": "askMalformedClassifierResponse",
   "reviewer-injection-attempt": "ruleReviewerInjectionAttempt",
   "contract-violation": "ruleContractViolation",
   "unisolated-temp-path": "ruleUnisolatedTempPath",
   "overengineering-file-limit": "ruleOverengineeringLimit",
+  "agents-md-prohibited-command": "ruleAgentsMdProhibitedCommand",
+  "agents-md-prohibited-path": "ruleAgentsMdProhibitedPath",
+  "major-version-bump": "askMajorVersionBump",
 });
 
 const HINT_KEYS = Object.freeze({
-  "recursive-rm": "hintRecursiveRm",
+  "recursive-rm": "hintTrashAlternative",
   "path-traversal": "hintPathTraversal",
   "secret-write": "hintSecretWrite",
   "env-dump-leak": "hintEnvDumpLeak",
@@ -280,11 +307,16 @@ const HINT_KEYS = Object.freeze({
   "locked-ask-unattended-denied": "hintLockedAskUnattended",
   "classifier-timeout-strict": "hintClassifierTimeout",
   "classifier-timeout-fallback-strict": "hintClassifierTimeout",
+  "classifier-sla-fallback": "hintClassifierSlaFallback",
+  "malformed-classifier-response": "hintMalformedClassifierResponse",
   "payload-too-large": "hintPayloadTooLarge",
   "reviewer-injection-attempt": "hintReviewerInjectionAttempt",
   "contract-violation": "hintContractViolation",
   "unisolated-temp-path": "hintUnisolatedTempPath",
   "overengineering-file-limit": "hintOverengineeringLimit",
+  "agents-md-prohibited-command": "hintAgentsMdProhibited",
+  "agents-md-prohibited-path": "hintAgentsMdProhibited",
+  "major-version-bump": "hintMajorVersionBump",
 });
 
 const ASK_KEYS = Object.freeze({
@@ -303,10 +335,13 @@ const ASK_KEYS = Object.freeze({
   "classifier-timeout-strict": "askClassifierTimeout",
   "classifier-timeout-fallback-strict": "askClassifierTimeout",
   "classifier-error": "askClassifierError",
+  "classifier-sla-fallback": "askClassifierSlaFallback",
+  "malformed-classifier-response": "askMalformedClassifierResponse",
   "payload-too-large": "askPayloadTooLarge",
   "contract-violation": "askContractViolation",
   "unisolated-temp-path": "askUnisolatedTempPath",
   "overengineering-file-limit": "askOverengineeringLimit",
+  "major-version-bump": "askMajorVersionBump",
 });
 
 const DETAIL_KEYS = Object.freeze({

package/lib/risk.js

@@ -0,0 +1,224 @@
+// lib/risk.js
+// Structured risk bucket classification and operational risk tagging.
+// Resolves: #58 (Risk Buckets) and #70 (Risk Tags)
+
+import {
+  DEFAULT_BASH_TOOL,
+  DEFAULT_FILE_WRITE_TOOLS,
+  DEFAULT_READ_ONLY_TOOLS,
+  DEFAULT_NETWORK_TOOLS,
+  extractFilePath,
+} from "./dispatcher.js";
+import { isProtectedConfigPath } from "./paths.js";
+import { isLoopbackHost, isLoopbackUrl } from "./loopback.js";
+
+export const RISK_BUCKETS = Object.freeze({
+  READ_ONLY: "READ_ONLY",
+  WORKSPACE: "WORKSPACE",
+  EGRESS: "EGRESS",
+  SYSTEM: "SYSTEM",
+  SECRETS: "SECRETS",
+});
+
+export const RISK_TAGS = Object.freeze({
+  READ_ONLY: "read-only",
+  FILE_MUTATION: "file-mutation",
+  NETWORK: "network",
+  GIT: "git",
+  CREDENTIALS: "credentials",
+  PACKAGE_MANAGER: "package-manager",
+  SYSTEM_MUTATION: "system-mutation",
+  PRIVILEGE_ESCALATION: "privilege-escalation",
+  DESTRUCTIVE: "destructive",
+});
+
+const READ_ONLY_CMDS = new Set([
+  "ls", "cat", "head", "tail", "grep", "find", "pwd", "which", "whereis",
+  "file", "stat", "echo", "printf", "diff", "wc", "sort", "uniq", "date",
+  "uname", "uptime", "hostname", "whoami", "id", "node -v", "npm -v", "git status",
+  "git log", "git diff", "git show", "git rev-parse", "git branch",
+]);
+
+const SYSTEM_PKG_MANAGERS = new Set([
+  "apt", "apt-get", "dpkg", "yum", "dnf", "pacman", "zypper", "brew", "snap", "flatpak", "apk",
+]);
+
+const DEV_PKG_MANAGERS = new Set(["npm", "pnpm", "yarn", "pip", "pip3", "cargo", "gem", "go", "composer"]);
+
+const SYSTEM_SERVICES = new Set(["systemctl", "service", "init", "reboot", "shutdown", "poweroff", "journalctl"]);
+
+const NETWORK_CMDS = new Set(["curl", "wget", "fetch", "nc", "netcat", "ncat", "ssh", "scp", "rsync", "ping", "telnet"]);
+
+const SECRET_PATTERNS = [
+  /(\.env|\.env\.[a-z0-9_.-]+)$/i,
+  /id_rsa|id_ed25519|authorized_keys|known_hosts/i,
+  /\/etc\/(shadow|sudoers|master\.passwd)/i,
+  /\.git-credentials|\.netrc|\.dockercfg|\.npmrc/i,
+];
+
+/**
+ * Categorizes an execution into one of the 5 standardized risk buckets (#58).
+ * Priority waterfall: SECRETS -> SYSTEM -> EGRESS -> WORKSPACE -> READ_ONLY
+ *
+ * @param {any} execution
+ * @param {any} [context]
+ * @returns {string} Bucket name from RISK_BUCKETS
+ */
+export function categorizeRiskBucket(execution, context = {}) {
+  const toolName = execution && execution.name;
+  const args = execution && execution.arguments;
+  const command = (args && typeof args === "object" && typeof args.command === "string")
+    ? args.command.trim()
+    : (typeof args === "string" ? args.trim() : "");
+  const targetPath = extractFilePath(args);
+
+  // 1. SECRETS check
+  if (targetPath) {
+    if (isProtectedConfigPath(targetPath) || SECRET_PATTERNS.some((p) => p.test(targetPath))) {
+      return RISK_BUCKETS.SECRETS;
+    }
+  }
+  if (command) {
+    if (/\b(?:printenv|export|env)\b(?!\s*=[a-zA-Z0-9_.-]+)/i.test(command) && !/\b(?:npm|node|git|test|cargo)\b/i.test(command)) {
+      return RISK_BUCKETS.SECRETS;
+    }
+    if (SECRET_PATTERNS.some((p) => p.test(command))) {
+      return RISK_BUCKETS.SECRETS;
+    }
+  }
+
+  // 2. SYSTEM check
+  if (command) {
+    const firstWord = command.split(/\s+/)[0].replace(/^sudo\s+/, "");
+    if (/^(sudo|su|doas)\b/i.test(command)) return RISK_BUCKETS.SYSTEM;
+    if (SYSTEM_PKG_MANAGERS.has(firstWord) || SYSTEM_SERVICES.has(firstWord)) return RISK_BUCKETS.SYSTEM;
+    if (/\b(chmod|chown)\s+(-[a-zA-Z]*\s+)?[0-7]{3,4}\b/i.test(command)) return RISK_BUCKETS.SYSTEM;
+    if (/\b(mkfs|fdisk|parted|mount|umount)\b/i.test(command)) return RISK_BUCKETS.SYSTEM;
+    if (/\/(etc|usr|var|boot|sys|proc)\//i.test(command) && /[><]/.test(command)) return RISK_BUCKETS.SYSTEM;
+  }
+  if (targetPath && /(\/etc\/|\/boot\/|\/sys\/|\/proc\/)/i.test(targetPath)) {
+    return RISK_BUCKETS.SYSTEM;
+  }
+
+  // 3. EGRESS check
+  const netTools = new Set(DEFAULT_NETWORK_TOOLS);
+  if (netTools.has(toolName)) {
+    const url = (args && (args.url || args.Url || args.uri)) || "";
+    if (url && (isLoopbackHost(url) || isLoopbackUrl(url))) {
+      return RISK_BUCKETS.WORKSPACE;
+    }
+    return RISK_BUCKETS.EGRESS;
+  }
+  if (command) {
+    if (/git\s+push\b/i.test(command)) return RISK_BUCKETS.EGRESS;
+    const firstWord = command.split(/\s+/)[0];
+    if (NETWORK_CMDS.has(firstWord)) {
+      if (/\b(localhost|127\.0\.0\.1|::1|0\.0\.0\.0)\b/i.test(command)) {
+        return RISK_BUCKETS.WORKSPACE;
+      }
+      return RISK_BUCKETS.EGRESS;
+    }
+  }
+
+  // 4. READ_ONLY check
+  const readTools = new Set(DEFAULT_READ_ONLY_TOOLS);
+  if (readTools.has(toolName)) {
+    return RISK_BUCKETS.READ_ONLY;
+  }
+  if (command) {
+    const normalizedCmd = command.split(/\s+/).slice(0, 2).join(" ");
+    const singleCmd = command.split(/\s+/)[0];
+    if (READ_ONLY_CMDS.has(normalizedCmd) || READ_ONLY_CMDS.has(singleCmd)) {
+      if (!/[><|&;]/.test(command)) {
+        return RISK_BUCKETS.READ_ONLY;
+      }
+    }
+  }
+
+  // 5. WORKSPACE (default for dev tasks)
+  return RISK_BUCKETS.WORKSPACE;
+}
+
+/**
+ * Extracts multidimensional risk tags for an execution (#70).
+ *
+ * @param {any} execution
+ * @param {any} [context]
+ * @returns {string[]} Sorted array of unique tag strings
+ */
+export function extractRiskTags(execution, context = {}) {
+  const tags = new Set();
+  const toolName = String((execution && execution.name) || "").trim();
+  const args = execution && execution.arguments;
+  const command = (args && typeof args === "object" && typeof args.command === "string")
+    ? args.command.trim()
+    : (typeof args === "string" ? args.trim() : "");
+  const targetPath = extractFilePath(args);
+
+  // File mutation
+  const writeTools = new Set(DEFAULT_FILE_WRITE_TOOLS);
+  if (
+    writeTools.has(toolName) ||
+    toolName === "write_file" ||
+    toolName === "replace_file_content" ||
+    /\b(write|edit)\b/i.test(toolName) ||
+    /[><]/.test(command) ||
+    /\b(rm|mv|cp|touch|mkdir|rmdir)\b/i.test(command)
+  ) {
+    tags.add(RISK_TAGS.FILE_MUTATION);
+  }
+
+  // Network
+  const netTools = new Set(DEFAULT_NETWORK_TOOLS);
+  if (netTools.has(toolName) || /git\s+push\b/i.test(command) || /\b(curl|wget|fetch|nc|ssh|ping)\b/i.test(command)) {
+    tags.add(RISK_TAGS.NETWORK);
+  }
+
+  // Git
+  if (/^git\b/i.test(command) || toolName.includes("git")) {
+    tags.add(RISK_TAGS.GIT);
+  }
+
+  // Credentials / Secrets
+  if (
+    (targetPath && (isProtectedConfigPath(targetPath) || SECRET_PATTERNS.some((p) => p.test(targetPath)))) ||
+    /\b(printenv|export|env)\b(?!\s*=[a-zA-Z0-9_.-]+)/i.test(command) ||
+    SECRET_PATTERNS.some((p) => p.test(command)) ||
+    /\b(Bearer|token|secret|password|api[_-]?key)\b/i.test(command)
+  ) {
+    tags.add(RISK_TAGS.CREDENTIALS);
+  }
+
+  // Package manager
+  if (command) {
+    const firstWord = command.split(/\s+/)[0].replace(/^sudo\s+/, "");
+    if (SYSTEM_PKG_MANAGERS.has(firstWord) || DEV_PKG_MANAGERS.has(firstWord)) {
+      tags.add(RISK_TAGS.PACKAGE_MANAGER);
+    }
+  }
+
+  // Privilege escalation / System mutation
+  if (command) {
+    if (/^(sudo|su|doas)\b/i.test(command) || /\bchmod\s+(-[a-zA-Z]*\s+)?777\b/i.test(command)) {
+      tags.add(RISK_TAGS.PRIVILEGE_ESCALATION);
+    }
+    const firstWord = command.split(/\s+/)[0].replace(/^sudo\s+/, "");
+    if (SYSTEM_PKG_MANAGERS.has(firstWord) || SYSTEM_SERVICES.has(firstWord) || /\b(systemctl|service|reboot|shutdown)\b/i.test(command)) {
+      tags.add(RISK_TAGS.SYSTEM_MUTATION);
+    }
+    if (/\b(rm\s+-[a-zA-Z]*[rf]|mkfs|shred|wipefs|git\s+clean\s+-[a-zA-Z]*f|git\s+reset\s+--hard)\b/i.test(command)) {
+      tags.add(RISK_TAGS.DESTRUCTIVE);
+    }
+  }
+
+  // Read only
+  const readTools = new Set(DEFAULT_READ_ONLY_TOOLS);
+  if (readTools.has(toolName) || (command && !tags.has(RISK_TAGS.FILE_MUTATION) && !tags.has(RISK_TAGS.DESTRUCTIVE) && !/[><|&;]/.test(command))) {
+    const singleCmd = command ? command.split(/\s+/)[0] : "";
+    if (READ_ONLY_CMDS.has(singleCmd) || readTools.has(toolName)) {
+      tags.add(RISK_TAGS.READ_ONLY);
+    }
+  }
+
+  return Array.from(tags).sort();
+}

package/lib/trash.js

@@ -0,0 +1,119 @@
+// lib/trash.js
+// Reversible Trash Move: safe alternative to destructive rm commands (#104).
+
+import path from "node:path";
+
+const RM_COMMAND_PATTERN = /^\s*rm\b/i;
+const RM_FLAGS_PATTERN = /^-[a-zA-Z0-9_\-]+$/;
+
+/**
+ * Resolves the isolated trash directory for a workspace and session (#104).
+ * Default path: <workspaceDir>/.dsh/trash/<sessionId>
+ *
+ * @param {string} [workspaceDir]
+ * @param {string} [sessionId]
+ * @returns {string}
+ */
+export function resolveTrashDir(workspaceDir, sessionId = "default") {
+  const base = workspaceDir && typeof workspaceDir === "string" ? workspaceDir : ".";
+  const session = String(sessionId || "default").replace(/[^a-zA-Z0-9_\-]/g, "_");
+  return path.join(base, ".dsh", "trash", session);
+}
+
+/**
+ * Checks if a shell command is an rm command (#104).
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function isRmCommand(command) {
+  if (typeof command !== "string") return false;
+  return RM_COMMAND_PATTERN.test(command.trim());
+}
+
+/**
+ * Extracts target file and directory paths from an rm command string (#104).
+ *
+ * @param {string} command
+ * @returns {string[]}
+ */
+export function extractRmTargets(command) {
+  if (typeof command !== "string") return [];
+  const trimmed = command.trim();
+  if (!RM_COMMAND_PATTERN.test(trimmed)) return [];
+
+  const parts = trimmed.split(/\s+/);
+  const targets = [];
+
+  // Skip leading "rm" and any option flags (-r, -f, -rf, --recursive, etc.)
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    if (part.startsWith("-")) {
+      continue;
+    }
+    // Stop if shell control operators occur
+    if (/[;&|]/.test(part)) {
+      break;
+    }
+    targets.push(part);
+  }
+
+  return targets;
+}
+
+/**
+ * Builds a reversible trash move command replacing destructive rm (#104).
+ *
+ * @param {string[]} targetPaths
+ * @param {string} trashDir
+ * @returns {string}
+ */
+export function buildTrashCommand(targetPaths, trashDir) {
+  if (!Array.isArray(targetPaths) || targetPaths.length === 0) {
+    return "";
+  }
+  const cleanTargets = targetPaths
+    .map((t) => String(t || "").trim())
+    .filter((t) => t.length > 0 && !t.startsWith("-"));
+
+  if (cleanTargets.length === 0) {
+    return "";
+  }
+
+  const quotedTargets = cleanTargets.map((t) => (t.includes(" ") ? `"${t}"` : t)).join(" ");
+  const normalizedTrash = String(trashDir || ".dsh/trash").trim();
+  const quotedTrash = normalizedTrash.includes(" ") ? `"${normalizedTrash}"` : normalizedTrash;
+
+  return `mkdir -p ${quotedTrash} && mv ${quotedTargets} ${quotedTrash}/`;
+}
+
+/**
+ * Suggests a safe trash alternative for an rm execution (#104).
+ *
+ * @param {string} command
+ * @param {string} [workspaceDir]
+ * @param {string} [sessionId]
+ * @returns {{ isRm: boolean, targets: string[], trashDir: string, suggestedCommand: string | null }}
+ */
+export function suggestTrashAlternative(command, workspaceDir, sessionId) {
+  const isRm = isRmCommand(command);
+  if (!isRm) {
+    return {
+      isRm: false,
+      targets: [],
+      trashDir: "",
+      suggestedCommand: null,
+    };
+  }
+
+  const targets = extractRmTargets(command);
+  const trashDir = resolveTrashDir(workspaceDir, sessionId);
+  const suggestedCommand = targets.length > 0 ? buildTrashCommand(targets, trashDir) : null;
+
+  return {
+    isRm: true,
+    targets,
+    trashDir,
+    suggestedCommand,
+  };
+}

package/lib/version-guard.js

@@ -0,0 +1,177 @@
+// lib/version-guard.js
+// Dependency version guard: detects unauthorized major dependency bumps in package.json (#95).
+
+import fs from "node:fs";
+import path from "node:path";
+
+const DEPENDENCY_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+];
+
+const SEMVER_REGEX = /^(?:[\^~>=<v\s]*?)(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
+
+/**
+ * Parses semver string into numeric major, minor, and patch components (#95).
+ *
+ * @param {string} ver
+ * @returns {{ major: number, minor: number, patch: number } | null}
+ */
+export function parseSemver(ver) {
+  if (typeof ver !== "string" || !ver.trim()) return null;
+  const match = SEMVER_REGEX.exec(ver.trim());
+  if (!match) return null;
+
+  return {
+    major: parseInt(match[1], 10),
+    minor: match[2] !== undefined ? parseInt(match[2], 10) : 0,
+    patch: match[3] !== undefined ? parseInt(match[3], 10) : 0,
+  };
+}
+
+/**
+ * Determines whether a version transition represents a major version bump (#95).
+ *
+ * @param {string} oldVer
+ * @param {string} newVer
+ * @returns {boolean}
+ */
+export function isMajorBump(oldVer, newVer) {
+  const oldParsed = parseSemver(oldVer);
+  const newParsed = parseSemver(newVer);
+  if (!oldParsed || !newParsed) return false;
+
+  return newParsed.major > oldParsed.major;
+}
+
+/**
+ * Compares two dependency maps and returns detected major bumps (#95).
+ *
+ * @param {Record<string, string>} [oldDeps]
+ * @param {Record<string, string>} [newDeps]
+ * @param {string} [section="dependencies"]
+ * @returns {Array<{ pkg: string, from: string, to: string, section: string }>}
+ */
+export function compareDependencySection(oldDeps = {}, newDeps = {}, section = "dependencies") {
+  if (!oldDeps || !newDeps) return [];
+  const bumps = [];
+
+  for (const [pkg, newVer] of Object.entries(newDeps)) {
+    const oldVer = oldDeps[pkg];
+    if (typeof oldVer === "string" && typeof newVer === "string") {
+      if (isMajorBump(oldVer, newVer)) {
+        bumps.push({
+          pkg,
+          from: oldVer,
+          to: newVer,
+          section,
+        });
+      }
+    }
+  }
+
+  return bumps;
+}
+
+/**
+ * Inspects a mutation between two package.json objects for major dependency bumps (#95).
+ *
+ * @param {any} oldPkg
+ * @param {any} newPkg
+ * @returns {{ hasMajorBump: boolean, bumps: Array<{ pkg: string, from: string, to: string, section: string }> }}
+ */
+export function inspectPackageJsonDiff(oldPkg, newPkg) {
+  if (!oldPkg || typeof oldPkg !== "object" || !newPkg || typeof newPkg !== "object") {
+    return { hasMajorBump: false, bumps: [] };
+  }
+
+  const allBumps = [];
+
+  for (const section of DEPENDENCY_SECTIONS) {
+    const oldSec = oldPkg[section] || {};
+    const newSec = newPkg[section] || {};
+    const sectionBumps = compareDependencySection(oldSec, newSec, section);
+    allBumps.push(...sectionBumps);
+  }
+
+  return {
+    hasMajorBump: allBumps.length > 0,
+    bumps: allBumps,
+  };
+}
+
+/**
+ * Guard enforcing human confirmation on major dependency version updates (#95).
+ */
+export class VersionGuard {
+  /**
+   * @param {{ workspaceDir?: string }} [options]
+   */
+  constructor(options = {}) {
+    this.workspaceDir = options.workspaceDir || "";
+  }
+
+  /**
+   * Inspects a file write operation to detect major dependency bumps in package.json (#95).
+   *
+   * @param {string} targetPath - Path of file being written
+   * @param {string | object} newContent - Incoming content or parsed JSON
+   * @returns {{ majorBump: boolean, bumps: Array<any>, detail?: string }}
+   */
+  inspectWrite(targetPath, newContent) {
+    if (typeof targetPath !== "string") {
+      return { majorBump: false, bumps: [] };
+    }
+
+    const basename = path.basename(targetPath);
+    if (basename !== "package.json") {
+      return { majorBump: false, bumps: [] };
+    }
+
+    let parsedNew;
+    if (typeof newContent === "string") {
+      try {
+        parsedNew = JSON.parse(newContent);
+      } catch {
+        return { majorBump: false, bumps: [] };
+      }
+    } else if (newContent && typeof newContent === "object") {
+      parsedNew = newContent;
+    } else {
+      return { majorBump: false, bumps: [] };
+    }
+
+    // Attempt reading existing package.json
+    let existingPkg = null;
+    const resolvedPath = path.isAbsolute(targetPath)
+      ? targetPath
+      : path.resolve(this.workspaceDir || process.cwd(), targetPath);
+
+    try {
+      if (fs.existsSync(resolvedPath)) {
+        const raw = fs.readFileSync(resolvedPath, "utf-8");
+        existingPkg = JSON.parse(raw);
+      }
+    } catch {
+      // ignore read/parse error on existing file
+    }
+
+    if (!existingPkg) {
+      return { majorBump: false, bumps: [] };
+    }
+
+    const diff = inspectPackageJsonDiff(existingPkg, parsedNew);
+    if (diff.hasMajorBump) {
+      const descriptions = diff.bumps.map((b) => `${b.pkg} (${b.from} -> ${b.to})`).join(", ");
+      return {
+        majorBump: true,
+        bumps: diff.bumps,
+        detail: `Major dependency version bump detected: ${descriptions}`,
+      };
+    }
+
+    return { majorBump: false, bumps: [] };
+  }
+}