agent-project-sdlc 0.1.23 → 0.1.25

package/dist/lib/validators.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { harnessPath, harnessRoot } from "./harness-root.js";
 import { listFiles, pathExists, readText } from "./fs.js";
@@ -8,11 +9,11 @@ const execFileAsync = promisify(execFile);
 const PARALLEL_MODES = new Set(["runtime_managed", "user_orchestrated"]);
 const PARALLEL_TRIGGERS = new Set(["user_requested", "workflow_default"]);
 const PARALLEL_RUNTIME_PROVIDERS = new Set(["codex_native_subagents", "user_orchestrated", "codex_exec_worktree"]);
-const TASK_PHASES = new Set(["REQUIREMENT_GATHERING", "ARCHITECTING", "SPRINTING", "REVIEWING", "TESTING", "RELEASING", "RFC_RECALIBRATION"]);
+const TASK_PHASES = new Set(["REQUIREMENT_GATHERING", "UI_UX_DESIGNING", "ARCHITECTING", "SPRINTING", "REVIEWING", "TESTING", "RELEASING", "RFC_RECALIBRATION"]);
 const RESERVED_SUSPENDED_PHASE_TARGET = "<suspended_phase>";
 const TRANSITION_KINDS = new Set(["normal", "return", "interrupt", "resume"]);
-const PARALLEL_ALLOWED_PHASES = new Set(["REQUIREMENT_GATHERING", "ARCHITECTING", "SPRINTING", "REVIEWING", "TESTING", "RELEASING", "RFC_RECALIBRATION"]);
-const PARALLEL_READ_ONLY_PHASES = new Set(["REQUIREMENT_GATHERING", "ARCHITECTING", "REVIEWING", "RELEASING", "RFC_RECALIBRATION"]);
+const PARALLEL_ALLOWED_PHASES = new Set(["REQUIREMENT_GATHERING", "UI_UX_DESIGNING", "ARCHITECTING", "SPRINTING", "REVIEWING", "TESTING", "RELEASING", "RFC_RECALIBRATION"]);
+const PARALLEL_READ_ONLY_PHASES = new Set(["REQUIREMENT_GATHERING", "UI_UX_DESIGNING", "ARCHITECTING", "REVIEWING", "RELEASING", "RFC_RECALIBRATION"]);
 const PARALLEL_PROTECTED_WRITE_PATTERNS = [
     ".codex/state/**",
     "<harnessRoot>/state/**",
@@ -86,8 +87,12 @@ const TESTING_DISALLOWED_CHANGED_PATHS = [...TESTING_DISALLOWED_ALLOWED_PATHS, "
 const TESTING_RUNTIME_FILE_TERMS = ["bootstrap", "cloud", "daemon", "poller", "provider", "runtime", "service", "systemd"];
 const TESTING_ALLOWED_TEST_FILE_TERMS = ["assertion", "fixture", "mock", "smoke"];
 const TEST_REPORT_PATH = ".docs/07_test/TEST_REPORT.md";
+const TEST_CASES_PATH = ".docs/07_test/TEST_CASES.md";
+const EXPERIENCE_DOC_PREFIX = ".docs/02_experience/";
+const DESIGN_SYSTEM_PATH = "DESIGN.md";
 const CURRENT_RELEASE_REPORT_PATH = ".docs/08_release/CURRENT_RELEASE.md";
 const TEST_REPORT_PLACEHOLDER_TERMS = ["pending", "tbd", "todo", "待填", "待补", "placeholder"];
+const TEST_CASE_ID_PATTERN = /\bTC-\d{3,}\b/g;
 const TEST_FACT_SOURCE_PHASES = new Set(["TESTING", "RFC_RECALIBRATION"]);
 const TEST_FACT_SOURCE_PATTERNS = [".docs/07_test/**", ".docs/07_test/"];
 const TEST_FACT_SOURCE_REF = /\.docs\/07_test\/[^\s`,)]+/g;
@@ -466,11 +471,47 @@ const RFC_SELF_TEST_TRIGGER_TERMS = [
     "运行环境",
     "阻塞"
 ];
+const RFC_UIUX_TRIGGER_TERMS = [
+    "ui/ux",
+    "ux",
+    "screen",
+    "interaction",
+    "design.md",
+    "frontend",
+    "browser",
+    "page",
+    "visual",
+    "体验",
+    "屏幕",
+    "交互",
+    "视觉",
+    "前端"
+];
+const RFC_UIUX_IMPACT_TERMS = ["ui/ux impact", "体验影响"];
+const UI_DRAFT_TASK_TERMS = [
+    "frontend",
+    "front-end",
+    "browser",
+    "page",
+    "screen",
+    "route",
+    "component",
+    "visual_ui",
+    "design.md",
+    ".docs/02_experience/",
+    "页面",
+    "前端",
+    "屏幕",
+    "交互",
+    "组件",
+    "视觉"
+];
 const validators = {
     "validate-harness": validateHarness,
     "validate-current": validateCurrent,
     "validate-plan": validatePlan,
     "validate-pm": validatePm,
+    "validate-uiux": validateUiux,
     "validate-design": validateDesign,
     "validate-dev": validateDev,
     "validate-review": validateReview,
@@ -495,6 +536,7 @@ async function validateHarness(projectRoot) {
     for (const required of [
         "AGENTS.md",
         ".docs/INDEX.md",
+        ".docs/02_experience",
         ".docs/09_runbooks",
         harnessPath(root, "config.yaml"),
         harnessPath(root, "state", "lifecycle.yaml"),
@@ -521,6 +563,7 @@ async function validateCurrent(projectRoot) {
     }
     const gateByPhase = {
         REQUIREMENT_GATHERING: "validate-pm",
+        UI_UX_DESIGNING: "validate-uiux",
         ARCHITECTING: "validate-design",
         SPRINTING: "validate-dev",
         REVIEWING: "validate-review",
@@ -545,6 +588,48 @@ async function validatePm(projectRoot) {
         errors.push("PRD must include open questions");
     return { info: [`validate-pm checked ${docs.length} file(s)`], errors };
 }
+async function validateUiux(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 ?? "") !== "UI_UX_DESIGNING");
+    const docs = await markdownFiles(path.join(projectRoot, ".docs/02_experience"));
+    const errors = [...plan.errors];
+    if (docs.length === 0)
+        errors.push("No UI/UX deliverables found in .docs/02_experience/");
+    let visualUi = false;
+    for (const doc of docs) {
+        const relative = repoRelative(projectRoot, doc);
+        const text = await readText(doc);
+        const notApplicable = containsAny(text, ["applicability: not_applicable", "applicability: `not_applicable`"]);
+        visualUi = visualUi || containsAny(text, ["applicability: visual_ui", "applicability: `visual_ui`"]);
+        if (notApplicable)
+            continue;
+        if (!containsAny(text, ["prd", "requirement", "需求"]))
+            errors.push(`${relative} must cite PRD and requirement IDs`);
+        if (!containsAny(text, ["user journey", "user journeys", "用户旅程"]))
+            errors.push(`${relative} must include user journeys`);
+        if (!containsAny(text, ["handoff matrix", "交接矩阵"]))
+            errors.push(`${relative} must include a handoff matrix`);
+        if (!containsAny(text, ["loading", "empty", "error", "success", "permission", "加载", "空状态", "错误", "成功", "权限"])) {
+            errors.push(`${relative} screen contracts must cover applicable loading/empty/error/success/permission states`);
+        }
+        if (!containsAny(text, ["responsive", "breakpoint", "响应式", "断点"]))
+            errors.push(`${relative} must include responsive acceptance`);
+        if (!containsAny(text, ["accessibility", "a11y", "focus", "keyboard", "touch", "无障碍", "焦点", "键盘", "触控"])) {
+            errors.push(`${relative} must include accessibility/focus/keyboard/touch expectations`);
+        }
+    }
+    if (visualUi) {
+        const designPath = path.join(projectRoot, DESIGN_SYSTEM_PATH);
+        if (!(await pathExists(designPath))) {
+            errors.push("visual UI experience requires root DESIGN.md");
+        }
+        else {
+            errors.push(...(await validateDesignMd(projectRoot)));
+        }
+    }
+    return { info: [`validate-uiux 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"));
@@ -552,6 +637,7 @@ async function validateDesign(projectRoot) {
     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 experience = await markdownFiles(path.join(projectRoot, ".docs/02_experience"));
     const text = await combinedText([...architecture, ...techPlan]);
     const errors = [...plan.errors];
     if (architecture.length === 0)
@@ -564,7 +650,7 @@ 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);
+    const draft = await validateDesignDraft(projectRoot, root, techPlan, experience);
     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 };
@@ -574,7 +660,7 @@ async function validatePlan(projectRoot) {
     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) {
+async function validateDesignDraft(projectRoot, root, techPlanFiles, experienceFiles) {
     const errors = [];
     const draft = await readYamlObject(path.join(projectRoot, root, "state", "plan.draft.yaml"));
     if ("current_phase" in draft) {
@@ -590,6 +676,7 @@ async function validateDesignDraft(projectRoot, root, techPlanFiles) {
     }
     const tasks = rawTasks.filter(isRecord);
     const availableTechPlans = new Set(techPlanFiles.map((file) => repoRelative(projectRoot, file)));
+    const availableExperienceDocs = new Set(experienceFiles.map((file) => repoRelative(projectRoot, file)));
     const developmentTasks = [];
     const primaryRefs = [];
     for (const [index, rawTask] of rawTasks.entries()) {
@@ -622,6 +709,7 @@ async function validateDesignDraft(projectRoot, root, techPlanFiles) {
                 errors.push(`Draft task ${String(rawTask.id ?? "")} references missing or generated tech plan slice: ${ref}`);
             }
         }
+        errors.push(...(await validateUiuxDesignRefsForDraftTask(projectRoot, rawTask, availableExperienceDocs)));
         errors.push(...(await validateSelfTestContractTechPlanBinding(projectRoot, rawTask, normalizedRefs)));
         primaryRefs.push(normalizedRefs[0]);
     }
@@ -633,6 +721,51 @@ async function validateDesignDraft(projectRoot, root, techPlanFiles) {
     }
     return { errors, tasks };
 }
+async function validateUiuxDesignRefsForDraftTask(projectRoot, task, availableExperienceDocs) {
+    const errors = [];
+    if (!isRecord(task.docs))
+        return errors;
+    const taskId = String(task.id ?? "");
+    const uiuxRefs = asStringList(task.docs.uiux).map(normalizeDocRef);
+    const designRefs = asStringList(task.docs.design_system).map(normalizeDocRef);
+    const uiTask = isUiDraftTask(task);
+    if (uiTask && uiuxRefs.length === 0) {
+        errors.push(`UI/frontend draft task ${taskId} must reference a UI/UX slice in docs.uiux`);
+    }
+    if (uiTask && designRefs.length === 0) {
+        errors.push(`UI/frontend draft task ${taskId} must reference DESIGN.md in docs.design_system`);
+    }
+    for (const ref of uiuxRefs) {
+        if (!ref.startsWith(EXPERIENCE_DOC_PREFIX)) {
+            errors.push(`Draft task ${taskId} docs.uiux must point into .docs/02_experience/: ${ref}`);
+        }
+        else if (!availableExperienceDocs.has(ref)) {
+            errors.push(`Draft task ${taskId} references missing or generated UI/UX slice: ${ref}`);
+        }
+    }
+    for (const ref of designRefs) {
+        if (ref !== DESIGN_SYSTEM_PATH) {
+            errors.push(`Draft task ${taskId} docs.design_system must point to DESIGN.md: ${ref}`);
+        }
+        else if (!(await pathExists(path.join(projectRoot, DESIGN_SYSTEM_PATH)))) {
+            errors.push(`Draft task ${taskId} references missing design system: ${DESIGN_SYSTEM_PATH}`);
+        }
+    }
+    return errors;
+}
+function isUiDraftTask(task) {
+    const docsText = isRecord(task.docs)
+        ? Object.values(task.docs)
+            .flatMap((value) => asStringList(value))
+            .join("\n")
+        : "";
+    const runtimeText = [task.target_runtime_environment, task.self_test_contract]
+        .filter(Boolean)
+        .map((value) => JSON.stringify(value))
+        .join("\n");
+    const text = [task.id, task.title, task.summary, task.phase, docsText, runtimeText].map((value) => String(value ?? "")).join("\n");
+    return containsAny(text, UI_DRAFT_TASK_TERMS);
+}
 function validateDraftTaskShape(task, index, errors) {
     const prefix = `Task #${index + 1}`;
     for (const field of ["id", "title", "status", "summary"]) {
@@ -815,6 +948,7 @@ async function validateTest(projectRoot) {
         errors.push("Test report must include PASS/BLOCKED decision");
     errors.push(...validateTestReadinessDecision(text));
     errors.push(...validateRuntimeHandoffReport(report?.text ?? "", "Test report"));
+    errors.push(...(await validateTestCasesIfNeeded(projectRoot, plan.plan, report?.text ?? "")));
     if (lifecycle.current_phase === "TESTING") {
         errors.push(...testingBoundaryErrorsForChangedFiles(await changedFiles(projectRoot)));
     }
@@ -872,6 +1006,7 @@ async function validateRfc(projectRoot) {
     if (invalidStatuses.length > 0)
         errors.push(`Invalid RFC status: ${invalidStatuses.join(", ")}`);
     errors.push(...(await validateRfcSelfTestImpact(projectRoot, docs)));
+    errors.push(...(await validateRfcUiuxImpact(projectRoot, docs)));
     return { info: [`validate-rfc checked ${docs.length} file(s)`], errors };
 }
 async function validateRfcSelfTestImpact(projectRoot, docs) {
@@ -891,6 +1026,23 @@ async function validateRfcSelfTestImpact(projectRoot, docs) {
     }
     return errors;
 }
+async function validateRfcUiuxImpact(projectRoot, docs) {
+    const errors = [];
+    for (const doc of docs) {
+        const relative = repoRelative(projectRoot, doc);
+        const basename = path.basename(doc);
+        const number = rfcNumber(basename);
+        if (number !== undefined && number < 27)
+            continue;
+        const text = await readText(doc);
+        if (!containsAny(text, RFC_UIUX_TRIGGER_TERMS))
+            continue;
+        if (!containsAny(text, RFC_UIUX_IMPACT_TERMS)) {
+            errors.push(`${relative} must include UI/UX Impact when RFC changes experience docs, screen contracts, DESIGN.md, frontend, or browser behavior`);
+        }
+    }
+    return errors;
+}
 function rfcNumber(fileName) {
     const match = fileName.match(/^RFC[_-](\d+)/i);
     return match ? Number(match[1]) : undefined;
@@ -1484,7 +1636,7 @@ function validateParallelExecutionContract(plan, currentPhase, errors) {
         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, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING, or RFC_RECALIBRATION");
+        errors.push("parallel_execution is only supported during REQUIREMENT_GATHERING, UI_UX_DESIGNING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING, or RFC_RECALIBRATION");
     }
     if (contract.coordinator !== "main_agent")
         errors.push('parallel_execution.coordinator must be "main_agent"');
@@ -2375,6 +2527,167 @@ function validateTestReadinessDecision(text) {
     }
     return [];
 }
+async function validateDesignMd(projectRoot) {
+    const errors = [];
+    try {
+        const cliPath = await findDesignMdCliPath(projectRoot);
+        if (!cliPath) {
+            errors.push("DESIGN.md linter not found; install package dependencies for @google/design.md");
+            return errors;
+        }
+        const { stdout } = await execFileAsync(process.execPath, [cliPath, "lint", DESIGN_SYSTEM_PATH], { cwd: projectRoot });
+        errors.push(...designMdLintErrors(stdout));
+    }
+    catch (caught) {
+        const error = caught;
+        const parsedErrors = designMdLintErrors(String(error.stdout ?? ""));
+        if (parsedErrors.length > 0) {
+            errors.push(...parsedErrors);
+        }
+        else {
+            errors.push(`DESIGN.md linter failed: ${String(error.stderr ?? error.message ?? "unknown error").trim()}`);
+        }
+    }
+    return errors;
+}
+async function findDesignMdCliPath(projectRoot) {
+    const candidates = [];
+    const addSearchRoots = (start) => {
+        let current = path.resolve(start);
+        while (true) {
+            candidates.push(path.join(current, "node_modules", "@google", "design.md", "dist", "index.js"));
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+    };
+    addSearchRoots(projectRoot);
+    addSearchRoots(path.dirname(fileURLToPath(import.meta.url)));
+    for (const candidate of candidates) {
+        if (await pathExists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function designMdLintErrors(stdout) {
+    const text = stdout.trim();
+    if (!text)
+        return [];
+    try {
+        const diagnostics = JSON.parse(text);
+        const errors = [];
+        const summary = isRecord(diagnostics.summary) ? diagnostics.summary : {};
+        if (Number(summary.errors ?? 0) > 0) {
+            errors.push("DESIGN.md linter reported errors");
+        }
+        const findings = Array.isArray(diagnostics.findings) ? diagnostics.findings : [];
+        for (const finding of findings) {
+            if (!isRecord(finding) || String(finding.severity ?? "").toLowerCase() !== "error")
+                continue;
+            errors.push(String(finding.message ?? "DESIGN.md linter error"));
+        }
+        return errors;
+    }
+    catch {
+        return [];
+    }
+}
+async function validateTestCasesIfNeeded(projectRoot, plan, reportText) {
+    const casesPath = path.join(projectRoot, TEST_CASES_PATH);
+    const shouldValidate = testCaseRefs(reportText).length > 0 || planReferencesTestCases(plan) || (await pathExists(casesPath));
+    if (!shouldValidate)
+        return [];
+    if (!(await pathExists(casesPath))) {
+        return [`Missing test cases: expected ${TEST_CASES_PATH} because TEST_REPORT.md or current TESTING task references test cases`];
+    }
+    return validateTestCases(await readText(casesPath), reportText);
+}
+function testCaseRefs(text) {
+    return [...new Set(text.match(TEST_CASE_ID_PATTERN) ?? [])].sort();
+}
+function planReferencesTestCases(plan) {
+    const tasks = Array.isArray(plan.tasks) ? plan.tasks : [];
+    return tasks.some((task) => {
+        if (!isRecord(task) || String(task.phase ?? "") !== "TESTING")
+            return false;
+        return asStringList(task.result_docs).includes(TEST_CASES_PATH);
+    });
+}
+function validateTestCases(text, reportText) {
+    const errors = [];
+    if (containsAny(text, TEST_REPORT_PLACEHOLDER_TERMS)) {
+        errors.push("TEST_CASES.md must not contain pending/TBD/TODO/placeholder content");
+    }
+    const lines = text.split(/\r?\n/);
+    const rows = [];
+    lines.forEach((line, index) => {
+        if (!line.trim().startsWith("|") || !/\bTC-\d{3,}\b/.test(line))
+            return;
+        const headers = findMarkdownTableHeader(lines, index);
+        if (!headers) {
+            errors.push("TEST_CASES.md cases must be listed in a Markdown table with headers");
+            return;
+        }
+        rows.push({ lineNumber: index + 1, headers, cells: splitMarkdownRow(line) });
+    });
+    TEST_CASE_ID_PATTERN.lastIndex = 0;
+    const ids = rows.flatMap((row) => testCaseRefs(row.cells.join("|")));
+    if (ids.length === 0) {
+        errors.push("TEST_CASES.md must include at least one TC-* case");
+    }
+    const duplicates = [...new Set(ids.filter((id, index) => ids.indexOf(id) !== index))].sort();
+    if (duplicates.length > 0) {
+        errors.push(`TEST_CASES.md Case ID must be unique: ${duplicates.join(", ")}`);
+    }
+    for (const row of rows) {
+        const requirement = headerIndex(row.headers, ["requirement", "risk", "需求", "风险"]);
+        const runnableEntry = headerIndex(row.headers, ["runnable entry", "runnable", "entry", "入口"]);
+        const steps = headerIndex(row.headers, ["steps", "步骤"]);
+        const expectedExit = headerIndex(row.headers, ["expected exit", "expected result", "expected", "预期", "出口"]);
+        const missing = [];
+        if (!requiredCell(row.cells, requirement))
+            missing.push("Requirement / Risk Ref");
+        if (!requiredCell(row.cells, runnableEntry))
+            missing.push("Runnable Entry");
+        if (!requiredCell(row.cells, steps))
+            missing.push("Steps");
+        if (!requiredCell(row.cells, expectedExit))
+            missing.push("Expected Exit");
+        if (missing.length > 0) {
+            errors.push(`TEST_CASES.md row ${row.lineNumber} missing required case fields: ${missing.join(", ")}`);
+        }
+    }
+    const missingRefs = testCaseRefs(reportText).filter((id) => !ids.includes(id));
+    if (missingRefs.length > 0) {
+        errors.push(`TEST_REPORT.md references case IDs not found in TEST_CASES.md: ${[...new Set(missingRefs)].join(", ")}`);
+    }
+    return errors;
+}
+function splitMarkdownRow(line) {
+    return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+}
+function isMarkdownSeparatorRow(line) {
+    const stripped = line.trim();
+    return stripped.startsWith("|") && /^[|:\-\s]+$/.test(stripped);
+}
+function findMarkdownTableHeader(lines, rowIndex) {
+    for (let index = rowIndex - 1; index > 0; index -= 1) {
+        if (!isMarkdownSeparatorRow(lines[index]))
+            continue;
+        const header = lines[index - 1];
+        return header.trim().startsWith("|") ? splitMarkdownRow(header) : undefined;
+    }
+    return undefined;
+}
+function headerIndex(headers, terms) {
+    return headers.findIndex((header) => terms.some((term) => header.toLowerCase().includes(term.toLowerCase())));
+}
+function requiredCell(cells, index) {
+    if (index === undefined || index < 0 || index >= cells.length)
+        return "";
+    return cells[index].trim();
+}
 function validateRuntimeHandoffReport(text, label) {
     const decision = finalDecision(text);
     if (decision !== "PASS")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@google/design.md": "^0.2.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {