@namewta/speculo 0.8.5 → 0.8.7

package/template/workflows/specdev/common/tools/validate-specdev.mjs

@@ -34,8 +34,6 @@ const EXPECTED_WORKS = new Set([
   "A-archive-and-consolidate",
   "C-code-review",
   "D-diagnose-bugs",
-  "E-eli5",
-  "E-engineering-cognitive-mentor",
   "G-grill-with-docs",
   "I-implement",
   "I-init-setup",
@@ -99,7 +97,6 @@ const VALID_STAGES = new Set([
   "triage",
   "diagnosis",
   "grill",
-  "eli5",
   "spec",
   "tickets",
   "goal-plan",
@@ -169,7 +166,6 @@ const STATE_ARTIFACT_BASENAMES = new Set([
   "source.md",
   "architecture-review.md",
   "architecture-review.html",
-  "eli_index.md",
   "wayfinder-map.md",
   "design-tree.json",
 ]);
@@ -469,10 +465,21 @@ function validateDocumentReferences(root) {
   const errors = [];
   const warnings = [];
   const entries = walk(root);
-  const knownFiles = new Set(entries.filter(isFile).map((path) => basename(path)));
-  const knownDirectories = new Set(entries.filter(isDirectory).map((path) => basename(path)));
+  const frozenResearchRoot = join(
+    root,
+    "P-prototype",
+    "design-library",
+    "research-snapshot",
+  );
+  const governedEntries = entries.filter(
+    (path) => path !== frozenResearchRoot && !path.startsWith(`${frozenResearchRoot}${sep}`),
+  );
+  const knownFiles = new Set(governedEntries.filter(isFile).map((path) => basename(path)));
+  const knownDirectories = new Set(governedEntries.filter(isDirectory).map((path) => basename(path)));
 
-  for (const path of entries.filter(
+  // The pinned research snapshot preserves its upstream relative links and HTML
+  // asset paths byte-for-byte. Global template link checks still validate it.
+  for (const path of governedEntries.filter(
     (item) => isFile(item) && [".md", ".html"].includes(extname(item).toLowerCase()),
   )) {
     const label = toPosix(relative(root, path));
@@ -686,12 +693,13 @@ function validateExecutionContractAssets(root) {
     configTemplate.execution.max_implementation_agents < 1 ||
     !Number.isInteger(configTemplate.execution?.max_integration_attempts) ||
     configTemplate.execution.max_integration_attempts < 1 ||
-    !Number.isInteger(configTemplate.planning?.ui_prototype_default_variants) ||
-    !Number.isInteger(configTemplate.planning?.ui_prototype_max_variants) ||
-    configTemplate.planning.ui_prototype_default_variants < 1 ||
-    configTemplate.planning.ui_prototype_max_variants < configTemplate.planning.ui_prototype_default_variants
+    !Number.isInteger(configTemplate.planning?.ui_design_default_candidates) ||
+    !Number.isInteger(configTemplate.planning?.ui_design_max_candidates) ||
+    configTemplate.planning.ui_design_default_candidates < 2 ||
+    configTemplate.planning.ui_design_max_candidates > 4 ||
+    configTemplate.planning.ui_design_max_candidates < configTemplate.planning.ui_design_default_candidates
   ) {
-    errors.push("config-template.json must define SpecDev config v5 with positive execution limits and valid prototype variant bounds");
+    errors.push("config-template.json must define SpecDev config v5 with positive execution limits and valid UI design candidate bounds");
   }
   for (const obsolete of ["auto_commit", "worktree_for_parallel", "max_parallel"]) {
     if (JSON.stringify(configTemplate).includes(`\"${obsolete}\"`)) {
@@ -820,14 +828,7 @@ function capabilityChecks(root) {
       "prototype",
       [
         join(root, "P-prototype", "P-prototype.md"),
-        ["一个问题", "Logic", "UI", "临时 branch/worktree", "promotion target", "main"],
-      ],
-    ],
-    [
-      "eli5",
-      [
-        join(root, "E-eli5", "E-eli5.md"),
-        ["大一新生", "零专业背景", "$ARGUMENTS", "ASCII", "eli_index.md", "{number}_{topic}.md"],
+        ["设计定向", "风格", "design-system.md", "comparison", "HTML/CSS/JS", "design-library/INDEX.md"],
       ],
     ],
     [
@@ -1207,88 +1208,79 @@ function validateReviews(change, required, errors) {
 
 function validatePrototypes(change, required, errors) {
   const root = join(change, "prototypes");
-  const paths = isDirectory(root)
-    ? walk(root).filter((path) => isFile(path) && basename(path) === "record.md").sort()
-    : [];
-  if (required && !paths.length) errors.push("prototype stage requires a prototypes/<id>/record.md artifact");
-  for (const path of paths) {
-    const { meta, body } = parseFrontmatter(path);
-    const label = toPosix(relative(change, path));
-    if (meta.schema_version !== 1 || meta.artifact !== "prototype-record") {
-      errors.push(`${label}: artifact/schema_version must be prototype-record/1`);
-    }
-    if (meta.change !== basename(change)) errors.push(`${label}: change must equal directory name`);
-    if (!/^PROTO-\d{3,}$/.test(String(meta.prototype_id ?? ""))) errors.push(`${label}: invalid prototype_id`);
-    if (!new Set(["logic", "ui"]).has(meta.branch)) errors.push(`${label}: invalid prototype branch`);
-    if (!new Set(["active", "answered", "blocked", "discarded"]).has(meta.status)) errors.push(`${label}: invalid prototype status`);
-    if (typeof meta.workspace_ref !== "string" || ABSOLUTE_MACHINE_PATH_RE.test(meta.workspace_ref)) {
-      errors.push(`${label}: workspace_ref must be a portable locator`);
-    }
-    if (meta.status === "answered" && (!String(meta.winner ?? "").trim() || !String(meta.promotion_target ?? "").trim())) {
-      errors.push(`${label}: answered prototype requires winner and promotion_target`);
-    }
-    if (!new Set(["pending", "clean", "registered"]).has(meta.cleanup_status)) errors.push(`${label}: invalid cleanup_status`);
-    for (const heading of ["## Question and Assumption", "## Run and Assets", "## Evaluation", "## Promotion and Cleanup"]) {
-      if (!body.includes(heading)) errors.push(`${label}: missing '${heading}'`);
-    }
+  if (!isDirectory(root)) {
+    if (required) errors.push("prototype stage requires a prototypes/UI-NNN/design-system.md artifact");
+    return [];
   }
-  return paths;
-}
-
-function validateEli5(change, required, errors) {
-  const indexPath = join(change, "eli_index.md");
-  const diagramFiles = readdirSync(change, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && /^\d{2,}_[^/\\\\\s]+\.md$/.test(entry.name))
-    .map((entry) => entry.name)
-    .sort();
 
-  if (!isFile(indexPath)) {
-    if (required) errors.push("eli5 stage requires eli_index.md");
-    return null;
-  }
+  const validator = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "P-prototype",
+    "tools",
+    "validate-design-package.mjs",
+  );
+  const paths = [];
+  let readyCount = 0;
 
-  const index = readText(indexPath);
-  if (!index.includes("# ELI5 图解索引")) errors.push("eli_index.md: missing index heading");
-  const entries = Array.from(index.matchAll(/^\|\s*(\d{2,})\s*\|\s*([^|\s]+\.md)\s*\|\s*([^|]+)\|\s*([^|]+)\|\s*$/gm));
-  if (!entries.length && required) errors.push("eli_index.md: requires at least one diagram entry");
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const entryPath = join(root, entry.name);
+    const label = toPosix(relative(change, entryPath));
+    if (entry.isSymbolicLink()) {
+      errors.push(`${label}: prototype design directories and files must not be symlinks`);
+      continue;
+    }
+    if (!entry.isDirectory()) {
+      errors.push(`${label}: prototypes may only contain UI-NNN design directories`);
+      continue;
+    }
+    if (!/^UI-\d{3,}$/.test(entry.name)) {
+      errors.push(`${label}: prototype design directory must use UI-NNN`);
+      continue;
+    }
 
-  const indexedFiles = new Set();
-  let previousNumber = 0;
-  for (const entry of entries) {
-    const [, number, fileName, topic, summary] = entry;
-    const numericNumber = Number(number);
-    if (!/^\d{2,}_[^/\\\\\s]+\.md$/.test(fileName)) {
-      errors.push(`eli_index.md: invalid diagram filename '${fileName}'`);
+    const designPath = join(entryPath, "design-system.md");
+    if (!isFile(designPath)) {
+      errors.push(`${label}: missing design-system.md`);
       continue;
     }
-    if (numericNumber <= previousNumber) errors.push("eli_index.md: diagram numbers must increase");
-    if (numericNumber !== previousNumber + 1) errors.push("eli_index.md: diagram numbers must start at 01 and be continuous");
-    previousNumber = numericNumber;
-    if (!fileName.startsWith(`${number}_`)) errors.push(`eli_index.md: '${fileName}' must start with '${number}_'`);
-    if (!topic.trim() || !summary.trim()) errors.push(`eli_index.md: '${fileName}' requires a topic and summary`);
-    indexedFiles.add(fileName);
+    paths.push(designPath);
+    const { meta } = parseFrontmatter(designPath);
+    if (meta.status === "ready") readyCount += 1;
+    try {
+      execFileSync(process.execPath, [validator, designPath], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      const details = String(error.stderr || error.stdout || error.message)
+        .trim()
+        .split(/\r?\n/)
+        .filter(Boolean);
+      if (!details.length) errors.push(`${label}: design package validation failed`);
+      for (const detail of details) errors.push(`${label}: ${detail}`);
+    }
   }
 
-  for (const fileName of diagramFiles) {
-    if (!indexedFiles.has(fileName)) errors.push(`eli_index.md: missing entry for '${fileName}'`);
-  }
-  for (const fileName of indexedFiles) {
-    if (!diagramFiles.includes(fileName)) errors.push(`eli_index.md: '${fileName}' does not exist`);
+  const obsoleteRecords = walk(root).filter(
+    (path) => isFile(path) && basename(path) === "record.md",
+  );
+  for (const path of obsoleteRecords) {
+    errors.push(`${toPosix(relative(change, path))}: obsolete prototype record is forbidden; use UI-NNN/design-system.md`);
   }
-
-  for (const fileName of diagramFiles) {
-    const markdown = readText(join(change, fileName));
-    for (const heading of ["## 先看全图", "## 一步一步看", "## 术语小词典", "## 你现在能复述什么"]) {
-      if (!markdown.includes(heading)) errors.push(`${fileName}: missing '${heading}'`);
-    }
-    if (!/```(?:text)?\s*[\s\S]*?(?:->|\||\+--)[\s\S]*?```/.test(markdown)) {
-      errors.push(`${fileName}: requires an ASCII diagram in a fenced code block`);
-    }
-    if (/<\/?(?:html|head|body|svg|canvas|img|picture)\b/i.test(markdown)) {
-      errors.push(`${fileName}: must be Markdown, not HTML`);
+  const discoveredDesigns = walk(root).filter(
+    (path) => isFile(path) && basename(path) === "design-system.md",
+  );
+  for (const path of discoveredDesigns) {
+    if (!paths.includes(path)) {
+      errors.push(`${toPosix(relative(change, path))}: design-system.md must be directly under prototypes/UI-NNN`);
     }
   }
-  return indexPath;
+  if (required && readyCount === 0) {
+    errors.push("prototype stage requires at least one ready UI design package");
+  }
+  return paths;
 }
 
 function validateSpec(path, errors, warnings) {
@@ -2151,7 +2143,6 @@ function validateChange(change, stage = null, repoRoot = null) {
   }
   validateReviews(change, stage === "review", errors);
   validatePrototypes(change, stage === "prototype", errors);
-  validateEli5(change, stage === "eli5", errors);
 
   const specRequired = new Set(["spec", "tickets", "goal-plan", "implement", "complete"]).has(stage);
   const specPath = join(change, "spec.md");