agent-project-sdlc 0.1.9 → 0.1.11

package/dist/lib/validators.js

@@ -6,13 +6,38 @@ import { listFiles, pathExists, readText } from "./fs.js";
 import { parseYaml } from "./yaml.js";
 const execFileAsync = promisify(execFile);
 const PARALLEL_MODES = new Set(["runtime_managed", "user_orchestrated"]);
-const PARALLEL_PHASES = new Set(["REQUIREMENT_GATHERING", "SPRINTING", "TESTING"]);
+const TASK_PHASES = new Set(["REQUIREMENT_GATHERING", "ARCHITECTING", "SPRINTING", "REVIEWING", "TESTING", "RELEASING", "RFC_RECALIBRATION"]);
+const PARALLEL_ALLOWED_PHASES = new Set(["REQUIREMENT_GATHERING", "SPRINTING", "TESTING"]);
+const TASK_STATUSES = new Set(["pending", "in_progress", "done", "blocked", "pending_revision", "cancelled"]);
+const OPEN_TASK_STATUSES = new Set(["pending", "in_progress", "blocked", "pending_revision"]);
+const DESIGN_CATEGORIES = [
+    {
+        label: "AI copilot/provider",
+        triggerTerms: ["ai provider", "ai output", "aioutput", "llm", "copilot", "副驾驶"],
+        architectureTerms: ["ai provider", "ai output", "llm", "copilot", "副驾驶", "模型", "智能", "prompt"]
+    },
+    {
+        label: "external system boundary",
+        triggerTerms: ["external system", "external integration", "webhook", "外部系统", "第三方", "微信", "工商", "税务", "社保", "公积金", "金蝶", "对象存储"],
+        architectureTerms: ["external system", "external integration", "webhook", "adapter", "适配", "边界", "外部系统", "第三方", "微信", "工商", "税务", "社保", "公积金", "金蝶", "对象存储"]
+    },
+    {
+        label: "compliance/permission/audit",
+        triggerTerms: ["compliance", "authorization", "audit log", "audit trail", "合规", "授权", "客户确认", "回执归档", "权限模型", "权限控制", "权限架构", "审计架构", "审计日志"],
+        architectureTerms: ["compliance", "permission", "authorization", "audit", "合规", "权限", "审计", "授权", "客户确认", "回执归档"]
+    }
+];
 const validators = {
     "validate-harness": validateHarness,
     "validate-current": validateCurrent,
+    "validate-plan": validatePlan,
     "validate-pm": validatePm,
     "validate-design": validateDesign,
-    "validate-dev": validateDev
+    "validate-dev": validateDev,
+    "validate-review": validateReview,
+    "validate-test": validateTest,
+    "validate-release": validateRelease,
+    "validate-rfc": validateRfc
 };
 export async function runValidator(projectRoot, gate) {
     const normalized = normalizeGate(gate);
@@ -51,14 +76,19 @@ async function validateCurrent(projectRoot) {
     const gateByPhase = {
         REQUIREMENT_GATHERING: "validate-pm",
         ARCHITECTING: "validate-design",
-        SPRINTING: "validate-dev"
+        SPRINTING: "validate-dev",
+        REVIEWING: "validate-review",
+        TESTING: "validate-test",
+        RELEASING: "validate-release",
+        RFC_RECALIBRATION: "validate-rfc"
     };
     return runValidator(projectRoot, gateByPhase[current] ?? "validate-harness");
 }
 async function validatePm(projectRoot) {
+    const plan = await validatePlanState(projectRoot, false);
     const docs = await markdownFiles(path.join(projectRoot, ".docs/01_product"));
     const text = await combinedText(docs);
-    const errors = [];
+    const errors = [...plan.errors];
     if (docs.length === 0)
         errors.push("No PRD deliverables found");
     if (!containsAny(text, ["acceptance", "验收"]))
@@ -70,10 +100,14 @@ async function validatePm(projectRoot) {
     return { info: [`validate-pm checked ${docs.length} file(s)`], errors };
 }
 async function validateDesign(projectRoot) {
+    const root = await harnessRoot(projectRoot);
+    const lifecycle = await readYamlObject(path.join(projectRoot, root, "state", "lifecycle.yaml"));
+    const plan = await validatePlanState(projectRoot, String(lifecycle.current_phase ?? "") !== "ARCHITECTING");
     const architecture = await markdownFiles(path.join(projectRoot, ".docs/02_architecture"));
     const techPlan = await markdownFiles(path.join(projectRoot, ".docs/03_tech_plan"));
+    const product = await markdownFiles(path.join(projectRoot, ".docs/01_product"));
     const text = await combinedText([...architecture, ...techPlan]);
-    const errors = [];
+    const errors = [...plan.errors];
     if (architecture.length === 0)
         errors.push("No architecture deliverables found");
     if (techPlan.length === 0)
@@ -84,29 +118,264 @@ async function validateDesign(projectRoot) {
         errors.push("Design must describe interfaces or contracts");
     if (!containsAny(text, ["task", "任务", "breakdown"]))
         errors.push("Design must include task breakdown");
+    const draft = await validateDesignDraft(projectRoot, root, techPlan);
+    errors.push(...draft.errors);
+    errors.push(...(await validateCrossCuttingArchitecture(projectRoot, product, techPlan, architecture, draft.tasks)));
     return { info: [`validate-design checked ${architecture.length + techPlan.length} file(s)`], errors };
 }
+async function validatePlan(projectRoot) {
+    const plan = await validatePlanState(projectRoot, true);
+    const pathErrors = await validateChangedPaths(projectRoot, plan.plan, true);
+    return { info: [`validate-plan checked ${plan.taskCount} task(s)`], errors: [...plan.errors, ...pathErrors] };
+}
+async function validateDesignDraft(projectRoot, root, techPlanFiles) {
+    const errors = [];
+    const draft = await readYamlObject(path.join(projectRoot, root, "state", "plan.draft.yaml"));
+    if ("current_phase" in draft) {
+        errors.push("plan.draft.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase");
+    }
+    if ("current_task_id" in draft) {
+        errors.push("plan.draft.yaml must not define current_task_id because drafts are not active task state");
+    }
+    const rawTasks = draft.tasks;
+    if (!Array.isArray(rawTasks) || rawTasks.length === 0) {
+        errors.push("plan.draft.yaml must contain at least one task before leaving ARCHITECTING");
+        return { errors, tasks: [] };
+    }
+    const tasks = rawTasks.filter(isRecord);
+    const availableTechPlans = new Set(techPlanFiles.map((file) => repoRelative(projectRoot, file)));
+    const developmentTasks = [];
+    const primaryRefs = [];
+    rawTasks.forEach((rawTask, index) => {
+        if (!isRecord(rawTask)) {
+            errors.push(`Task draft #${index + 1} must be a mapping`);
+            return;
+        }
+        validateDraftTaskShape(rawTask, index, errors);
+        if (rawTask.status !== "pending") {
+            errors.push(`Draft task ${String(rawTask.id ?? "")} should start as pending`);
+        }
+        if (!isDevelopmentDraft(rawTask))
+            return;
+        developmentTasks.push(rawTask);
+        if (!isRecord(rawTask.docs)) {
+            errors.push(`Draft task ${String(rawTask.id ?? "")} docs must be a mapping`);
+            return;
+        }
+        const techRefs = asStringList(rawTask.docs.tech_plan);
+        if (techRefs.length === 0) {
+            errors.push(`Draft task ${String(rawTask.id ?? "")} must reference at least one tech plan slice in docs.tech_plan`);
+            return;
+        }
+        const normalizedRefs = techRefs.map(normalizeDocRef);
+        for (const ref of normalizedRefs) {
+            if (!ref.startsWith(".docs/03_tech_plan/")) {
+                errors.push(`Draft task ${String(rawTask.id ?? "")} docs.tech_plan must point into .docs/03_tech_plan/: ${ref}`);
+            }
+            else if (!availableTechPlans.has(ref)) {
+                errors.push(`Draft task ${String(rawTask.id ?? "")} references missing or generated tech plan slice: ${ref}`);
+            }
+        }
+        primaryRefs.push(normalizedRefs[0]);
+    });
+    if (developmentTasks.length === 0) {
+        errors.push("plan.draft.yaml must contain at least one development task with implementation_doc");
+    }
+    if (developmentTasks.length > 1 && new Set(primaryRefs).size !== primaryRefs.length) {
+        errors.push("Draft development tasks must reference distinct primary tech plan slices in docs.tech_plan");
+    }
+    return { errors, tasks };
+}
+function validateDraftTaskShape(task, index, errors) {
+    const prefix = `Task #${index + 1}`;
+    for (const field of ["id", "title", "status", "summary"]) {
+        if (!task[field])
+            errors.push(`${prefix} missing field: ${field}`);
+    }
+    const taskId = String(task.id ?? "");
+    if (!/^[A-Z]+-\d+$/.test(taskId)) {
+        errors.push(`${taskId || prefix} id must match PREFIX-###`);
+    }
+    if (taskId.startsWith("TASK-") && !TASK_PHASES.has(String(task.phase ?? ""))) {
+        errors.push(`${taskId} must define valid phase`);
+    }
+    else if (task.phase !== undefined && !TASK_PHASES.has(String(task.phase))) {
+        errors.push(`${taskId} has invalid phase: ${String(task.phase)}`);
+    }
+    if (!TASK_STATUSES.has(String(task.status))) {
+        errors.push(`${String(task.id ?? prefix)} has invalid status: ${String(task.status)}`);
+    }
+    if (typeof task.summary !== "string" || !task.summary.trim()) {
+        errors.push(`${String(task.id ?? prefix)} must define summary`);
+    }
+    const hasImplementationDoc = typeof task.implementation_doc === "string" && task.implementation_doc.trim().length > 0;
+    const hasResultDocs = Array.isArray(task.result_docs) && task.result_docs.length > 0;
+    if (!hasImplementationDoc && !hasResultDocs) {
+        errors.push(`${String(task.id ?? prefix)} must define implementation_doc or result_docs`);
+    }
+    if (OPEN_TASK_STATUSES.has(String(task.status))) {
+        if ("gate_result" in task)
+            errors.push(`${String(task.id ?? prefix)} open task must not define gate_result`);
+        for (const field of ["docs", "allowed_paths", "required_gates", "acceptance_criteria"]) {
+            if (!task[field])
+                errors.push(`${String(task.id ?? prefix)} open task missing field: ${field}`);
+        }
+        if (!isRecord(task.docs))
+            errors.push(`${String(task.id ?? prefix)} docs must be a mapping`);
+        if (!Array.isArray(task.allowed_paths) || task.allowed_paths.length === 0) {
+            errors.push(`${String(task.id ?? prefix)} must define allowed_paths`);
+        }
+        if (!Array.isArray(task.required_gates) || task.required_gates.length === 0) {
+            errors.push(`${String(task.id ?? prefix)} must define required_gates`);
+        }
+        if (!Array.isArray(task.acceptance_criteria) || task.acceptance_criteria.length === 0) {
+            errors.push(`${String(task.id ?? prefix)} must define acceptance_criteria`);
+        }
+    }
+    else {
+        for (const field of ["docs", "allowed_paths", "required_gates", "acceptance_criteria", "working_notes", "gate_result", "result_docs"]) {
+            if (field in task)
+                errors.push(`${String(task.id ?? prefix)} closed task must not retain ${field}`);
+        }
+    }
+}
+async function validateCrossCuttingArchitecture(projectRoot, productFiles, techPlanFiles, architectureFiles, draftTasks) {
+    const errors = [];
+    const sourceText = [
+        await combinedText(productFiles),
+        await combinedText(techPlanFiles),
+        draftTasks.map(taskText).join("\n")
+    ].join("\n");
+    const architectureTexts = await Promise.all(architectureFiles.map(async (file) => ({ file, text: await readText(file) })));
+    const assigned = new Set();
+    for (const category of DESIGN_CATEGORIES) {
+        if (!containsAny(sourceText, category.triggerTerms))
+            continue;
+        const match = architectureTexts.find((doc) => !assigned.has(repoRelative(projectRoot, doc.file)) && containsAny(doc.text, category.architectureTerms));
+        if (!match) {
+            errors.push(`Design requires a dedicated ${category.label} architecture slice`);
+        }
+        else {
+            assigned.add(repoRelative(projectRoot, match.file));
+        }
+    }
+    return errors;
+}
 async function validateDev(projectRoot) {
+    const plan = await validatePlanState(projectRoot, false);
+    return { info: [`validate-dev checked ${plan.taskCount} task(s)`], errors: plan.errors };
+}
+async function validateReview(projectRoot) {
+    const plan = await validatePlanState(projectRoot, false);
+    const text = (await readText(path.join(projectRoot, ".docs/06_review/REVIEW_REPORT.md"))).toLowerCase();
+    const errors = [...plan.errors];
+    if (!containsAny(text, ["finding", "发现", "风险"]))
+        errors.push("Review report must include findings or risks");
+    if (!containsAny(text, ["test gap", "测试缺口", "coverage"]))
+        errors.push("Review report must include test gaps or coverage notes");
+    if (!containsAny(text, ["pass", "blocked", "通过", "阻塞"]))
+        errors.push("Review report must include PASS/BLOCKED decision");
+    return { info: ["validate-review checked review report"], errors };
+}
+async function validateTest(projectRoot) {
+    const plan = await validatePlanState(projectRoot, false);
+    const text = (await readText(path.join(projectRoot, ".docs/07_test/TEST_PLAN.md"))).toLowerCase();
+    const errors = [...plan.errors];
+    if (!containsAny(text, ["matrix", "矩阵"]))
+        errors.push("Test plan must include a test matrix");
+    if (!containsAny(text, ["regression", "回归"]))
+        errors.push("Test plan must include regression coverage");
+    if (!containsAny(text, ["coverage gap", "覆盖缺口", "gap"]))
+        errors.push("Test plan must include coverage gaps");
+    if (!containsAny(text, ["pass", "blocked", "通过", "阻塞"]))
+        errors.push("Test plan must include PASS/BLOCKED decision");
+    return { info: ["validate-test checked test plan"], errors };
+}
+async function validateRelease(projectRoot) {
+    const plan = await validatePlanState(projectRoot, false);
+    const docs = await markdownFiles(path.join(projectRoot, ".docs/08_release"));
+    const text = await combinedText(docs);
+    const errors = [...plan.errors];
+    if (docs.length === 0)
+        errors.push("No release deliverables found");
+    if (!containsAny(text, ["release", "发布"]))
+        errors.push("Release docs must include release notes");
+    if (!containsAny(text, ["smoke", "冒烟"]))
+        errors.push("Release docs must include smoke test evidence");
+    if (!containsAny(text, ["rollback", "回滚"]))
+        errors.push("Release docs must include rollback plan");
+    return { info: [`validate-release checked ${docs.length} file(s)`], errors };
+}
+async function validateRfc(projectRoot) {
+    const plan = await validatePlanState(projectRoot, false);
+    const docs = await markdownFiles(path.join(projectRoot, ".docs/rfc"));
+    const text = await combinedText(docs);
+    const errors = [...plan.errors];
+    if (docs.length === 0)
+        errors.push("No RFC documents found");
+    if (!containsAny(text, ["background", "背景"]))
+        errors.push("RFC must include background");
+    if (!containsAny(text, ["product impact", "产品影响"]))
+        errors.push("RFC must include product impact");
+    if (!containsAny(text, ["technical impact", "技术影响"]))
+        errors.push("RFC must include technical impact candidates");
+    if (!containsAny(text, ["regression", "回归"]))
+        errors.push("RFC must include regression requirements");
+    const statuses = [...text.matchAll(/status:\s*([a-z_]+)/g)].map((match) => match[1].toUpperCase());
+    if (statuses.length === 0)
+        errors.push("RFC must include a Status line");
+    const invalidStatuses = statuses.filter((status) => !["DRAFT", "APPLIED", "VERIFIED", "ARCHIVED"].includes(status));
+    if (invalidStatuses.length > 0)
+        errors.push(`Invalid RFC status: ${invalidStatuses.join(", ")}`);
+    return { info: [`validate-rfc checked ${docs.length} file(s)`], errors };
+}
+async function validatePlanState(projectRoot, allowOpen) {
     const errors = [];
     const root = await harnessRoot(projectRoot);
     const tasksData = await readYamlObject(path.join(projectRoot, root, "state", "plan.yaml"));
-    validateParallelExecutionContract(tasksData, errors);
+    const lifecycle = await readYamlObject(path.join(projectRoot, root, "state", "lifecycle.yaml"));
+    const currentPhase = String(lifecycle.current_phase ?? "");
+    if ("current_phase" in tasksData) {
+        errors.push("plan.yaml must not define current_phase; lifecycle.yaml is the single source for current_phase");
+    }
+    validateParallelExecutionContract(tasksData, currentPhase, errors);
     const tasks = Array.isArray(tasksData.tasks) ? tasksData.tasks : [];
     const nextTaskSequence = tasksData.next_task_sequence;
     if (!Number.isInteger(nextTaskSequence) || Number(nextTaskSequence) <= 0) {
         errors.push("plan.yaml must define positive integer next_task_sequence");
     }
     const open = tasks.filter((task) => ["pending", "in_progress", "blocked", "pending_revision"].includes(String(task.status)));
-    if (open.length > 0)
+    if (!allowOpen && open.length > 0)
         errors.push(`Open tasks remain: ${open.map((task) => task.id).join(", ")}`);
     let maxTaskSequence = 0;
-    for (const task of tasks) {
-        for (const field of ["id", "title", "status", "summary", "implementation_doc"]) {
+    tasks.forEach((task, index) => {
+        if (!isRecord(task)) {
+            errors.push(`Task #${index + 1} must be a mapping`);
+            return;
+        }
+        for (const field of ["id", "title", "status", "summary"]) {
             if (!task[field])
                 errors.push(`Task missing ${field}: ${String(task.id ?? "unknown")}`);
         }
         const taskId = String(task.id ?? "");
-        const match = taskId.match(/^DEV-(\d+)$/);
+        if (!/^[A-Z]+-\d+$/.test(taskId)) {
+            errors.push(`${taskId || `Task #${index + 1}`} id must match PREFIX-###`);
+        }
+        if (taskId.startsWith("TASK-") && !TASK_PHASES.has(String(task.phase ?? ""))) {
+            errors.push(`${taskId} must define valid phase`);
+        }
+        else if (task.phase !== undefined && !TASK_PHASES.has(String(task.phase))) {
+            errors.push(`${taskId} has invalid phase: ${String(task.phase)}`);
+        }
+        if (!["pending", "in_progress", "done", "blocked", "pending_revision", "cancelled"].includes(String(task.status))) {
+            errors.push(`${String(task.id ?? `Task #${index + 1}`)} has invalid status: ${String(task.status)}`);
+        }
+        const hasImplementationDoc = typeof task.implementation_doc === "string" && task.implementation_doc.trim().length > 0;
+        const hasResultDocs = Array.isArray(task.result_docs) && task.result_docs.length > 0;
+        if (!hasImplementationDoc && !hasResultDocs) {
+            errors.push(`${String(task.id ?? `Task #${index + 1}`)} must define implementation_doc or result_docs`);
+        }
+        const match = taskId.match(/^[A-Z]+-(\d+)$/);
         if (match) {
             maxTaskSequence = Math.max(maxTaskSequence, Number(match[1]));
         }
@@ -118,27 +387,37 @@ async function validateDev(projectRoot) {
                 if (!task[field])
                     errors.push(`Open task ${task.id} missing ${field}`);
             }
+            if (!isRecord(task.docs)) {
+                errors.push(`${task.id} docs must be a mapping`);
+            }
             if (!Array.isArray(task.allowed_paths) || task.allowed_paths.length === 0) {
                 errors.push(`Open task ${task.id} must define allowed_paths`);
             }
             if (!Array.isArray(task.required_gates) || task.required_gates.length === 0) {
                 errors.push(`Open task ${task.id} must define required_gates`);
             }
+            if (!Array.isArray(task.acceptance_criteria) || task.acceptance_criteria.length === 0) {
+                errors.push(`Open task ${task.id} must define acceptance_criteria`);
+            }
         }
         else {
             errors.push(`Completed task ${task.id} must not remain in plan.yaml`);
-            for (const field of ["docs", "allowed_paths", "required_gates", "acceptance_criteria", "working_notes", "gate_result"]) {
-                if (task[field])
+            for (const field of ["docs", "allowed_paths", "required_gates", "acceptance_criteria", "working_notes", "gate_result", "result_docs"]) {
+                if (field in task)
                     errors.push(`Closed task ${task.id} must not retain ${field}`);
             }
         }
-    }
+    });
     if (Number.isInteger(nextTaskSequence) && Number(nextTaskSequence) <= maxTaskSequence) {
         errors.push("next_task_sequence must be greater than task ids currently in plan.yaml");
     }
-    return { info: [`validate-dev checked ${tasks.length} task(s)`], errors };
+    const currentTaskId = String(tasksData.current_task_id ?? "");
+    if (currentTaskId && !tasks.some((task) => isRecord(task) && task.id === currentTaskId)) {
+        errors.push(`current_task_id does not match a task: ${currentTaskId}`);
+    }
+    return { taskCount: tasks.length, errors, plan: tasksData };
 }
-function validateParallelExecutionContract(plan, errors) {
+function validateParallelExecutionContract(plan, currentPhase, errors) {
     const contract = plan.parallel_execution;
     if (contract === undefined || contract === null)
         return;
@@ -153,17 +432,19 @@ function validateParallelExecutionContract(plan, errors) {
     if (!PARALLEL_MODES.has(String(contract.mode ?? ""))) {
         errors.push("parallel_execution.mode must be runtime_managed or user_orchestrated");
     }
-    if (!PARALLEL_PHASES.has(String(contract.phase ?? ""))) {
-        errors.push("parallel_execution.phase must be REQUIREMENT_GATHERING, SPRINTING, or TESTING");
+    if ("phase" in contract) {
+        errors.push("parallel_execution must not define phase; lifecycle.yaml is the single source for current_phase");
+    }
+    if ("linked_task_id" in contract) {
+        errors.push("parallel_execution must not define linked_task_id; use plan.yaml current_task_id");
+    }
+    if (!PARALLEL_ALLOWED_PHASES.has(currentPhase)) {
+        errors.push("parallel_execution is only supported during REQUIREMENT_GATHERING, SPRINTING, or TESTING");
     }
     if (contract.coordinator !== "main_agent")
         errors.push('parallel_execution.coordinator must be "main_agent"');
-    if (contract.phase === "SPRINTING") {
-        if (!contract.linked_task_id)
-            errors.push("SPRINTING parallel_execution must define linked_task_id");
-        if (contract.linked_task_id !== plan.current_task_id) {
-            errors.push("SPRINTING parallel_execution.linked_task_id must match current_task_id");
-        }
+    if (currentPhase === "SPRINTING" && !plan.current_task_id) {
+        errors.push("SPRINTING parallel_execution requires plan.yaml current_task_id");
     }
     const workers = contract.workers;
     if (!Array.isArray(workers) || workers.length === 0) {
@@ -227,6 +508,36 @@ function validateParallelExecutionContract(plan, errors) {
         errors.push("parallel_execution.integration.fact_source_updates must be a non-empty list");
     }
 }
+async function validateChangedPaths(projectRoot, plan, allowOpen) {
+    if (!allowOpen)
+        return [];
+    const currentTaskId = String(plan.current_task_id ?? "");
+    if (!currentTaskId)
+        return [];
+    const tasks = Array.isArray(plan.tasks) ? plan.tasks : [];
+    const task = tasks.find((candidate) => isRecord(candidate) && candidate.id === currentTaskId);
+    if (!isRecord(task))
+        return [`current_task_id does not match a task: ${currentTaskId}`];
+    if (!Array.isArray(task.allowed_paths))
+        return [`${currentTaskId} must define allowed_paths`];
+    const patterns = task.allowed_paths.map((pattern) => String(pattern).replace("<harnessRoot>", ".codex"));
+    const changed = await changedFiles(projectRoot);
+    const blocked = changed.filter((file) => !matchesAny(file, patterns));
+    return blocked.length > 0 ? [`Changed files outside current task allowed_paths: ${blocked.join(", ")}`] : [];
+}
+function matchesAny(file, patterns) {
+    return patterns.some((pattern) => matchesGlob(file, pattern));
+}
+function matchesGlob(file, pattern) {
+    const normalizedFile = file.replace(/\\/g, "/");
+    const normalizedPattern = pattern.replace(/\\/g, "/");
+    if (normalizedFile === normalizedPattern)
+        return true;
+    if (normalizedPattern.endsWith("/**") && normalizedFile.startsWith(normalizedPattern.slice(0, -3)))
+        return true;
+    const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*");
+    return new RegExp(`^${escaped}$`).test(normalizedFile);
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -237,14 +548,46 @@ async function readYamlObject(filePath) {
 }
 async function markdownFiles(root) {
     const files = await listFiles(root);
-    return files.filter((file) => file.endsWith(".md") && !file.endsWith("overview.md"));
+    return files.filter((file) => {
+        const name = path.basename(file).toLowerCase();
+        return file.endsWith(".md") && name !== "overview.md" && name !== "readme.md";
+    });
 }
 async function combinedText(files) {
     const parts = await Promise.all(files.map((file) => readText(file)));
     return parts.join("\n").toLowerCase();
 }
 function containsAny(text, needles) {
-    return needles.some((needle) => text.includes(needle.toLowerCase()));
+    const lowered = text.toLowerCase();
+    return needles.some((needle) => lowered.includes(needle.toLowerCase()));
+}
+function isDevelopmentDraft(task) {
+    const taskId = String(task.id ?? "");
+    return Boolean(task.implementation_doc) || task.phase === "SPRINTING" || taskId.startsWith("DEV-");
+}
+function asStringList(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => String(item).trim()).filter(Boolean);
+    }
+    if (typeof value === "string" && value.trim())
+        return [value.trim()];
+    return [];
+}
+function normalizeDocRef(value) {
+    const normalized = value.replace(/\\/g, "/");
+    return normalized.startsWith("./") ? normalized.slice(2) : normalized;
+}
+function repoRelative(projectRoot, file) {
+    return path.relative(projectRoot, file).split(path.sep).join("/");
+}
+function taskText(task) {
+    const parts = ["id", "title", "summary", "phase"].map((key) => String(task[key] ?? "")).filter(Boolean);
+    if (isRecord(task.docs)) {
+        for (const value of Object.values(task.docs)) {
+            parts.push(...asStringList(value));
+        }
+    }
+    return parts.join("\n");
 }
 export async function changedFiles(projectRoot) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {