@coreyuan/vector-mind 1.0.44 → 1.0.49

package/dist/index.js

@@ -14,9 +14,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { BUILTIN_CONVENTIONS } from "./builtin-conventions.js";
-import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS, BUILTIN_GIT_COMMIT_SUMMARY_INSTRUCTIONS, BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS, BUILTIN_PAYLOAD_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
+import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS, BUILTIN_GIT_COMMIT_SUMMARY_INSTRUCTIONS, BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS, BUILTIN_PAYLOAD_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_REQUIREMENT_BOUNDARY_AND_MODULARITY_INSTRUCTIONS, BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.44";
+const SERVER_VERSION = "1.0.49";
 const rootFromEnv = process.env.VECTORMIND_ROOT?.trim() ?? "";
 const prettyJsonOutput = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_PRETTY_JSON ?? "").trim().toLowerCase());
 const debugLogEnabled = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_DEBUG_LOG ?? "").trim().toLowerCase());
@@ -65,6 +65,52 @@ const PENDING_PRUNE_EVERY = (() => {
         return 500;
     return n;
 })();
+const DEVELOPMENT_WARN_FILE_LINES = (() => {
+    const raw = process.env.VECTORMIND_WARN_FILE_LINES?.trim();
+    if (!raw)
+        return 800;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 100)
+        return 800;
+    return Math.min(50_000, n);
+})();
+const DEVELOPMENT_BLOCK_FILE_LINES = (() => {
+    const raw = process.env.VECTORMIND_BLOCK_FILE_LINES?.trim();
+    if (!raw)
+        return 1200;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < DEVELOPMENT_WARN_FILE_LINES)
+        return Math.max(1200, DEVELOPMENT_WARN_FILE_LINES);
+    return Math.min(100_000, n);
+})();
+const DEVELOPMENT_HUGE_FILE_LINES = (() => {
+    const raw = process.env.VECTORMIND_HUGE_FILE_LINES?.trim();
+    if (!raw)
+        return 3000;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < DEVELOPMENT_BLOCK_FILE_LINES) {
+        return Math.max(3000, DEVELOPMENT_BLOCK_FILE_LINES);
+    }
+    return Math.min(200_000, n);
+})();
+const DEVELOPMENT_WARN_FILE_BYTES = (() => {
+    const raw = process.env.VECTORMIND_WARN_FILE_BYTES?.trim();
+    if (!raw)
+        return 120_000;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 10_000)
+        return 120_000;
+    return Math.min(20_000_000, n);
+})();
+const DEVELOPMENT_WARN_PENDING_FILES = (() => {
+    const raw = process.env.VECTORMIND_WARN_PENDING_FILES?.trim();
+    if (!raw)
+        return 12;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return 12;
+    return Math.min(500, n);
+})();
 const RIPGREP_RESOLVE_TIMEOUT_MS = 5_000;
 const RIPGREP_SEARCH_TIMEOUT_MS = 30_000;
 const RIPGREP_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
@@ -1384,6 +1430,470 @@ function isContentIndexableFile(filePath) {
         return false;
     return getContentChunkKind(filePath) !== null;
 }
+function isLikelySourceImplementationFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return new Set([
+        ".ts",
+        ".tsx",
+        ".js",
+        ".jsx",
+        ".mjs",
+        ".cjs",
+        ".py",
+        ".go",
+        ".rs",
+        ".java",
+        ".kt",
+        ".cs",
+        ".c",
+        ".cc",
+        ".cpp",
+        ".h",
+        ".hpp",
+        ".vue",
+        ".svelte",
+    ]).has(ext);
+}
+function countFileLinesBounded(absPath, maxBytes) {
+    let stat;
+    try {
+        stat = fs.statSync(absPath);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isFile())
+        return null;
+    const bytesToRead = Math.min(stat.size, maxBytes);
+    const fd = fs.openSync(absPath, "r");
+    try {
+        const buffer = Buffer.alloc(bytesToRead);
+        const read = fs.readSync(fd, buffer, 0, bytesToRead, 0);
+        let lines = read > 0 ? 1 : 0;
+        for (let i = 0; i < read; i++) {
+            if (buffer[i] === 10)
+                lines += 1;
+        }
+        return { lines, truncated: stat.size > bytesToRead };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function isPathInsideProjectRoot(absPath) {
+    const root = path.resolve(projectRoot);
+    const rel = path.relative(root, path.resolve(absPath));
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function checkPathScope(inputPath) {
+    const normalizedInput = inputPath.trim() || ".";
+    const absPath = path.resolve(path.isAbsolute(normalizedInput) ? normalizedInput : path.join(projectRoot, normalizedInput));
+    return {
+        input_path: inputPath,
+        abs_path: absPath,
+        in_project: isPathInsideProjectRoot(absPath),
+        project_root: path.resolve(projectRoot),
+    };
+}
+function buildCrossProjectPathWarnings(paths) {
+    const checks = (paths ?? []).map((p) => checkPathScope(p)).filter((c) => !c.in_project);
+    if (!checks.length)
+        return [];
+    return [
+        {
+            code: "cross_project_path",
+            severity: "warning",
+            message: "A path points outside the current project_root. Switch project_root intentionally before reading/searching another repo; do not mix unrelated project context into the current requirement.",
+            files: checks.slice(0, 10).map((c) => c.input_path),
+            details: {
+                project_root: path.resolve(projectRoot),
+                paths: checks.slice(0, 10),
+                total_paths: checks.length,
+            },
+        },
+    ];
+}
+function buildLargeImplementationFileWarning(args) {
+    const linesValue = args.lineCountTruncated ? `${args.lineCount}+` : args.lineCount;
+    if (args.lineCount >= DEVELOPMENT_HUGE_FILE_LINES) {
+        return {
+            code: "huge_file_modularization_required",
+            severity: "blocker",
+            message: "This implementation file is huge. Before any normal feature work, perform mechanical modularization: move whole functions/types/impl blocks into real, clearly named modules/directories, avoid *.generated.* or *.parts files, preserve behavior, then run format/build/tests.",
+            files: [args.filePath],
+            details: {
+                lines: linesValue,
+                bytes: args.bytes,
+                warn_lines: DEVELOPMENT_WARN_FILE_LINES,
+                block_lines: DEVELOPMENT_BLOCK_FILE_LINES,
+                huge_lines: DEVELOPMENT_HUGE_FILE_LINES,
+                required_action: "mechanical_modularization",
+                allowed_change_modes: ["mechanical_modularization", "emergency_hotfix"],
+                forbidden_file_patterns: ["*.generated.*", "*.parts", "*.rs.parts", "*_part*"],
+                mechanical_rules: [
+                    "move whole declarations only",
+                    "use real module names and clear directory boundaries",
+                    "preserve behavior and public semantics",
+                    "only add necessary mod/use/pub(crate)/re-export glue",
+                    "run formatter, build, and tests after each phase",
+                ],
+                reading: !!args.reading,
+            },
+        };
+    }
+    return {
+        code: args.code,
+        severity: args.code === "large_file" || (args.code === "large_file_read" && args.lineCount < DEVELOPMENT_BLOCK_FILE_LINES)
+            ? "warning"
+            : "blocker",
+        message: args.code === "large_file"
+            ? "This implementation file is getting large. Prefer extracting focused modules instead of continuing to pile unrelated responsibilities into it."
+            : args.reading
+                ? "You are reading a very large implementation file. Do not keep patching new feature code into it; identify a narrow function and split new behavior into focused modules unless this task is explicitly a planned extraction."
+                : "This implementation file is already very large. Do not add new feature code here by default; split into a focused module/service/component and keep this file as a thin entry.",
+        files: [args.filePath],
+        details: {
+            lines: linesValue,
+            bytes: args.bytes,
+            warn_lines: DEVELOPMENT_WARN_FILE_LINES,
+            block_lines: DEVELOPMENT_BLOCK_FILE_LINES,
+            huge_lines: DEVELOPMENT_HUGE_FILE_LINES,
+        },
+    };
+}
+function buildFileReadDevelopmentWarnings(filePath, absPath, stat) {
+    const warnings = [];
+    if (!isPathInsideProjectRoot(absPath)) {
+        warnings.push(...buildCrossProjectPathWarnings([filePath]));
+        return warnings;
+    }
+    if (!isLikelySourceImplementationFile(filePath))
+        return warnings;
+    let st = stat;
+    try {
+        st ??= fs.statSync(absPath);
+    }
+    catch {
+        return warnings;
+    }
+    if (!st.isFile())
+        return warnings;
+    const lineInfo = countFileLinesBounded(absPath, 2_000_000);
+    const lineCount = lineInfo?.lines ?? 0;
+    const tooManyLines = lineCount >= DEVELOPMENT_BLOCK_FILE_LINES;
+    const warnLines = lineCount >= DEVELOPMENT_WARN_FILE_LINES;
+    const warnBytes = st.size >= DEVELOPMENT_WARN_FILE_BYTES;
+    if (!tooManyLines && !warnLines && !warnBytes)
+        return warnings;
+    warnings.push(buildLargeImplementationFileWarning({
+        code: "large_file_read",
+        filePath,
+        lineCount,
+        lineCountTruncated: lineInfo?.truncated,
+        bytes: st.size,
+        reading: true,
+    }));
+    return warnings;
+}
+function buildMatchedFileDevelopmentWarnings(filePaths) {
+    const seen = new Set();
+    const warnings = [];
+    for (const fp of filePaths) {
+        if (!fp || seen.has(fp))
+            continue;
+        seen.add(fp);
+        const abs = path.isAbsolute(fp) ? path.resolve(fp) : path.join(projectRoot, fp);
+        warnings.push(...buildFileReadDevelopmentWarnings(normalizeToDbPath(fp), abs));
+        if (warnings.length >= 8)
+            break;
+    }
+    return warnings;
+}
+function buildRequirementStartWarnings(args) {
+    const warnings = [];
+    const activeReqs = listActiveRequirementsStmt.all(10);
+    if (!args.close_previous && activeReqs.length > 0) {
+        warnings.push({
+            code: "multiple_active_requirements",
+            severity: "warning",
+            message: "Starting a requirement without closing previous active requirements can mix unrelated context. Only keep multiple active requirements when the user explicitly asked for parallel work.",
+            details: {
+                active_requirements: activeReqs.slice(0, 5).map((r) => ({ id: r.id, title: r.title, status: r.status })),
+            },
+        });
+    }
+    const text = `${args.title}\n${args.background}`.toLowerCase();
+    const broadTerms = [
+        "顺便",
+        "一起",
+        "所有",
+        "全部",
+        "整体",
+        "重构",
+        "统一",
+        "优化一下",
+        "顺手",
+        "相关的",
+        "all ",
+        "everything",
+        "refactor",
+        "cleanup",
+        "clean up",
+    ];
+    const matched = broadTerms.filter((term) => text.includes(term));
+    if (matched.length >= 2 || text.length > 1800) {
+        warnings.push({
+            code: "broad_requirement_scope",
+            severity: "warning",
+            message: "The requirement wording looks broad. Treat the current user request as the only boundary; do not add extra workflows, fields, pages, interfaces, or touch completed related features unless explicitly required.",
+            details: { matched_terms: matched.slice(0, 10), text_length: text.length },
+        });
+    }
+    return warnings;
+}
+function normalizeScopeTerms(values) {
+    return Array.from(new Set((values ?? []).map((v) => v.trim()).filter(Boolean)));
+}
+function buildRequirementScopeContract(args) {
+    const allowTerms = normalizeScopeTerms(args.scope_allow);
+    const denyTerms = normalizeScopeTerms(args.scope_deny);
+    const allowedPaths = normalizeScopeTerms(args.allowed_paths).map(normalizeToDbPath);
+    const deniedPaths = normalizeScopeTerms(args.denied_paths).map((p) => p.replace(/\\/g, "/"));
+    return {
+        allow_terms: allowTerms,
+        deny_terms: Array.from(new Set(denyTerms)),
+        allowed_paths: Array.from(new Set(allowedPaths)),
+        denied_paths: Array.from(new Set(deniedPaths)),
+        inferred_from: [],
+    };
+}
+function getRequirementScopeContract(reqId) {
+    const memId = getRequirementMemoryItemIdStmt.get(reqId)?.id;
+    if (memId == null)
+        return null;
+    const row = getMemoryItemByIdStmt.get(memId);
+    const meta = parseMetadataJson(row?.metadata_json);
+    const raw = meta.scope_contract;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    return {
+        allow_terms: Array.isArray(obj.allow_terms) ? obj.allow_terms.filter((v) => typeof v === "string") : [],
+        deny_terms: Array.isArray(obj.deny_terms) ? obj.deny_terms.filter((v) => typeof v === "string") : [],
+        allowed_paths: Array.isArray(obj.allowed_paths) ? obj.allowed_paths.filter((v) => typeof v === "string") : [],
+        denied_paths: Array.isArray(obj.denied_paths) ? obj.denied_paths.filter((v) => typeof v === "string") : [],
+        inferred_from: Array.isArray(obj.inferred_from) ? obj.inferred_from.filter((v) => typeof v === "string") : [],
+    };
+}
+function wildcardToRegex(pattern) {
+    const source = escapeRegExp(pattern).replace(/\\\*/g, ".*");
+    return new RegExp(source, "i");
+}
+function pathMatchesAnyPattern(filePath, patterns) {
+    const normalized = filePath.replace(/\\/g, "/");
+    return patterns.filter((p) => wildcardToRegex(p.replace(/\\/g, "/")).test(normalized));
+}
+function fileContentHasDeniedTerms(filePath, terms) {
+    if (!terms.length || filePath === "(unspecified)")
+        return [];
+    const abs = path.isAbsolute(filePath) ? path.resolve(filePath) : path.join(projectRoot, filePath);
+    let st;
+    try {
+        st = fs.statSync(abs);
+    }
+    catch {
+        return [];
+    }
+    if (!st.isFile() || st.size > 2_000_000)
+        return [];
+    let content = "";
+    try {
+        content = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const lower = `${filePath}\n${content.slice(0, 250_000)}`.toLowerCase();
+    return terms.filter((term) => lower.includes(term.toLowerCase()));
+}
+function mergeScopeContracts(base, extra) {
+    if (!base && !extra)
+        return null;
+    return {
+        allow_terms: Array.from(new Set([...(base?.allow_terms ?? []), ...(extra?.allow_terms ?? [])])),
+        deny_terms: Array.from(new Set([...(base?.deny_terms ?? []), ...(extra?.deny_terms ?? [])])),
+        allowed_paths: Array.from(new Set([...(base?.allowed_paths ?? []), ...(extra?.allowed_paths ?? [])])),
+        denied_paths: Array.from(new Set([...(base?.denied_paths ?? []), ...(extra?.denied_paths ?? [])])),
+        inferred_from: Array.from(new Set([...(base?.inferred_from ?? []), ...(extra?.inferred_from ?? [])])),
+    };
+}
+function buildScopeDriftWarnings(args) {
+    const requirementContract = args.requirement ? getRequirementScopeContract(args.requirement.id) : null;
+    const contract = mergeScopeContracts(requirementContract, args.contract);
+    const hasScopeRules = !!contract && (contract.allow_terms.length > 0 ||
+        contract.deny_terms.length > 0 ||
+        contract.allowed_paths.length > 0 ||
+        contract.denied_paths.length > 0);
+    const warnings = [];
+    if (!contract || !hasScopeRules) {
+        if (args.includeMissingContractHint && args.files.length > 0) {
+            warnings.push({
+                code: "scope_contract_missing",
+                severity: "warning",
+                message: "No explicit scope allow/deny contract is set for this requirement, so the planned files cannot be proven in-scope before editing. Define scope_allow/scope_deny or allowed_paths/denied_paths before editing.",
+                files: args.files.map((f) => normalizeToDbPath(f.file_path)).slice(0, 12),
+                details: {
+                    requirement_id: args.requirement?.id ?? null,
+                    requirement_title: args.requirement?.title ?? null,
+                },
+            });
+        }
+        return warnings;
+    }
+    const allowTerms = contract.allow_terms;
+    const denyTerms = contract.deny_terms;
+    const allowedPaths = contract.allowed_paths;
+    const deniedPaths = contract.denied_paths;
+    const intentText = args.intent ?? "";
+    const intentDenied = denyTerms.filter((term) => intentText.toLowerCase().includes(term.toLowerCase()));
+    const suspicious = [];
+    for (const f of args.files) {
+        const fp = normalizeToDbPath(f.file_path);
+        if (fp === "(unspecified)")
+            continue;
+        const matchedDeniedPaths = pathMatchesAnyPattern(fp, deniedPaths);
+        const matchedDeniedTerms = [
+            ...denyTerms.filter((term) => fp.toLowerCase().includes(term.toLowerCase())),
+            ...fileContentHasDeniedTerms(fp, denyTerms),
+        ];
+        const isExplicitlyAllowed = pathMatchesAnyPattern(fp, allowedPaths).length > 0 ||
+            allowTerms.some((term) => fp.toLowerCase().includes(term.toLowerCase()));
+        const violatesAllowedPaths = allowedPaths.length > 0 && pathMatchesAnyPattern(fp, allowedPaths).length === 0;
+        if ((matchedDeniedPaths.length || matchedDeniedTerms.length || intentDenied.length || violatesAllowedPaths) &&
+            !isExplicitlyAllowed) {
+            suspicious.push({
+                file_path: fp,
+                matched_terms: Array.from(new Set([...matchedDeniedTerms, ...intentDenied])).slice(0, 12),
+                matched_paths: [
+                    ...matchedDeniedPaths.slice(0, 12),
+                    ...(violatesAllowedPaths ? [`outside allowed_paths: ${allowedPaths.slice(0, 5).join(", ")}`] : []),
+                ],
+            });
+        }
+    }
+    if (suspicious.length) {
+        warnings.push({
+            code: "scope_drift",
+            severity: "blocker",
+            message: "The current requirement appears to be touching a denied or out-of-scope domain. Stop and narrow the change unless the user explicitly expanded this requirement.",
+            files: suspicious.slice(0, 12).map((s) => s.file_path),
+            details: {
+                requirement_id: args.requirement?.id ?? null,
+                requirement_title: args.requirement?.title ?? null,
+                inferred_from: contract.inferred_from,
+                deny_terms: denyTerms.slice(0, 30),
+                denied_paths: deniedPaths.slice(0, 30),
+                suspicious: suspicious.slice(0, 12),
+            },
+        });
+    }
+    return warnings;
+}
+function buildDevelopmentWarnings(files, opts = {}) {
+    const warnings = [];
+    const uniqueFiles = Array.from(new Set(files
+        .map((f) => f.file_path)
+        .filter((f) => !!f && f !== "(unspecified)")
+        .map((f) => normalizeToDbPath(f))));
+    if (opts.includeUnspecified || files.some((f) => f.file_path === "(unspecified)")) {
+        warnings.push({
+            code: "unspecified_change_target",
+            severity: "warning",
+            message: "No changed file target was captured. For development work, sync concrete files so the current requirement owns only its real changes.",
+        });
+    }
+    if (uniqueFiles.length >= DEVELOPMENT_WARN_PENDING_FILES) {
+        warnings.push({
+            code: "many_pending_files",
+            severity: "warning",
+            message: "This requirement touches many files. Re-check the user request and keep only files required by the current requirement.",
+            files: uniqueFiles.slice(0, 20),
+            details: { total_files: uniqueFiles.length, threshold: DEVELOPMENT_WARN_PENDING_FILES },
+        });
+    }
+    const topDirs = new Set(uniqueFiles
+        .map((f) => f.replace(/\\/g, "/").split("/").filter(Boolean)[0] ?? "")
+        .filter(Boolean));
+    if (uniqueFiles.length >= 6 && topDirs.size >= 4) {
+        warnings.push({
+            code: "broad_change_surface",
+            severity: "warning",
+            message: "Changed files span several top-level areas. Avoid modifying completed or merely related features unless the current requirement explicitly needs it.",
+            files: uniqueFiles.slice(0, 20),
+            details: { top_level_dirs: Array.from(topDirs).slice(0, 12), total_dirs: topDirs.size },
+        });
+    }
+    for (const relPath of uniqueFiles) {
+        if (!isLikelySourceImplementationFile(relPath))
+            continue;
+        const absPath = path.isAbsolute(relPath) ? relPath : path.join(projectRoot, relPath);
+        let stat;
+        try {
+            stat = fs.statSync(absPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        const lineInfo = countFileLinesBounded(absPath, 2_000_000);
+        const lineCount = lineInfo?.lines ?? 0;
+        const tooManyLines = lineCount >= DEVELOPMENT_BLOCK_FILE_LINES;
+        const warnLines = lineCount >= DEVELOPMENT_WARN_FILE_LINES;
+        const warnBytes = stat.size >= DEVELOPMENT_WARN_FILE_BYTES;
+        if (!tooManyLines && !warnLines && !warnBytes)
+            continue;
+        warnings.push(buildLargeImplementationFileWarning({
+            code: tooManyLines ? "very_large_file" : "large_file",
+            filePath: relPath,
+            lineCount,
+            lineCountTruncated: lineInfo?.truncated,
+            bytes: stat.size,
+        }));
+    }
+    return warnings;
+}
+function isLargeFileWarningCode(code) {
+    return (code === "large_file" ||
+        code === "very_large_file" ||
+        code === "large_file_read" ||
+        code === "huge_file_modularization_required");
+}
+function isDevelopmentWarningBlockingForChangeMode(warning, changeMode) {
+    if (changeMode === "mechanical_modularization") {
+        if (isLargeFileWarningCode(warning.code))
+            return false;
+        if (warning.code === "scope_contract_missing")
+            return false;
+    }
+    if (changeMode === "emergency_hotfix") {
+        if (isLargeFileWarningCode(warning.code))
+            return false;
+        if (warning.code === "scope_contract_missing")
+            return false;
+    }
+    return warning.severity === "blocker" || warning.severity === "warning";
+}
+function compactDevelopmentWarningsText(warnings) {
+    if (!warnings.length)
+        return [];
+    const lines = ["development warnings:"];
+    for (const w of warnings.slice(0, 8)) {
+        const files = w.files?.length ? ` files=${w.files.slice(0, 5).join(",")}` : "";
+        lines.push(`- ${w.severity} ${w.code}: ${oneLine(w.message, 180)}${files}`);
+    }
+    return lines;
+}
 function extractSymbols(filePath, content) {
     const ext = path.extname(filePath).toLowerCase();
     if (ext === ".py")
@@ -1541,6 +2051,142 @@ function extractCLikeSymbols(content) {
     }
     return symbols;
 }
+function declarationRegexForExtension(ext) {
+    switch (ext) {
+        case ".rs":
+            return /^\s*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?(?:fn|struct|enum|trait|impl|mod|type|const|static)\s+([A-Za-z_][\w]*)?/;
+        case ".go":
+            return /^\s*(?:func|type|const|var)\s+(?:\([^)]*\)\s*)?([A-Za-z_][\w]*)?/;
+        case ".py":
+            return /^(?:class|async\s+def|def)\s+([A-Za-z_][\w]*)/;
+        case ".ts":
+        case ".tsx":
+        case ".js":
+        case ".jsx":
+        case ".mjs":
+        case ".cjs":
+            return /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|enum|const|let|var)\s+([A-Za-z_$][\w$]*)?/;
+        default:
+            return /^\s*(?:pub\s+)?(?:async\s+)?(?:fn|function|class|struct|enum|interface|type|const|static)\s+([A-Za-z_][\w]*)?/;
+    }
+}
+function moduleNameFromDeclaration(name, signature) {
+    const text = `${name} ${signature}`.toLowerCase();
+    const rules = [
+        [/(config|setting|env)/, "config"],
+        [/(state|store|persist)/, "state"],
+        [/(api|client|request|response|heartbeat|activate|sync)/, "api"],
+        [/(service|daemon|install|start|stop)/, "service"],
+        [/(log|logger|redact)/, "logging"],
+        [/(gui|window|dialog|form|view|button|list)/, "ui"],
+        [/(share|disk|smb|unc|folder|directory)/, "share"],
+        [/(repair|cleanup|probe|health)/, "maintenance"],
+        [/(path|sanitize|normalize|host|ip|util|helper)/, "util"],
+        [/(test|mock|fixture)/, "tests"],
+    ];
+    for (const [pattern, moduleName] of rules) {
+        if (pattern.test(text))
+            return moduleName;
+    }
+    return "core";
+}
+function topLevelDeclarationsForPlan(content, ext, maxDecls = 160) {
+    const decls = [];
+    const lines = content.split(/\r?\n/);
+    const regex = declarationRegexForExtension(ext);
+    for (let i = 0; i < lines.length && decls.length < maxDecls; i++) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("#"))
+            continue;
+        const m = raw.match(regex);
+        if (!m)
+            continue;
+        const fallback = trimmed.split(/\s+/).slice(0, 3).join("_").replace(/[^\w$]+/g, "_");
+        const name = (m[1] || fallback || `declaration_${i + 1}`).replace(/^[^A-Za-z_]+/, "") || `declaration_${i + 1}`;
+        const kind = trimmed.split(/\s+/).find((part) => ["fn", "function", "class", "struct", "enum", "trait", "impl", "mod", "type", "const", "static", "interface"].includes(part.replace(/[({].*$/, ""))) ?? "declaration";
+        decls.push({
+            line: i + 1,
+            kind,
+            name,
+            signature: oneLine(trimmed, 180),
+            suggested_module: moduleNameFromDeclaration(name, trimmed),
+        });
+    }
+    return decls;
+}
+function targetPathForModule(originalFilePath, targetDir, moduleName) {
+    const ext = path.extname(originalFilePath) || ".txt";
+    const normalizedTargetDir = targetDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (!normalizedTargetDir || normalizedTargetDir === ".")
+        return `${moduleName}${ext}`;
+    return `${normalizedTargetDir}/${moduleName}${ext}`;
+}
+function buildLargeFileSplitPlan(args) {
+    const content = fs.readFileSync(args.absPath, "utf8");
+    const st = fs.statSync(args.absPath);
+    const lines = content.split(/\r?\n/).length;
+    const ext = path.extname(args.absPath).toLowerCase();
+    const baseName = path.basename(args.filePath, path.extname(args.filePath));
+    const parentDir = path.dirname(args.filePath).replace(/\\/g, "/");
+    const defaultTargetDir = parentDir === "." ? baseName : `${parentDir}/${baseName}`;
+    const targetDir = normalizeToDbPath(args.targetDir ?? defaultTargetDir);
+    const declarations = topLevelDeclarationsForPlan(content, ext);
+    const grouped = new Map();
+    for (const decl of declarations) {
+        const key = grouped.size >= args.maxModules && !grouped.has(decl.suggested_module) ? "core" : decl.suggested_module;
+        const list = grouped.get(key) ?? [];
+        list.push(decl);
+        grouped.set(key, list);
+    }
+    if (!grouped.size)
+        grouped.set("core", []);
+    const modules = Array.from(grouped.entries())
+        .slice(0, args.maxModules)
+        .map(([moduleName, decls]) => ({
+        module: moduleName,
+        target_path: targetPathForModule(args.filePath, targetDir, moduleName),
+        declarations: decls.slice(0, 24).map((d) => `${d.kind} ${d.name} @L${d.line}`),
+        reason: `Move whole ${moduleName}-related declarations together without changing behavior.`,
+    }));
+    return {
+        ok: true,
+        file_path: args.filePath,
+        line_count: lines,
+        bytes: st.size,
+        huge_threshold_lines: DEVELOPMENT_HUGE_FILE_LINES,
+        required_action: "mechanical_modularization",
+        intent: args.intent,
+        target_dir: targetDir,
+        forbidden_patterns: ["*.generated.*", "*.parts", "*.rs.parts", "*_part*", "*Part*"],
+        mechanical_rules: [
+            "Move only complete declarations/impl blocks/functions/classes/types; do not split a declaration body.",
+            "Use real module names and clear directory boundaries; do not create generated/parts/partN files.",
+            "Preserve behavior, names, API semantics, data formats, side effects, and test expectations.",
+            "Only add necessary module declarations, imports, pub(crate), and re-exports to make moved code compile.",
+            "Run formatter, build/check, and relevant tests after each small phase.",
+        ],
+        modules,
+        steps: [
+            "Create a dedicated mechanical modularization requirement before touching the huge file.",
+            "Add the target module directory and move one cohesive declaration group at a time.",
+            "Keep the original file as a thin entry/mod orchestration file where possible.",
+            "After each group, run formatter and the smallest available compile/test command.",
+            "Record the split with record_large_file_split(status='partial' or 'resolved').",
+            "Resume the original feature only after the target huge file is no longer the default place for new code.",
+        ],
+        validation: [
+            "No *.generated.*, *.parts, *.rs.parts, or numbered part files were created.",
+            "The original file line count decreased or contains only thin orchestration glue.",
+            "Formatter passes.",
+            "Build/check passes.",
+            "Relevant tests pass.",
+        ],
+        notes: declarations.length
+            ? [`Detected ${declarations.length} top-level declarations for mechanical grouping.`]
+            : ["No top-level declarations were detected by lightweight scanning; split by obvious cohesive sections and verify after each move."],
+    };
+}
 function chunkTextByLines(content, opts) {
     const lines = content.split(/\r?\n/);
     if (lines.length === 0)
@@ -1744,12 +2390,42 @@ const StartRequirementArgsSchema = ProjectRootArgSchema.merge(z.object({
     title: z.string().min(1),
     background: z.string().optional().default(""),
     close_previous: z.boolean().optional().default(true),
+    scope_allow: z.array(z.string().min(1)).optional(),
+    scope_deny: z.array(z.string().min(1)).optional(),
+    allowed_paths: z.array(z.string().min(1)).optional(),
+    denied_paths: z.array(z.string().min(1)).optional(),
 }));
 const SyncChangeIntentArgsSchema = ProjectRootArgSchema.merge(z.object({
     intent: z.string().min(1),
     files: z.array(z.string().min(1)).optional(),
     affected_files: z.array(z.string().min(1)).optional(),
 }));
+const PreflightChangeScopeArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
+    intent: z.string().optional().default(""),
+    files: z.array(z.string().min(1)).optional(),
+    planned_files: z.array(z.string().min(1)).optional(),
+    change_mode: z
+        .enum(["feature", "bugfix", "refactor", "mechanical_modularization", "emergency_hotfix"])
+        .optional()
+        .default("feature"),
+    scope_allow: z.array(z.string().min(1)).optional(),
+    scope_deny: z.array(z.string().min(1)).optional(),
+    allowed_paths: z.array(z.string().min(1)).optional(),
+    denied_paths: z.array(z.string().min(1)).optional(),
+}));
+const PlanLargeFileSplitArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
+    file: z.string().min(1),
+    intent: z.string().optional().default("mechanical modularization"),
+    target_dir: z.string().optional(),
+    max_modules: z.number().int().min(2).max(30).optional().default(12),
+}));
+const RecordLargeFileSplitArgsSchema = ProjectRootArgSchema.merge(z.object({
+    file: z.string().min(1),
+    status: z.enum(["planned", "in_progress", "partial", "resolved"]),
+    summary: z.string().min(1),
+    modules: z.array(z.string().min(1)).optional(),
+    remaining_lines: z.number().int().min(0).optional(),
+}));
 const QueryCodebaseArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     query: z.string().min(1),
 }));
@@ -2079,6 +2755,7 @@ function compactGrepText(data) {
     const lines = [
         `grep ${data.backend}${fallback} mode=${data.mode} matches=${data.matches.length}/${total} truncated=${data.truncated}${candidateText} q="${oneLine(data.query, 100)}"`,
     ];
+    lines.push(...compactDevelopmentWarningsText(data.development_warnings ?? []));
     if (data.ripgrep_error)
         lines.push(`ripgrep_error ${oneLine(data.ripgrep_error, 180)}`);
     for (const m of data.matches.slice(0, 80)) {
@@ -2108,15 +2785,18 @@ function compactReadTextFileText(data) {
     const offset = data.offset != null ? ` offset=${data.offset}` : "";
     const header = `file ${data.file_path}${offset} chars=${data.returned_chars}/${data.total_chars} truncated=${data.truncated}`;
     const hint = data.truncated ? "\nhint: continue with offset or read_file_lines; use format=json for metadata fields" : "";
-    return `${header}\n${data.text}${hint}`;
+    const warnings = compactDevelopmentWarningsText(data.development_warnings ?? []).join("\n");
+    return `${header}${warnings ? `\n${warnings}` : ""}\n${data.text}${hint}`;
 }
 function compactReadFileLinesText(data) {
     const header = `lines ${data.file_path}:${data.from_line}-${data.to_line} returned=${data.returned} truncated=${data.truncated}`;
     const hint = data.truncated ? "\nhint: narrow range or raise max_lines/max_chars; use format=json for metadata fields" : "";
-    return `${header}\n${data.text}${hint}`;
+    const warnings = compactDevelopmentWarningsText(data.development_warnings ?? []).join("\n");
+    return `${header}${warnings ? `\n${warnings}` : ""}\n${data.text}${hint}`;
 }
 function compactQueryCodebaseText(data) {
     const lines = [`query_codebase matches=${data.matches.length} q="${oneLine(data.query, 100)}"`];
+    lines.push(...compactDevelopmentWarningsText(data.development_warnings ?? []));
     for (const m of data.matches.slice(0, 50)) {
         lines.push(`${m.file_path}: ${m.type} ${m.name}${m.signature ? ` — ${oneLine(m.signature, 160)}` : ""}`);
     }
@@ -2151,6 +2831,44 @@ function compactMaintenanceText(data) {
     lines.push("hint: dry_run=false applies changes; vacuum=true reclaims sqlite file space after pruning");
     return lines.join("\n");
 }
+function compactPreflightChangeScopeText(data) {
+    const req = data.active_requirement ? `#${data.active_requirement.id} ${data.active_requirement.title}` : "none";
+    const lines = [
+        `preflight_change_scope ok=${data.ok} safe_to_edit=${data.safe_to_edit} mode=${data.change_mode} requirement=${req} files=${data.files.length} intent="${oneLine(data.intent, 120)}"`,
+        `action: ${oneLine(data.recommended_action, 180)}`,
+    ];
+    if (data.required_action)
+        lines.push(`required_action=${data.required_action}`);
+    if (data.allowed_change_modes?.length)
+        lines.push(`allowed_change_modes=${data.allowed_change_modes.join(",")}`);
+    if (data.scope_contract) {
+        lines.push(`scope allow_terms=${data.scope_contract.allow_terms.length} deny_terms=${data.scope_contract.deny_terms.length} allowed_paths=${data.scope_contract.allowed_paths.length} denied_paths=${data.scope_contract.denied_paths.length}`);
+    }
+    lines.push(...compactDevelopmentWarningsText(data.development_warnings));
+    if (!data.development_warnings.length)
+        lines.push("- no development warnings");
+    return lines.join("\n");
+}
+function compactLargeFileSplitPlanText(data) {
+    const lines = [
+        `large_file_split ok=${data.ok} file=${data.file_path} lines=${data.line_count} threshold=${data.huge_threshold_lines} action=${data.required_action}`,
+        `target_dir=${data.target_dir}`,
+        `forbidden=${data.forbidden_patterns.join(",")}`,
+    ];
+    lines.push("modules:");
+    for (const m of data.modules.slice(0, 20)) {
+        const decls = m.declarations.length ? ` decls=${m.declarations.slice(0, 8).join("; ")}` : " decls=(manual sections)";
+        lines.push(`- ${m.module} -> ${m.target_path}${decls}`);
+    }
+    lines.push("steps:");
+    for (const step of data.steps.slice(0, 8))
+        lines.push(`- ${step}`);
+    lines.push("validation:");
+    for (const v of data.validation.slice(0, 8))
+        lines.push(`- ${v}`);
+    lines.push("hint: use format=json for full declarations/rules");
+    return lines.join("\n");
+}
 function compactBootstrapText(data) {
     const lines = [];
     lines.push(`ok ctx ${data.root_source} watcher=${data.watcher_enabled ? (data.watcher_ready ? "ready" : "starting") : "off"} root=${data.project_root}`);
@@ -2175,6 +2893,7 @@ function compactBootstrapText(data) {
     else {
         lines.push("pending 0");
     }
+    lines.push(...compactDevelopmentWarningsText(data.development_warnings ?? []));
     if (data.items.length) {
         lines.push("requirements:");
         for (const item of data.items) {
@@ -4285,6 +5004,9 @@ function buildServerInstructions() {
         "Built-in architecture and code-organization quality policy:",
         BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS,
         "",
+        "Built-in requirement boundary and modularity quality policy:",
+        BUILTIN_REQUIREMENT_BOUNDARY_AND_MODULARITY_INSTRUCTIONS,
+        "",
         "Built-in frontend output-purity quality policy:",
         BUILTIN_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS,
         "",
@@ -4315,7 +5037,13 @@ function buildServerInstructions() {
         "- For raw repo text search with exact file+line+col matches, prefer grep({ query: <pattern> }). It uses ripgrep against real project files when available, applies built-in noise filters, and only falls back to indexed search if ripgrep is unavailable.",
         "- To read a bounded segment of a file, prefer read_file_lines({ path: <file>, from_line/to_line or total_count }) over unbounded file reads.",
         "- BEFORE editing code: call start_requirement(title, background) to set the active requirement.",
+        "  - When the user names a narrow feature/domain, pass scope_allow/allowed_paths and scope_deny/denied_paths when useful. These are generic project-specific scope boundaries, not business-specific built-ins.",
+        "- BEFORE editing once target files/modules are known: call preflight_change_scope(intent, files/planned_files, optional scope_allow/scope_deny/allowed_paths/denied_paths). If ok=false/safe_to_edit=false or it returns development_warnings, stop before editing and narrow the plan unless the user explicitly expands the requirement.",
+        "- Treat the active requirement as the only change boundary. Do not add extra business behavior, new flows, new fields, new interfaces, or touch completed/related features unless the user explicitly asked or the change is strictly necessary.",
+        "- Do not keep piling new feature code into a large single file. Prefer small modules/services/components; if an implementation file is already large, split it before adding more responsibilities.",
+        "- If preflight_change_scope/read_file_lines/grep/query_codebase/get_pending_changes/sync_change_intent returns huge_file_modularization_required, do not continue normal feature work. Call plan_large_file_split, perform mechanical modularization with real module names/directories, never create generated/parts/partN files, then call record_large_file_split before resuming normal feature work. Only use preflight_change_scope(change_mode='mechanical_modularization') for the split itself; use change_mode='emergency_hotfix' only for the smallest urgent fix and still record why the split was deferred.",
         "- AFTER editing + saving: call get_pending_changes() to see unsynced files, then call sync_change_intent(intent, files). (You can omit files to auto-link all pending changes.)",
+        "- If preflight_change_scope, read_file_lines, grep, query_codebase, get_pending_changes, or sync_change_intent returns development_warnings, address those warnings before continuing or explain why the current requirement truly needs that scope.",
         "- After major milestones/decisions: call upsert_project_summary(summary) and/or add_note(...) to persist durable context locally.",
         "- When a requirement or user decision changes/reverses an older behavior, call upsert_decision(key, title, content, supersedes_req_ids?/supersedes_memory_ids?) and/or supersede_memory(...). Current decisions are shown in bootstrap_context/get_brain_dump and superseded memories are hidden from default semantic recall so stale requirements do not override newer facts.",
         "- If the user states a durable project convention (build commands, frameworks, naming rules, output paths): call upsert_convention(key, content, tags) so it is applied in future sessions.",
@@ -4974,14 +5702,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: [
             {
                 name: "start_requirement",
-                description: "MUST call BEFORE editing code. Starts/activates a requirement so all subsequent code changes can be linked to a concrete intent (do not edit code without an active requirement).",
+                description: "MUST call BEFORE editing code. Starts/activates the concrete user requirement so subsequent changes stay inside that requirement boundary and do not accumulate unrelated work. Supports scope_allow/scope_deny and allowed_paths/denied_paths to prevent unrelated domain drift.",
                 inputSchema: toJsonSchemaCompat(StartRequirementArgsSchema),
             },
             {
                 name: "sync_change_intent",
-                description: "MUST call AFTER you edit code and save files. Archives the intent summary and links affected files to the current active requirement. If you omit files, the server will auto-link all pending changed files since the last sync.",
+                description: "MUST call AFTER you edit code and save files. Archives the intent summary, links affected files to the current active requirement, and returns development_warnings for oversized files, broad change scope, or missing file targets.",
                 inputSchema: toJsonSchemaCompat(SyncChangeIntentArgsSchema),
             },
+            {
+                name: "preflight_change_scope",
+                description: "MUST call BEFORE editing once you know the intended files/modules. Checks planned files against the active requirement and optional generic scope_allow/scope_deny/allowed_paths/denied_paths. If ok=false/safe_to_edit=false, stop before editing and narrow the plan or scope contract. For huge files, use change_mode='mechanical_modularization' only when the task is to split the file.",
+                inputSchema: toJsonSchemaCompat(PreflightChangeScopeArgsSchema),
+            },
+            {
+                name: "plan_large_file_split",
+                description: "Plan a mechanical modularization split for a huge implementation file. Produces real module names/directories and explicitly forbids generated/parts/partN files. Use this before normal feature work when preflight_change_scope returns huge_file_modularization_required.",
+                inputSchema: toJsonSchemaCompat(PlanLargeFileSplitArgsSchema),
+            },
+            {
+                name: "record_large_file_split",
+                description: "Record the planned/in-progress/partial/resolved status of a huge-file mechanical modularization split so future sessions know the file is being decomposed and where modules moved.",
+                inputSchema: toJsonSchemaCompat(RecordLargeFileSplitArgsSchema),
+            },
             {
                 name: "get_brain_dump",
                 description: "Restore recent requirements/changes/notes/summary/pending changes. Prefer bootstrap_context() at session start when you also want recall from the local memory store.",
@@ -4989,12 +5732,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "bootstrap_context",
-                description: "MUST call at the start of every new chat/session. Returns brain dump + pending changes, and (if you pass query) matches from the local memory store to avoid guessing.",
+                description: "MUST call at the start of every new chat/session. Returns brain dump + pending changes + development_warnings, and (if you pass query) matches from the local memory store to avoid guessing.",
                 inputSchema: toJsonSchemaCompat(BootstrapContextArgsSchema),
             },
             {
                 name: "get_pending_changes",
-                description: "List files that changed locally but have not been acknowledged by sync_change_intent yet. Use this to see what needs syncing (or omit files in sync_change_intent to auto-link them).",
+                description: "List files that changed locally but have not been acknowledged by sync_change_intent yet. Also returns development_warnings to catch god-file growth, broad change scope, and requirement-boundary drift.",
                 inputSchema: toJsonSchemaCompat(GetPendingChangesArgsSchema),
             },
             {
@@ -5039,7 +5782,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "grep",
-                description: "Repo text search with precise file/line/col matches, powered by ripgrep against real project files plus built-in noise filters. Falls back to indexed search only when ripgrep is unavailable.",
+                description: "Repo text search with precise file/line/col matches, powered by ripgrep against real project files plus built-in noise filters. Falls back to indexed search only when ripgrep is unavailable. Returns development_warnings for cross-project paths or huge implementation-file matches.",
                 inputSchema: toJsonSchemaCompat(GrepArgsSchema),
             },
             {
@@ -5054,7 +5797,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "read_file_lines",
-                description: "Read a specific line range from a file under project_root (with strict size limits). Prefer this over Get-Content for deterministic reads.",
+                description: "Read a specific line range from a file under project_root (with strict size limits). Prefer this over Get-Content for deterministic reads. Returns development_warnings when the target is a huge implementation file.",
                 inputSchema: toJsonSchemaCompat(ReadFileLinesArgsSchema),
             },
             {
@@ -5064,7 +5807,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "query_codebase",
-                description: "Search the symbol index for class/function/type names (or substrings) to locate definitions by file path and signature. Use this when you need to find code—do not guess locations.",
+                description: "Search the symbol index for class/function/type names (or substrings) to locate definitions by file path and signature. Use this when you need to find code; do not guess locations. Returns development_warnings when matches point at huge implementation files.",
                 inputSchema: toJsonSchemaCompat(QueryCodebaseArgsSchema),
             },
             {
@@ -5118,6 +5861,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (toolName === "start_requirement") {
             const args = StartRequirementArgsSchema.parse(rawArgs);
             flushPendingChangeBuffer();
+            const scope_contract = buildRequirementScopeContract({
+                title: args.title,
+                background: args.background,
+                scope_allow: args.scope_allow,
+                scope_deny: args.scope_deny,
+                allowed_paths: args.allowed_paths,
+                denied_paths: args.denied_paths,
+            });
+            const development_warnings = buildRequirementStartWarnings({
+                title: args.title,
+                background: args.background,
+                close_previous: args.close_previous,
+            });
             if (args.close_previous) {
                 try {
                     completeAllActiveRequirementsStmt.run();
@@ -5131,13 +5887,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const id = Number(info.lastInsertRowid);
             const background = args.background?.trim() ?? "";
             const content = background ? `${args.title}\n\n${background}` : args.title;
-            const memoryInfo = insertMemoryItemStmt.run("requirement", args.title, content, null, null, null, id, safeJson({ status: "active" }), sha256Hex(content));
+            const memoryInfo = insertMemoryItemStmt.run("requirement", args.title, content, null, null, null, id, safeJson({ status: "active", scope_contract }), sha256Hex(content));
             const memory_id = Number(memoryInfo.lastInsertRowid);
             enqueueEmbedding(memory_id);
             logActivity("start_requirement", {
                 req_id: id,
                 title: args.title,
                 closed_previous: args.close_previous,
+                scope_contract,
+                development_warnings: development_warnings.length,
             });
             return {
                 content: [
@@ -5148,6 +5906,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             requirement: { id, title: args.title },
                             memory_item: { id: memory_id },
                             closed_previous: args.close_previous,
+                            scope_contract,
+                            development_warnings,
                         }),
                     },
                 ],
@@ -5302,6 +6062,208 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        if (toolName === "preflight_change_scope") {
+            const args = PreflightChangeScopeArgsSchema.parse(rawArgs);
+            const changeMode = args.change_mode;
+            flushPendingChangeBuffer();
+            const files = (args.files ?? args.planned_files ?? []).filter((f) => typeof f === "string" && f.length > 0);
+            const active = getActiveRequirementStmt.get();
+            const explicitContract = buildRequirementScopeContract({
+                title: active?.title ?? "",
+                background: active?.context_data ?? "",
+                scope_allow: args.scope_allow,
+                scope_deny: args.scope_deny,
+                allowed_paths: args.allowed_paths,
+                denied_paths: args.denied_paths,
+            });
+            const fileInputs = files.map((file_path) => ({ file_path }));
+            const development_warnings = [
+                ...buildDevelopmentWarnings(fileInputs, { includeUnspecified: fileInputs.length === 0 }),
+                ...buildScopeDriftWarnings({
+                    requirement: active,
+                    contract: explicitContract,
+                    intent: args.intent,
+                    files: fileInputs,
+                    includeMissingContractHint: true,
+                }),
+            ];
+            const scope_contract = mergeScopeContracts(active ? getRequirementScopeContract(active.id) : null, explicitContract);
+            logActivity("preflight_change_scope", {
+                req_id: active?.id ?? null,
+                intent_preview: makePreviewText(args.intent, 200),
+                change_mode: changeMode,
+                files: files.slice(0, 25),
+                files_total: files.length,
+                development_warnings: development_warnings.length,
+            });
+            const hasTargetFiles = fileInputs.length > 0;
+            const hugeWarnings = development_warnings.filter((w) => w.code === "huge_file_modularization_required");
+            const hasHugeFile = hugeWarnings.length > 0;
+            const blockingWarnings = development_warnings.filter((w) => isDevelopmentWarningBlockingForChangeMode(w, changeMode));
+            const hasBlockingWarnings = blockingWarnings.length > 0;
+            const safeToEdit = hasTargetFiles && !hasBlockingWarnings;
+            const recommendedAction = !hasTargetFiles
+                ? "Identify the intended target files/modules and rerun preflight_change_scope before editing."
+                : hasHugeFile && changeMode === "mechanical_modularization" && safeToEdit
+                    ? "Proceed only with mechanical modularization: call plan_large_file_split, move whole declarations into real named modules/directories, avoid generated/parts files, validate, then record_large_file_split."
+                    : hasHugeFile && changeMode === "emergency_hotfix" && safeToEdit
+                        ? "Proceed only with the smallest urgent fix, do not add new responsibilities, record why mechanical modularization was deferred, and plan/record the split next."
+                        : hasHugeFile
+                            ? "Stop normal feature work. Call plan_large_file_split and perform mechanical modularization first, or rerun preflight_change_scope with change_mode='mechanical_modularization' for the split itself."
+                            : hasBlockingWarnings
+                                ? "Stop before editing. Narrow the planned files or explicitly expand the current requirement/scope contract."
+                                : "Planned files are within the current generic scope checks.";
+            const requiredAction = hasHugeFile && changeMode !== "mechanical_modularization"
+                ? "mechanical_modularization"
+                : undefined;
+            const allowedChangeModes = hasHugeFile
+                ? ["mechanical_modularization", "emergency_hotfix"]
+                : undefined;
+            const outputValue = {
+                ok: safeToEdit,
+                safe_to_edit: safeToEdit,
+                change_mode: changeMode,
+                recommended_action: recommendedAction,
+                required_action: requiredAction,
+                allowed_change_modes: allowedChangeModes,
+                active_requirement: active ? { id: active.id, title: active.title } : null,
+                intent: args.intent,
+                files: files.map(normalizeToDbPath),
+                scope_contract,
+                development_warnings,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolCompactOrJson("preflight_change_scope", outputValue, compactPreflightChangeScopeText(outputValue), args.format),
+                    },
+                ],
+            };
+        }
+        if (toolName === "plan_large_file_split") {
+            const args = PlanLargeFileSplitArgsSchema.parse(rawArgs);
+            flushPendingChangeBuffer();
+            const resolved = resolveReadPathUnderProjectRoot(args.file);
+            let stat;
+            try {
+                stat = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) }],
+                };
+            }
+            if (!stat.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            if (!isLikelySourceImplementationFile(resolved.dbFilePath)) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                error: "Not a recognized source implementation file",
+                                file_path: resolved.dbFilePath,
+                            }),
+                        },
+                    ],
+                };
+            }
+            const lineInfo = countFileLinesBounded(resolved.absPath, 8_000_000);
+            const lineCount = lineInfo?.lines ?? 0;
+            if (lineCount < DEVELOPMENT_HUGE_FILE_LINES) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                file_path: resolved.dbFilePath,
+                                line_count: lineInfo?.truncated ? `${lineCount}+` : lineCount,
+                                huge_threshold_lines: DEVELOPMENT_HUGE_FILE_LINES,
+                                recommended_action: "This file is not above the huge-file threshold. Use normal focused modularity rules unless the user explicitly asked for refactoring.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            let targetDir = args.target_dir;
+            if (targetDir) {
+                targetDir = resolveProjectPathUnderRoot(targetDir, { allowRoot: true }).dbFilePath;
+            }
+            const plan = buildLargeFileSplitPlan({
+                filePath: resolved.dbFilePath,
+                absPath: resolved.absPath,
+                intent: args.intent,
+                targetDir,
+                maxModules: args.max_modules,
+            });
+            logActivity("plan_large_file_split", {
+                file_path: plan.file_path,
+                line_count: plan.line_count,
+                target_dir: plan.target_dir,
+                modules: plan.modules.map((m) => m.module),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolCompactOrJson("plan_large_file_split", plan, compactLargeFileSplitPlanText(plan), args.format),
+                    },
+                ],
+            };
+        }
+        if (toolName === "record_large_file_split") {
+            const args = RecordLargeFileSplitArgsSchema.parse(rawArgs);
+            flushPendingChangeBuffer();
+            const normalizedFile = normalizeToDbPath(args.file);
+            const active = getActiveRequirementStmt.get();
+            const modules = (args.modules ?? []).map(normalizeToDbPath);
+            const content = [
+                `Huge-file mechanical modularization ${args.status}: ${normalizedFile}`,
+                "",
+                args.summary,
+                modules.length ? `\nModules:\n${modules.map((m) => `- ${m}`).join("\n")}` : "",
+                args.remaining_lines != null ? `\nRemaining lines: ${args.remaining_lines}` : "",
+            ].filter(Boolean).join("\n");
+            const meta = {
+                tags: ["large-file-split", "mechanical-modularization"],
+                file: normalizedFile,
+                status: args.status,
+                modules,
+                remaining_lines: args.remaining_lines ?? null,
+                active_requirement_id: active?.id ?? null,
+            };
+            const info = insertMemoryItemStmt.run("note", `large-file-split:${normalizedFile}:${args.status}`, content, normalizedFile, null, null, active?.id ?? null, safeJson(meta), sha256Hex(content));
+            const id = Number(info.lastInsertRowid);
+            enqueueEmbedding(id);
+            logActivity("record_large_file_split", {
+                memory_item_id: id,
+                file_path: normalizedFile,
+                status: args.status,
+                modules: modules.slice(0, 20),
+                remaining_lines: args.remaining_lines ?? null,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            note: { id },
+                            file_path: normalizedFile,
+                            status: args.status,
+                            modules,
+                            remaining_lines: args.remaining_lines ?? null,
+                        }),
+                    },
+                ],
+            };
+        }
         if (toolName === "sync_change_intent") {
             const args = SyncChangeIntentArgsSchema.parse(rawArgs);
             flushPendingChangeBuffer();
@@ -5386,12 +6348,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
             });
             insertTx();
+            const development_warnings = [
+                ...buildDevelopmentWarnings(synced_files, {
+                    includeUnspecified: synced_files.some((f) => f.file_path === "(unspecified)"),
+                }),
+                ...buildScopeDriftWarnings({
+                    requirement: active,
+                    intent: args.intent,
+                    files: synced_files,
+                }),
+            ];
             logActivity("sync_change_intent", {
                 req_id: active.id,
                 title: active.title,
                 intent_preview: makePreviewText(args.intent, 200),
                 files: synced_files.slice(0, 25),
                 files_total: synced_files.length,
+                development_warnings: development_warnings.length,
             });
             return {
                 content: [
@@ -5402,6 +6375,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             linked_to_requirement: { id: active.id, title: active.title },
                             synced_files,
                             created,
+                            development_warnings,
                         }),
                     },
                 ],
@@ -5442,6 +6416,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const pending_total = mergedPending.total;
             const pending_truncated = mergedPending.truncated;
             const pending_changes = mergedPending.page;
+            const activeForScope = getActiveRequirementStmt.get();
+            const development_warnings = [
+                ...buildDevelopmentWarnings(pending_changes),
+                ...(activeForScope
+                    ? buildScopeDriftWarnings({ requirement: activeForScope, files: pending_changes })
+                    : []),
+            ];
             const q = args.query?.trim() ?? "";
             const semanticKinds = args.kinds?.length ? args.kinds : BOOTSTRAP_DEFAULT_CONTEXT_KINDS;
             const semantic = q
@@ -5506,6 +6487,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 pending_limit,
                 pending_truncated,
                 pending_changes,
+                development_warnings,
                 items,
                 semantic,
             };
@@ -5553,6 +6535,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const pending_total = mergedPending.total;
             const pending_truncated = mergedPending.truncated;
             const pending_changes = mergedPending.page;
+            const activeForScope = getActiveRequirementStmt.get();
+            const development_warnings = [
+                ...buildDevelopmentWarnings(pending_changes),
+                ...(activeForScope
+                    ? buildScopeDriftWarnings({ requirement: activeForScope, files: pending_changes })
+                    : []),
+            ];
             logActivity("get_brain_dump", {
                 pending_total,
                 pending_returned: pending_changes.length,
@@ -5597,6 +6586,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 pending_limit,
                 pending_truncated,
                 pending_changes,
+                development_warnings,
                 items,
                 semantic: null,
             };
@@ -5619,18 +6609,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const total = mergedPending.total;
             const truncated = mergedPending.truncated;
             const pending = mergedPending.page;
+            const activeForScope = getActiveRequirementStmt.get();
+            const development_warnings = [
+                ...buildDevelopmentWarnings(pending),
+                ...(activeForScope ? buildScopeDriftWarnings({ requirement: activeForScope, files: pending }) : []),
+            ];
             logActivity("get_pending_changes", {
                 total,
                 offset,
                 limit,
                 returned: pending.length,
                 truncated,
+                development_warnings: development_warnings.length,
             });
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({ ok: true, total, offset, limit, truncated, pending }),
+                        text: toolJson({ ok: true, total, offset, limit, truncated, pending, development_warnings }),
                     },
                 ],
             };
@@ -5821,6 +6817,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const includePaths = args.include_paths?.length ? args.include_paths : null;
             const excludePaths = args.exclude_paths?.length ? args.exclude_paths : null;
             const maxResults = args.max_results;
+            const development_warnings = [
+                ...buildCrossProjectPathWarnings(includePaths),
+                ...buildCrossProjectPathWarnings(excludePaths),
+            ];
             const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
             const ripgrepResult = runRipgrepSearch({
                 query: q,
@@ -5832,6 +6832,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 maxResults,
             });
             if (ripgrepResult.ok) {
+                const grepDevelopmentWarnings = [
+                    ...development_warnings,
+                    ...buildMatchedFileDevelopmentWarnings(ripgrepResult.matches.map((m) => m.file_path)),
+                ];
                 logActivity("grep", {
                     backend: ripgrepResult.backend,
                     rg_command: ripgrepResult.rg_command,
@@ -5844,6 +6848,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     matches: ripgrepResult.matches.length,
                     total_matches: ripgrepResult.total_matches,
                     truncated: ripgrepResult.truncated,
+                    development_warnings: grepDevelopmentWarnings.length,
                 });
                 const outputValue = {
                     ok: true,
@@ -5858,6 +6863,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     matches: ripgrepResult.matches,
                     total_matches: ripgrepResult.total_matches,
                     truncated: ripgrepResult.truncated,
+                    development_warnings: grepDevelopmentWarnings,
                 };
                 return {
                     content: [
@@ -5923,6 +6929,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            const grepDevelopmentWarnings = [
+                ...development_warnings,
+                ...buildMatchedFileDevelopmentWarnings(indexedResult.matches.map((m) => m.file_path)),
+            ];
             logActivity("grep", {
                 backend: indexedResult.backend,
                 fallback_reason: "ripgrep_unavailable",
@@ -5939,6 +6949,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 candidates_scanned: indexedResult.candidates.scanned,
                 matches: indexedResult.matches.length,
                 truncated: indexedResult.truncated,
+                development_warnings: grepDevelopmentWarnings.length,
             });
             const outputValue = {
                 ok: true,
@@ -5957,6 +6968,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 candidates: indexedResult.candidates,
                 matches: indexedResult.matches,
                 truncated: indexedResult.truncated,
+                development_warnings: grepDevelopmentWarnings,
             };
             return {
                 content: [
@@ -6076,6 +7088,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 total_chars: result.totalChars,
                 truncated: result.truncated,
             });
+            const development_warnings = buildFileReadDevelopmentWarnings(resolved.dbFilePath, resolved.absPath, st);
             const outputValue = {
                 ok: true,
                 file_path: resolved.dbFilePath,
@@ -6083,6 +7096,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 returned_chars: result.returnedChars,
                 total_chars: result.totalChars,
                 truncated: result.truncated,
+                development_warnings,
                 text: result.text,
             };
             return {
@@ -6212,6 +7226,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 returned: result.returned,
                 truncated: result.truncated,
             });
+            const development_warnings = buildFileReadDevelopmentWarnings(resolved.dbFilePath, resolved.absPath, st);
             const outputValue = {
                 ok: true,
                 file_path: resolved.dbFilePath,
@@ -6219,6 +7234,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 to_line: toLine,
                 returned: result.returned,
                 truncated: result.truncated,
+                development_warnings,
                 text: result.text,
             };
             return {
@@ -6237,12 +7253,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const like = `%${escaped}%`;
             const rows = searchSymbolsStmt.all(like, like, q, like, 250);
             const filtered = rows.filter((r) => !shouldIgnoreDbFilePath(r.file_path)).slice(0, 50);
+            const development_warnings = buildMatchedFileDevelopmentWarnings(filtered.map((m) => m.file_path));
             logActivity("query_codebase", {
                 query: q,
                 matches: filtered.length,
+                development_warnings: development_warnings.length,
                 sample: filtered.slice(0, 10).map((m) => ({ name: m.name, type: m.type, file_path: m.file_path })),
             });
-            const outputValue = { ok: true, query: q, matches: filtered };
+            const outputValue = { ok: true, query: q, matches: filtered, development_warnings };
             return {
                 content: [
                     {