cf-claw 3.0.5 → 3.0.7

package/dist/factory.js

@@ -1,6 +1,7 @@
 import Database from "better-sqlite3";
 import path from "node:path";
 import fs from "node:fs";
+import { execSync } from "node:child_process";
 import { chatCompletionWithFallback } from "./llm/index.js";
 import { getTool, tools } from "./tools/index.js";
 import { logUsage, estimateCost } from "./usage.js";
@@ -9,6 +10,7 @@ import { getAgent, listAgents } from "./agents.js";
 import { sendToTelegram } from "./bot.js";
 import { config } from "./config.js";
 import { getDataDir, getProjectsDir } from "./paths.js";
+import { docList, docRead } from "./documents.js";
 const DATA_DIR = getDataDir();
 const PROJECTS_DIR = getProjectsDir();
 const DB_PATH = path.join(DATA_DIR, "cf-claw.db");
@@ -58,7 +60,17 @@ const hasPhaseCol = taskTableInfo.some((c) => c.name === "phase");
 if (!hasPhaseCol) {
     db.exec("ALTER TABLE factory_tasks ADD COLUMN phase TEXT DEFAULT NULL");
 }
-const insertProject = db.prepare("INSERT INTO factory_projects (title, description, status) VALUES (?, ?, ?)");
+if (!projectTableInfo.some((c) => c.name === "source_type")) {
+    db.exec("ALTER TABLE factory_projects ADD COLUMN source_type TEXT DEFAULT 'scratch'");
+}
+if (!projectTableInfo.some((c) => c.name === "source_git_url")) {
+    db.exec("ALTER TABLE factory_projects ADD COLUMN source_git_url TEXT");
+}
+if (!projectTableInfo.some((c) => c.name === "source_branch")) {
+    db.exec("ALTER TABLE factory_projects ADD COLUMN source_branch TEXT");
+}
+const updateProjectSource = db.prepare("UPDATE factory_projects SET source_type = ?, source_git_url = ?, source_branch = ?, updated_at = datetime('now') WHERE id = ?");
+const insertProject = db.prepare("INSERT INTO factory_projects (title, description, status, source_type, source_git_url, source_branch) VALUES (?, ?, ?, ?, ?, ?)");
 const getProjectById = db.prepare("SELECT * FROM factory_projects WHERE id = ?");
 const getAllProjects = db.prepare("SELECT * FROM factory_projects ORDER BY updated_at DESC");
 const updateProjectStatus = db.prepare("UPDATE factory_projects SET status = ?, updated_at = datetime('now') WHERE id = ?");
@@ -200,7 +212,23 @@ function matchesArtifact(pattern, relPath) {
     }
     return toPathRegex(normalizedPattern).test(normalizedPath);
 }
-function validateWorkspaceAgainstContract(workspacePath, contract) {
+function checkDocumentStoreForArtifact(pattern) {
+    const docs = docList();
+    const normalizedPattern = pattern.replace(/\\/g, "/").trim().toLowerCase();
+    for (const doc of docs) {
+        const filenameLower = doc.filename.toLowerCase();
+        const titleLower = doc.title.toLowerCase();
+        const matchesFilename = matchesArtifact(normalizedPattern, filenameLower) ||
+            filenameLower.includes(normalizedPattern.replace(/\*/g, ""));
+        const matchesTitle = matchesArtifact(normalizedPattern, titleLower) ||
+            titleLower.includes(normalizedPattern.replace(/\*/g, ""));
+        if (matchesFilename || matchesTitle) {
+            return true;
+        }
+    }
+    return false;
+}
+function validateWorkspaceAgainstContract(workspacePath, contract, projectTitle) {
     if (!workspacePath || !contract) {
         return { ok: true, violations: [] };
     }
@@ -211,10 +239,14 @@ function validateWorkspaceAgainstContract(workspacePath, contract) {
     const files = collectFiles(workspaceAbs, 1200).map((f) => path.relative(workspaceAbs, f).replace(/\\/g, "/"));
     const violations = [];
     for (const required of contract.requiredArtifacts) {
-        const found = files.some((f) => matchesArtifact(required, f));
-        if (!found) {
-            violations.push(`Missing required artifact pattern: ${required}`);
+        const foundInFs = files.some((f) => matchesArtifact(required, f));
+        if (foundInFs)
+            continue;
+        if (checkDocumentStoreForArtifact(required)) {
+            console.log(`🏭 Artifact ${required} found in document store (not filesystem, but acceptable)`);
+            continue;
         }
+        violations.push(`Missing required artifact pattern: ${required}`);
     }
     for (const forbidden of contract.forbiddenArtifacts) {
         const matches = files.filter((f) => matchesArtifact(forbidden, f));
@@ -395,14 +427,17 @@ function rowToProject(row) {
         description: row.description || "",
         status: row.status,
         workspacePath,
+        sourceType: row.source_type || "scratch",
+        sourceGitUrl: row.source_git_url || null,
+        sourceBranch: row.source_branch || null,
         taskCount: counts?.total || 0,
         completedTasks: counts?.completed || 0,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
     };
 }
-export function createFactoryProject(title, description) {
-    const result = insertProject.run(title, description, "planning");
+export function createFactoryProject(title, description, sourceType = "scratch", sourceGitUrl = null, sourceBranch = null) {
+    const result = insertProject.run(title, description, "planning", sourceType, sourceGitUrl, sourceBranch);
     const projectId = Number(result.lastInsertRowid);
     const workspacePath = buildDefaultWorkspacePath(projectId, title);
     ensureWorkspaceDir(workspacePath);
@@ -433,7 +468,7 @@ export function getFactoryTask(taskId) {
 }
 export function forceRetryTask(taskId) {
     const task = getFactoryTask(taskId);
-    if (!task || task.status !== "human_intervention")
+    if (!task || (task.status !== "human_intervention" && task.status !== "failed"))
         return false;
     updateTaskRetry.run("backlog", 0, JSON.stringify({}), taskId);
     return true;
@@ -597,7 +632,7 @@ function scopeToolInput(toolName, rawArgs, workspacePath) {
         return rawArgs;
     const workspaceAbs = absoluteWorkspacePath(workspacePath);
     const scoped = { ...rawArgs };
-    const pathTools = new Set(["file_read", "file_write", "file_create", "file_delete", "file_list", "file_search"]);
+    const pathTools = new Set(["file_read", "file_write", "file_create", "file_delete", "file_list", "file_search", "doc_save"]);
     if (pathTools.has(toolName)) {
         const rawPath = typeof scoped.path === "string" ? scoped.path : ".";
         const normalizedInput = normalizeAgentRelativePath(rawPath, workspacePath);
@@ -670,7 +705,7 @@ async function runFactoryAgent(agentDef, task, contextPayload, maxIterations = 1
             })),
         });
         for (const tc of response.toolCalls) {
-            if (tc.name === "file_write" || tc.name === "file_create") {
+            if (tc.name === "file_write" || tc.name === "file_create" || tc.name === "doc_save") {
                 totalFileWriteCalls++;
             }
             const tool = getTool(tc.name);
@@ -741,6 +776,8 @@ Return ONLY a JSON object with:
 }`;
 const Stoffe_DECOMPOSE_PROMPT = `You are Stoffe, Systems Architect. Given Fredrix's product spec, break it into concrete technical tasks for the development team.
 
+IMPORTANT: You MUST save the architecture blueprint to a file called \`ARCHITECTURE.md\` in the project workspace using the file_create tool. The architecture must be written to disk, not just returned as text.
+
 Available agents:
 {agents}
 
@@ -844,6 +881,7 @@ function normalizeStageId(input) {
         security: "security-audit",
         "final review": "final-review",
         review: "code-review",
+        architecture: "blueprint",
     };
     return aliasMap[normalized] || normalized;
 }
@@ -1265,6 +1303,351 @@ export async function factoryCreate(description) {
         tasks: created,
     };
 }
+function enrichDescriptionFromWorkspace(workspacePath) {
+    const workspaceAbs = absoluteWorkspacePath(workspacePath);
+    if (!fs.existsSync(workspaceAbs))
+        return "";
+    const parts = [];
+    const appRoot = findLikelyAppRoot(workspaceAbs);
+    const { stack, scripts } = detectTechStack(appRoot);
+    if (stack.length > 0) {
+        parts.push(`Detected tech stack: ${stack.join(", ")}`);
+    }
+    const readmePath = path.join(workspaceAbs, "README.md");
+    if (fs.existsSync(readmePath)) {
+        try {
+            const readme = fs.readFileSync(readmePath, "utf-8").slice(0, 2000);
+            parts.push(`README excerpt:\n${readme}`);
+        }
+        catch { }
+    }
+    const pkgPath = path.join(appRoot, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+            if (pkg.name)
+                parts.push(`Package name: ${pkg.name}`);
+            if (pkg.description)
+                parts.push(`Package description: ${pkg.description}`);
+            if (pkg.scripts && Object.keys(pkg.scripts).length > 0) {
+                parts.push(`Available scripts: ${Object.keys(pkg.scripts).join(", ")}`);
+            }
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            const depNames = Object.keys(allDeps);
+            if (depNames.length > 0 && depNames.length <= 40) {
+                parts.push(`Dependencies: ${depNames.join(", ")}`);
+            }
+            else if (depNames.length > 40) {
+                parts.push(`Dependencies: ${depNames.length} packages`);
+            }
+        }
+        catch { }
+    }
+    const allFiles = collectFiles(workspaceAbs, 200);
+    const topLevel = new Set();
+    for (const f of allFiles) {
+        const rel = path.relative(workspaceAbs, f);
+        const topDir = rel.split(path.sep)[0];
+        if (topDir)
+            topLevel.add(topDir);
+    }
+    if (topLevel.size > 0) {
+        parts.push(`Top-level directories/files: ${[...topLevel].sort().join(", ")}`);
+    }
+    parts.push(`Total files scanned: ${allFiles.length}`);
+    return parts.join("\n\n");
+}
+const EXISTING_PROJECT_DECOMPOSE_PROMPT = `You are Stoffe, Systems Architect. You are analyzing an EXISTING codebase that has already been built. The user wants to make changes/additions to it.
+
+IMPORTANT: You MUST save the analysis to a file called \`ARCHITECTURE.md\` in the project workspace using the file_create tool.
+
+Available agents:
+{agents}
+
+User's request:
+{description}
+
+## EXISTING CODEBASE CONTEXT:
+{workspace_context}
+
+Available orchestration profiles:
+{profiles}
+
+## CODE AGENTS (for implementation/integration tasks):
+{code_agents}
+
+## QA AGENTS (for testing tasks):
+{qa_agents}
+
+## REVIEW AGENTS (for code review tasks):
+{review_agents}
+
+## SECURITY AGENTS (for security audit tasks):
+{security_agents}
+
+MANDATORY RULES:
+- This is an EXISTING project. Tasks must MODIFY or EXTEND existing files, not create from scratch.
+- Analyze the existing codebase structure before creating tasks.
+- Each implementation task must specify which existing files need to be modified.
+- Split implementation across MULTIPLE code agents when the work has distinct areas.
+- Assign reviewer_agent to every code task using a review/QA agent.
+- Include a QA Testing task that depends on ALL code tasks.
+- Include a Code Review task that depends on the QA task.
+
+Define dependencies between tasks (0-indexed task IDs).
+
+Provide a Mermaid flow diagram showing the task dependencies.
+
+Return ONLY JSON:
+{
+  "pipeline_profile": "one of the available profiles",
+  "tasks": [
+    {
+      "title": "Short task title",
+      "description": "Detailed description including which existing files to modify and what changes to make",
+      "assigned_agent": "agent_name_lowercase",
+      "reviewer_agent": "agent_name_lowercase" | null,
+      "dependencies": [0, 1],
+      "max_retries": 10,
+      "stage_id": "optional stage id",
+      "architecture_contract": {
+        "stack_type": "optional",
+        "language": "optional",
+        "required_artifacts": [],
+        "forbidden_artifacts": [],
+        "reviewer_focus": [],
+        "notes": "optional"
+      }
+    }
+  ]
+}`;
+async function decomposeExistingProject(description, workspaceContext) {
+    const agents = listAgents();
+    const agentList = agents
+        .map((a) => `- ${a.name} (${a.role}, team: ${a.team})`)
+        .join("\n");
+    const codeAgents = agents.filter((a) => isCodeAgent(a));
+    const qaAgents = agents.filter((a) => isQaAgent(a));
+    const reviewAgents = agents.filter((a) => isReviewAgent(a));
+    const securityAgents = agents.filter((a) => isSecurityAgent(a));
+    const suggestedProfile = resolveProjectProfile(description + " " + workspaceContext, null);
+    const formatAgentList = (list) => list.length > 0
+        ? list.map((a) => `- ${a.name} (${a.role})`).join("\n")
+        : "- (none available)";
+    const prompt = EXISTING_PROJECT_DECOMPOSE_PROMPT
+        .replace("{agents}", agentList)
+        .replace("{description}", description)
+        .replace("{workspace_context}", workspaceContext)
+        .replace("{profiles}", formatProfilesForPrompt())
+        .replace("{code_agents}", formatAgentList(codeAgents))
+        .replace("{qa_agents}", formatAgentList(qaAgents))
+        .replace("{review_agents}", formatAgentList(reviewAgents))
+        .replace("{security_agents}", formatAgentList(securityAgents));
+    console.log("🏭 Stoffe analyzing existing codebase...");
+    const stoffeAgent = getAgent("Stoffe");
+    const stoffeResponse = await chatCompletionWithFallback(stoffeAgent?.model || undefined, stoffeAgent?.fallbackModel || undefined, { messages: [{ role: "user", content: prompt }] });
+    const stoffeText = stoffeResponse.content?.trim() || "[]";
+    let rawTasks = [];
+    let stoffePipelineProfile = null;
+    const objectMatch = stoffeText.match(/\{[\s\S]*\}/);
+    if (objectMatch) {
+        const parsed = JSON.parse(objectMatch[0]);
+        if (typeof parsed.pipeline_profile === "string") {
+            stoffePipelineProfile = parsed.pipeline_profile;
+        }
+        if (Array.isArray(parsed.tasks)) {
+            rawTasks = parsed.tasks;
+        }
+    }
+    if (rawTasks.length === 0) {
+        const arrMatch = stoffeText.match(/\[[\s\S]*\]/);
+        if (!arrMatch)
+            throw new Error("Stoffe failed to produce valid JSON for existing project");
+        rawTasks = JSON.parse(arrMatch[0]);
+    }
+    const pipelineProfile = resolveProjectProfile(description, stoffePipelineProfile);
+    const validAgents = new Set(agents.map((a) => a.name.toLowerCase()));
+    const defaultSecurityReviewer = findAgentForStage("security-audit", agents, "sara");
+    const tasks = rawTasks.map((t) => {
+        const assigned = validAgents.has((t.assigned_agent || "").toLowerCase())
+            ? t.assigned_agent.toLowerCase()
+            : "chris";
+        let reviewer = t.reviewer_agent && validAgents.has(t.reviewer_agent.toLowerCase())
+            ? t.reviewer_agent.toLowerCase()
+            : null;
+        if (isSecuritySensitiveTask(t) && (!reviewer || reviewer !== defaultSecurityReviewer)) {
+            reviewer = defaultSecurityReviewer;
+        }
+        return {
+            title: t.title || "Untitled task",
+            description: t.description || "",
+            assigned_agent: assigned,
+            reviewer_agent: reviewer,
+            dependencies: Array.isArray(t.dependencies) ? t.dependencies : [],
+            max_retries: Number.isInteger(t.max_retries)
+                ? Math.max(1, Number(t.max_retries))
+                : DEFAULT_MAX_RETRIES,
+            stage_id: normalizeStageId(typeof t.stage_id === "string" ? t.stage_id : detectTaskStageId(t, agents)),
+            architecture_contract: normalizeArchitectureContract(t.architecture_contract),
+        };
+    });
+    return {
+        title: description.substring(0, 80).replace(/\n.*/g, "").trim() || "Existing Project",
+        tasks,
+        pipelineProfile,
+    };
+}
+export async function factoryCreateFromGit(gitUrl, branch, description) {
+    const repoName = gitUrl
+        .replace(/\.git$/, "")
+        .split("/")
+        .pop() || "git-project";
+    const title = description
+        ? description.substring(0, 80).replace(/\n.*/g, "").trim()
+        : repoName;
+    const project = createFactoryProject(title, description || `Cloned from ${gitUrl}`, "git", gitUrl, branch);
+    const workspacePath = project.workspacePath;
+    const workspaceAbs = absoluteWorkspacePath(workspacePath);
+    if (fs.existsSync(workspaceAbs)) {
+        fs.rmSync(workspaceAbs, { recursive: true, force: true });
+    }
+    const branchArg = branch ? ` --branch ${quoteForShell(branch)}` : "";
+    const cloneCmd = `git clone --depth 1${branchArg} ${quoteForShell(gitUrl)} ${quoteForShell(workspaceAbs)}`;
+    console.log(`🏭 Cloning ${gitUrl} into ${workspacePath}...`);
+    try {
+        execSync(cloneCmd, { stdio: "pipe", timeout: 120_000 });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        updateProjectStatus.run("failed", project.id);
+        throw new Error(`Git clone failed: ${msg}`);
+    }
+    const workspaceContext = enrichDescriptionFromWorkspace(workspacePath);
+    const enrichedDescription = description
+        ? `${description}\n\n--- Existing Codebase ---\n${workspaceContext}`
+        : `Modify/improve the existing codebase.\n\n--- Existing Codebase ---\n${workspaceContext}`;
+    const { title: decomposedTitle, tasks, pipelineProfile } = await decomposeExistingProject(enrichedDescription, workspaceContext);
+    if (decomposedTitle && decomposedTitle !== "Existing Project") {
+        db.prepare("UPDATE factory_projects SET title = ?, updated_at = datetime('now') WHERE id = ?").run(decomposedTitle, project.id);
+    }
+    const allAgents = listAgents();
+    const profile = resolveProjectProfile(enrichedDescription, pipelineProfile);
+    const patchedTasks = injectMissingStages(tasks, profile, allAgents);
+    const projectId = project.id;
+    const taskMap = new Map();
+    for (let i = 0; i < patchedTasks.length; i++) {
+        const t = patchedTasks[i];
+        const phase = AGENT_PHASES[t.assigned_agent?.toLowerCase()] || null;
+        const contextPayload = {
+            ...(t.architecture_contract ? { architecture_contract: t.architecture_contract } : {}),
+            ...(t.stage_id ? { stage_id: t.stage_id } : {}),
+            pipeline_profile: profile,
+            is_existing_project: true,
+        };
+        const result = insertTask.run(projectId, t.title, t.description, t.assigned_agent, t.reviewer_agent || null, "[]", t.max_retries, JSON.stringify(contextPayload), phase);
+        taskMap.set(i, Number(result.lastInsertRowid));
+    }
+    for (let i = 0; i < patchedTasks.length; i++) {
+        const taskId = taskMap.get(i);
+        if (!taskId)
+            continue;
+        const mappedDependencies = (Array.isArray(patchedTasks[i].dependencies) ? patchedTasks[i].dependencies : [])
+            .map((depIdx) => {
+            if (typeof depIdx !== "number" || !Number.isInteger(depIdx))
+                return null;
+            return taskMap.get(depIdx) ?? null;
+        })
+            .filter((depId) => depId !== null);
+        updateTaskDependencies.run(JSON.stringify(mappedDependencies), taskId);
+    }
+    const created = getFactoryTasks(projectId);
+    updateProjectStatus.run("running", projectId);
+    const updatedRow = getProjectById.get(projectId);
+    return {
+        project: rowToProject(updatedRow),
+        tasks: created,
+    };
+}
+export async function factoryCreateFromLocal(localPath, description) {
+    const absLocalPath = path.resolve(localPath);
+    if (!fs.existsSync(absLocalPath)) {
+        throw new Error(`Local path does not exist: ${localPath}`);
+    }
+    const dirName = path.basename(absLocalPath);
+    const title = description
+        ? description.substring(0, 80).replace(/\n.*/g, "").trim()
+        : dirName;
+    const project = createFactoryProject(title, description || `Imported from ${localPath}`, "local", null, null);
+    const workspacePath = project.workspacePath;
+    const workspaceAbs = absoluteWorkspacePath(workspacePath);
+    if (fs.existsSync(workspaceAbs)) {
+        fs.rmSync(workspaceAbs, { recursive: true, force: true });
+    }
+    console.log(`🏭 Copying ${localPath} into ${workspacePath}...`);
+    copyDirFiltered(absLocalPath, workspaceAbs);
+    const workspaceContext = enrichDescriptionFromWorkspace(workspacePath);
+    const enrichedDescription = description
+        ? `${description}\n\n--- Existing Codebase ---\n${workspaceContext}`
+        : `Modify/improve the existing codebase.\n\n--- Existing Codebase ---\n${workspaceContext}`;
+    const { title: decomposedTitle, tasks, pipelineProfile } = await decomposeExistingProject(enrichedDescription, workspaceContext);
+    if (decomposedTitle && decomposedTitle !== "Existing Project") {
+        db.prepare("UPDATE factory_projects SET title = ?, updated_at = datetime('now') WHERE id = ?").run(decomposedTitle, project.id);
+    }
+    const allAgents = listAgents();
+    const profile = resolveProjectProfile(enrichedDescription, pipelineProfile);
+    const patchedTasks = injectMissingStages(tasks, profile, allAgents);
+    const projectId = project.id;
+    const taskMap = new Map();
+    for (let i = 0; i < patchedTasks.length; i++) {
+        const t = patchedTasks[i];
+        const phase = AGENT_PHASES[t.assigned_agent?.toLowerCase()] || null;
+        const contextPayload = {
+            ...(t.architecture_contract ? { architecture_contract: t.architecture_contract } : {}),
+            ...(t.stage_id ? { stage_id: t.stage_id } : {}),
+            pipeline_profile: profile,
+            is_existing_project: true,
+        };
+        const result = insertTask.run(projectId, t.title, t.description, t.assigned_agent, t.reviewer_agent || null, "[]", t.max_retries, JSON.stringify(contextPayload), phase);
+        taskMap.set(i, Number(result.lastInsertRowid));
+    }
+    for (let i = 0; i < patchedTasks.length; i++) {
+        const taskId = taskMap.get(i);
+        if (!taskId)
+            continue;
+        const mappedDependencies = (Array.isArray(patchedTasks[i].dependencies) ? patchedTasks[i].dependencies : [])
+            .map((depIdx) => {
+            if (typeof depIdx !== "number" || !Number.isInteger(depIdx))
+                return null;
+            return taskMap.get(depIdx) ?? null;
+        })
+            .filter((depId) => depId !== null);
+        updateTaskDependencies.run(JSON.stringify(mappedDependencies), taskId);
+    }
+    const created = getFactoryTasks(projectId);
+    updateProjectStatus.run("running", projectId);
+    const updatedRow = getProjectById.get(projectId);
+    return {
+        project: rowToProject(updatedRow),
+        tasks: created,
+    };
+}
+function copyDirFiltered(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    const skip = new Set(["node_modules", ".git", "dist", ".next", "__pycache__", ".cache", "coverage"]);
+    for (const entry of entries) {
+        if (skip.has(entry.name))
+            continue;
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirFiltered(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
 function areDependenciesMet(task, allTasks) {
     if (task.dependencies.length === 0)
         return true;
@@ -1273,13 +1656,41 @@ function areDependenciesMet(task, allTasks) {
         return dep && dep.status === "done";
     });
 }
-function buildContextFromDeps(task, allTasks) {
+function buildContextFromDeps(task, allTasks, projectTitle) {
     const context = {};
+    const projectLower = (projectTitle || "").toLowerCase();
     for (const depId of task.dependencies) {
         const dep = allTasks.find((t) => t.id === depId);
         if (dep && dep.result) {
             context[`${dep.title} (${dep.assignedAgent})`] = dep.result;
         }
+        if (dep) {
+            const docs = docList();
+            const depTitleLower = (dep.title || "").toLowerCase();
+            const relatedDocs = [];
+            for (const doc of docs) {
+                const docTitleLower = doc.title.toLowerCase();
+                const docFilenameLower = doc.filename.toLowerCase();
+                const docCategoryLower = (doc.category || "").toLowerCase();
+                const docTagsLower = (doc.tags || []).join(" ").toLowerCase();
+                const matchesDep = docTitleLower.includes(depTitleLower) ||
+                    docFilenameLower.includes(depTitleLower.split(" ").slice(0, 2).join("_")) ||
+                    docFilenameLower.includes(depTitleLower.split(" ").join("-"));
+                const matchesProject = projectLower &&
+                    (docCategoryLower.includes(projectLower) ||
+                        docTagsLower.includes(projectLower) ||
+                        docFilenameLower.includes(projectLower.replace(/\s+/g, "-")));
+                if (matchesDep && (matchesProject || !projectLower)) {
+                    const content = docRead(doc.id);
+                    if (content) {
+                        relatedDocs.push({ filename: doc.filename, content });
+                    }
+                }
+            }
+            if (relatedDocs.length > 0) {
+                context[`${dep.title} (${dep.assignedAgent}) - Documents`] = relatedDocs;
+            }
+        }
     }
     return context;
 }
@@ -1419,7 +1830,7 @@ async function executeTask(task, allTasks) {
     const project = getFactoryProject(task.projectId);
     const workspacePath = project?.workspacePath || null;
     setTaskStarted.run(task.id);
-    const context = buildContextFromDeps(task, allTasks);
+    const context = buildContextFromDeps(task, allTasks, project?.title);
     const mergedContext = { ...task.contextPayload, ...context };
     const contract = resolveTaskArchitectureContract(task, mergedContext);
     if (contract) {
@@ -1441,7 +1852,11 @@ async function executeTask(task, allTasks) {
     const agentDef = agentChoice.forceFallbackModel && chosenAgent.fallbackModel
         ? { ...chosenAgent, model: chosenAgent.fallbackModel, fallbackModel: undefined }
         : chosenAgent;
-    const needsCodeOutput = /\b(implement|build|scaffold|frontend|backend|api|ui|dom|component|code|create)\b/i.test(`${task.title} ${task.description}`) && !/\b(specification|diagram|flow|review|audit|document)\b/i.test(`${task.title} ${task.description}`);
+    const stageId = normalizeStageId(typeof task.contextPayload?.stage_id === "string" ? task.contextPayload.stage_id : null);
+    const stageRequiresCodeOutput = stageId === "blueprint" || stageId === "ui-ux-design" || stageId === "implementation" || stageId === "integration";
+    const keywordRequiresCode = /\b(implement|build|scaffold|frontend|backend|api|ui|dom|component|code|create)\b/i.test(`${task.title} ${task.description}`);
+    const keywordExcludesCode = /\b(specification|diagram|flow|review|audit|document)\b/i.test(`${task.title} ${task.description}`);
+    const needsCodeOutput = (stageRequiresCodeOutput || keywordRequiresCode) && !keywordExcludesCode;
     const codeDeliveryGuard = needsCodeOutput
         ? "\n\n## Delivery requirement\nYou must produce real code changes in the project workspace using file_write and/or file_create. Descriptions without actual file operations are invalid."
         : "";
@@ -1477,28 +1892,30 @@ async function executeTask(task, allTasks) {
             }
             return;
         }
-        const contractValidation = validateWorkspaceAgainstContract(workspacePath, contract);
-        if (!contractValidation.ok) {
-            const newRetryCount = task.retryCount + 1;
-            const problem = contractValidation.violations.join("\n");
-            const bounce = buildBounceFeedback("system", chosenAgent.name, "Output violates architecture contract", newRetryCount, problem, "Bring workspace artifacts in line with the architecture contract before resubmitting.");
-            const newContext = {
-                ...mergedContext,
-                latest_review_feedback: bounce,
-                [`review_feedback_attempt_${newRetryCount}`]: bounce,
-            };
-            if (newRetryCount >= task.maxRetries) {
-                updateTaskResult.run("human_intervention", run.content, JSON.stringify(newContext), task.id);
-                console.log(`🏭 Task ${task.id} hit max retries (${newRetryCount}) after contract validation failure → human_intervention`);
-                if (project) {
-                    await notifyHumanIntervention(task, project);
+        if (needsCodeOutput) {
+            const contractValidation = validateWorkspaceAgainstContract(workspacePath, contract, project?.title);
+            if (!contractValidation.ok) {
+                const newRetryCount = task.retryCount + 1;
+                const problem = contractValidation.violations.join("\n");
+                const bounce = buildBounceFeedback("system", chosenAgent.name, "Output violates architecture contract", newRetryCount, problem, "Bring workspace artifacts in line with the architecture contract before resubmitting.");
+                const newContext = {
+                    ...mergedContext,
+                    latest_review_feedback: bounce,
+                    [`review_feedback_attempt_${newRetryCount}`]: bounce,
+                };
+                if (newRetryCount >= task.maxRetries) {
+                    updateTaskResult.run("human_intervention", run.content, JSON.stringify(newContext), task.id);
+                    console.log(`🏭 Task ${task.id} hit max retries (${newRetryCount}) after contract validation failure → human_intervention`);
+                    if (project) {
+                        await notifyHumanIntervention(task, project);
+                    }
                 }
+                else {
+                    updateTaskRetry.run("backlog", newRetryCount, JSON.stringify(newContext), task.id);
+                    console.log(`🏭 Task ${task.id} failed contract validation → retry ${newRetryCount}/${task.maxRetries}`);
+                }
+                return;
             }
-            else {
-                updateTaskRetry.run("backlog", newRetryCount, JSON.stringify(newContext), task.id);
-                console.log(`🏭 Task ${task.id} failed contract validation → retry ${newRetryCount}/${task.maxRetries}`);
-            }
-            return;
         }
         updateTaskResult.run("review", run.content, JSON.stringify(mergedContext), task.id);
         console.log(`🏭 Task ${task.id} completed → review`);