@coreyuan/vector-mind 1.0.44 → 1.0.48

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.48";
 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,42 @@ 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_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 +1420,416 @@ 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 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({
+        code: "large_file_read",
+        severity: tooManyLines ? "blocker" : "warning",
+        message: tooManyLines
+            ? "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."
+            : "You are reading a large implementation file. Keep the target narrow and prefer extracting focused modules before adding responsibilities.",
+        files: [filePath],
+        details: {
+            lines: lineInfo?.truncated ? `${lineCount}+` : lineCount,
+            bytes: st.size,
+            warn_lines: DEVELOPMENT_WARN_FILE_LINES,
+            block_lines: DEVELOPMENT_BLOCK_FILE_LINES,
+            warn_bytes: DEVELOPMENT_WARN_FILE_BYTES,
+        },
+    });
+    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({
+            code: tooManyLines ? "very_large_file" : "large_file",
+            severity: tooManyLines ? "blocker" : "warning",
+            message: tooManyLines
+                ? "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."
+                : "This implementation file is getting large. Prefer extracting focused modules instead of continuing to pile unrelated responsibilities into it.",
+            files: [relPath],
+            details: {
+                lines: lineInfo?.truncated ? `${lineCount}+` : lineCount,
+                bytes: stat.size,
+                warn_lines: DEVELOPMENT_WARN_FILE_LINES,
+                block_lines: DEVELOPMENT_BLOCK_FILE_LINES,
+                warn_bytes: DEVELOPMENT_WARN_FILE_BYTES,
+            },
+        });
+    }
+    return warnings;
+}
+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")
@@ -1744,12 +2190,25 @@ 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(),
+    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 QueryCodebaseArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     query: z.string().min(1),
 }));
@@ -2079,6 +2538,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 +2568,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 +2614,20 @@ 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} requirement=${req} files=${data.files.length} intent="${oneLine(data.intent, 120)}"`,
+        `action: ${oneLine(data.recommended_action, 180)}`,
+    ];
+    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 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 +2652,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 +4763,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 +4796,12 @@ 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.",
         "- 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 +5460,19 @@ 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.",
+                inputSchema: toJsonSchemaCompat(PreflightChangeScopeArgsSchema),
+            },
             {
                 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 +5480,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 +5530,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 +5545,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 +5555,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 +5609,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 +5635,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 +5654,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 +5810,65 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        if (toolName === "preflight_change_scope") {
+            const args = PreflightChangeScopeArgsSchema.parse(rawArgs);
+            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),
+                files: files.slice(0, 25),
+                files_total: files.length,
+                development_warnings: development_warnings.length,
+            });
+            const hasTargetFiles = fileInputs.length > 0;
+            const hasBlockingWarnings = development_warnings.some((w) => w.severity === "blocker" || w.severity === "warning");
+            const safeToEdit = hasTargetFiles && !hasBlockingWarnings;
+            const recommendedAction = !hasTargetFiles
+                ? "Identify the intended target files/modules and rerun preflight_change_scope before editing."
+                : 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 outputValue = {
+                ok: safeToEdit,
+                safe_to_edit: safeToEdit,
+                recommended_action: recommendedAction,
+                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 === "sync_change_intent") {
             const args = SyncChangeIntentArgsSchema.parse(rawArgs);
             flushPendingChangeBuffer();
@@ -5386,12 +5953,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 +5980,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             linked_to_requirement: { id: active.id, title: active.title },
                             synced_files,
                             created,
+                            development_warnings,
                         }),
                     },
                 ],
@@ -5442,6 +6021,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 +6092,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 pending_limit,
                 pending_truncated,
                 pending_changes,
+                development_warnings,
                 items,
                 semantic,
             };
@@ -5553,6 +6140,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 +6191,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 pending_limit,
                 pending_truncated,
                 pending_changes,
+                development_warnings,
                 items,
                 semantic: null,
             };
@@ -5619,18 +6214,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 +6422,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 +6437,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 +6453,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 +6468,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     matches: ripgrepResult.matches,
                     total_matches: ripgrepResult.total_matches,
                     truncated: ripgrepResult.truncated,
+                    development_warnings: grepDevelopmentWarnings,
                 };
                 return {
                     content: [
@@ -5923,6 +6534,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 +6554,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 +6573,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 candidates: indexedResult.candidates,
                 matches: indexedResult.matches,
                 truncated: indexedResult.truncated,
+                development_warnings: grepDevelopmentWarnings,
             };
             return {
                 content: [
@@ -6076,6 +6693,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 +6701,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 +6831,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 +6839,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 to_line: toLine,
                 returned: result.returned,
                 truncated: result.truncated,
+                development_warnings,
                 text: result.text,
             };
             return {
@@ -6237,12 +6858,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: [
                     {