android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/spec-handoff.js

@@ -0,0 +1,1004 @@
+import {
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { buildAreaContentTxt } from "./generation/index.js";
+import {
+  filterRenderableAreas,
+  loadStage2AreaGraph,
+  loadStage2InputWithReport,
+  sortAreasReachableFirst,
+} from "./stage2-input.js";
+import { areaDirFor, renderDirFor } from "./agent-render/orchestrate.js";
+import {
+  mergeAreaReqContents,
+  mergeReqContents,
+} from "./agent-render/merge.js";
+import { readAreaAttempt, readAttempt } from "./agent-render/snapshot.js";
+/** Version of the local contract consumed by the a2h-spec-generate skill. */
+export const SPEC_HANDOFF_CONTRACT_VERSION = "1.0.0";
+export const SPEC_INPUT_FORMAT = "a2h-spec-generate-text-v1";
+/** Validate the exact text boundary understood by
+ * `a2h-spec-generate/scripts/parse_requirements.mjs`. */
+export function validateSpecInputText(text, expectedRequirementCount) {
+  const blocks = text
+    .replace(/^\uFEFF/u, "")
+    .replace(/\r\n?/gu, "\n")
+    .trim()
+    .split(/\n[ \t]*\n+/u)
+    .filter((block) => block.trim().length > 0);
+  if (
+    expectedRequirementCount !== undefined &&
+    blocks.length !== expectedRequirementCount
+  ) {
+    throw new Error(
+      `Spec input contains ${blocks.length} parser blocks; expected ${expectedRequirementCount}`,
+    );
+  }
+  for (const [index, block] of blocks.entries()) {
+    const firstLine = block.split("\n")[0]?.trim() ?? "";
+    if (firstLine.length === 0)
+      throw new Error(`Spec input block ${index + 1} has an empty title`);
+    if (/^(?:访问路径|区域说明|前置条件)\s*[:：]/u.test(firstLine)) {
+      throw new Error(
+        `Spec input block ${index + 1} still exposes Stage 2 metadata`,
+      );
+    }
+  }
+}
+const METADATA_PREFIXES = ["访问路径", "区域说明"];
+function oneLine(value) {
+  return value
+    .replace(/\r\n?/gu, " ")
+    .replace(/[\t ]+/gu, " ")
+    .trim();
+}
+function uniqueNonEmpty(values) {
+  return [...new Set(values.map(oneLine).filter((value) => value.length > 0))];
+}
+function metadataKind(line) {
+  const match = /^(前置条件|访问路径|区域说明)\s*[:：]/u.exec(line);
+  if (match?.[1] === "前置条件") return "precondition";
+  if (match?.[1] === "访问路径") return "path";
+  if (match?.[1] === "区域说明") return "description";
+  return undefined;
+}
+function metadataValue(line) {
+  const separator = line.search(/[:：]/u);
+  return separator < 0 ? "" : line.slice(separator + 1).trim();
+}
+function normalizeBody(value) {
+  // The downstream parser uses a blank line as the requirement separator.
+  // Keep ordinary line breaks (including list indentation), but remove blank
+  // lines so an Agent paragraph can never be mistaken for another REQ item.
+  return value
+    .replace(/^\uFEFF/u, "")
+    .replace(/\r\n?/gu, "\n")
+    .split("\n")
+    .map((line) => line.replace(/[ \t]+$/gu, ""))
+    .filter((line) => line.trim().length > 0)
+    .join("\n")
+    .trim();
+}
+function normalizeTitle(value) {
+  return oneLine(value);
+}
+/** Split the UI-path convention used by both the current renderer (` - `)
+ * and older requirement files (`-` without surrounding spaces).  This helper
+ * is only used for ownership inference; the title itself is always preserved
+ * verbatim in the exported REQ text. */
+function titleSegments(title) {
+  return normalizeTitle(title)
+    .split(/\s*-\s*/u)
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0);
+}
+function comparableTitle(title) {
+  return titleSegments(title).join(" - ");
+}
+function looksLikeUiTitle(value, knownTitles) {
+  const title = normalizeTitle(value);
+  if (knownTitles.has(title)) return true;
+  // Stage 2's deterministic and Agent titles are navigation paths.  The
+  // separator also keeps a continuation paragraph (usually a sentence or a
+  // list item) from being promoted to a new requirement in the legacy parser.
+  if (/^[-*]\s/u.test(title) || /^\d+[.)、]\s/u.test(title)) return false;
+  if (titleSegments(title).length >= 2) return true;
+  // A hand-written legacy title may contain only one page/control name.  A
+  // sentence-like continuation normally ends in punctuation, so this keeps
+  // that useful compatibility case without reintroducing blank-line splits.
+  return title.length <= 160 && !/[。！？.!?；;：:]$/u.test(title);
+}
+/**
+ * Parse the old Stage 2 text formats without exposing their machine headers
+ * to the spec skill.  This is deliberately a compatibility fallback; new
+ * Stage 2 runs are read from finalized output.json files instead.
+ */
+export function parseStage2ReqText(
+  text,
+  sourceFile = "REQ.txt",
+  knownTitles = new Set(),
+) {
+  const normalized = text.replace(/^\uFEFF/u, "").replace(/\r\n?/gu, "\n");
+  const blocks = normalized.split(/\n[ \t]*\n+/u);
+  const preconditions = [];
+  const entries = [];
+  const warnings = [];
+  let activePreconditions = [];
+  for (const [blockIndex, rawBlock] of blocks.entries()) {
+    const lines = rawBlock
+      .split("\n")
+      .map((line) => line.trimEnd())
+      .filter((line) => !/^(```|~~~)\s*$/u.test(line));
+    if (lines.every((line) => line.trim().length === 0)) continue;
+    const contentLines = [];
+    const blockPreconditions = [];
+    let hasAreaMetadata = false;
+    for (const rawLine of lines) {
+      const line = rawLine.trim();
+      if (line.length === 0) continue;
+      const kind = metadataKind(line);
+      if (kind === "precondition") {
+        const value = metadataValue(line);
+        if (value.length > 0) {
+          preconditions.push(value);
+          blockPreconditions.push(value);
+        }
+        continue;
+      }
+      if (kind === "path" || kind === "description") {
+        // These labels describe an Area, not an individual requirement.  They
+        // are intentionally not copied into the downstream input.
+        hasAreaMetadata = true;
+        continue;
+      }
+      contentLines.push(rawLine);
+    }
+    if (hasAreaMetadata) {
+      // A path/description header marks a new Area in the old Markdown
+      // serializer.  Do not leak the previous Area's preconditions into it.
+      activePreconditions = uniqueNonEmpty(blockPreconditions);
+    } else if (blockPreconditions.length > 0) {
+      // A plain req-N.txt commonly stores a standalone precondition block
+      // before its first title.  Keep it active for all following entries in
+      // that file until another Area header resets it.
+      activePreconditions = uniqueNonEmpty([
+        ...activePreconditions,
+        ...blockPreconditions,
+      ]);
+    }
+    if (contentLines.length === 0) continue;
+    const title = normalizeTitle(contentLines[0] ?? "");
+    if (title.length === 0) continue;
+    if (!looksLikeUiTitle(title, knownTitles) && entries.length > 0) {
+      // Embedded blank lines are legal in Agent prose but have the same shape
+      // as the legacy separator.  Treat a non-path block as continuation.
+      const previous = entries[entries.length - 1];
+      const continuation = normalizeBody(contentLines.join("\n"));
+      if (continuation.length > 0) {
+        entries[entries.length - 1] = {
+          ...previous,
+          body: normalizeBody(`${previous.body}\n${continuation}`),
+        };
+      }
+      continue;
+    }
+    let body = normalizeBody(contentLines.slice(1).join("\n"));
+    if (body.startsWith(title)) {
+      body = normalizeBody(body.slice(title.length));
+      warnings.push(
+        `${sourceFile} block ${blockIndex + 1} repeated its title in the body; removed it`,
+      );
+    }
+    entries.push({
+      title,
+      body,
+      sourceIndex: blockIndex + 1,
+      preconditions: [...activePreconditions],
+    });
+  }
+  if (entries.length === 0) {
+    warnings.push(
+      `${sourceFile} did not contain a recognizable UI-path requirement`,
+    );
+  }
+  return {
+    preconditions: uniqueNonEmpty(preconditions),
+    entries,
+    warnings,
+  };
+}
+function inferAreaName(title) {
+  const segments = titleSegments(title);
+  if (segments.length >= 2) return segments[segments.length - 2];
+  return segments[0];
+}
+function inferPagePath(title, areaName) {
+  // A rendered title interleaves page names with actions (for example
+  // `点击"设置"`).  Without the graph we cannot distinguish those boundaries
+  // reliably, so only return a path when the title contains no action-like
+  // segment.  Otherwise the manifest uses the canonical empty path and emits
+  // a warning at the caller.
+  const segments = titleSegments(title);
+  if (segments.length < 2 || areaName === undefined) return [];
+  const areaIndex = segments.lastIndexOf(areaName);
+  if (areaIndex <= 0) return [];
+  const prefix = segments.slice(0, areaIndex);
+  return prefix.some((segment) =>
+    /^(?:点击|长按|选择|切换|输入|提交|返回|滑动|拖动|打开应用|满足启动条件)/u.test(
+      segment,
+    ),
+  )
+    ? []
+    : prefix;
+}
+function safeBatchStem(value, index, used) {
+  const base =
+    oneLine(value)
+      .normalize("NFKC")
+      .replace(/[<>:"\/\\|?*\u0000-\u001F]/gu, "-")
+      .replace(/\s+/gu, "_")
+      .replace(/-+/gu, "-")
+      .replace(/^[-_.]+|[-_.]+$/gu, "")
+      .slice(0, 72) || "area";
+  const prefix = `${String(index + 1).padStart(3, "0")}-${base}`;
+  let candidate = prefix;
+  let suffix = 2;
+  while (used.has(candidate) || candidate === "." || candidate === "..") {
+    candidate = `${prefix}-${suffix}`;
+    suffix += 1;
+  }
+  used.add(candidate);
+  return candidate;
+}
+function pagePathForArea(area) {
+  if (area.canonicalPath.status === "resolved") {
+    const values = area.canonicalPath.segments
+      .map((segment) => oneLine(segment.areaName))
+      .filter((value) => value.length > 0);
+    return [...new Set(values)];
+  }
+  // An unresolved or unreachable Area has no verified route.  Returning its
+  // display name here would make the manifest look like a confirmed path;
+  // leave it empty and let the batch warning make the uncertainty visible.
+  return [];
+}
+function areaNameFor(area) {
+  if (area.displayName.status !== "resolved") return undefined;
+  const value = oneLine(area.displayName.value);
+  return value.length > 0 ? value : undefined;
+}
+function featureIdFor(source, index) {
+  const explicit = source.featureIds?.[index];
+  return explicit === undefined || explicit.length === 0 ? undefined : explicit;
+}
+function preconditionsFromHeaders(headers, warnings, sourceLabel) {
+  const values = [];
+  for (const header of headers) {
+    const line = oneLine(header);
+    const kind = metadataKind(line);
+    if (kind === "precondition") {
+      const value = metadataValue(line);
+      if (value.length > 0) values.push(value);
+    } else if (kind === "path" || kind === "description") {
+      // Explicitly discard the old Area metadata.  It is not a requirement
+      // title and would become a phantom requirement in parse_requirements.mjs.
+      continue;
+    } else if (line.length > 0) {
+      warnings.push(`${sourceLabel}: discarded an unknown Area header`);
+    }
+  }
+  return uniqueNonEmpty(values);
+}
+function normalizeFeatureEntry(
+  feature,
+  preconditions,
+  id,
+  warnings,
+  sourceLabel,
+  sourceIndex,
+  sourceFeatureId,
+) {
+  let title = normalizeTitle(feature.title);
+  if (title.length === 0) {
+    warnings.push(
+      `${sourceLabel}: feature ${sourceIndex + 1} has no title and was skipped`,
+    );
+    return undefined;
+  }
+  let body = normalizeBody(feature.body);
+  if (body.length === 0) {
+    warnings.push(
+      `${sourceLabel}: ${title} has an empty body; it is kept for source-side completion`,
+    );
+  }
+  const prefix =
+    preconditions.length === 0 ? "" : `前置条件：${preconditions.join("；")}`;
+  if (prefix.length > 0 && !body.startsWith(prefix)) {
+    body = body.length > 0 ? `${prefix}\n${body}` : prefix;
+  }
+  // A title is a single parser line.  If a legacy producer put an Area or
+  // precondition label in that position, remove it rather than handing a
+  // machine header to the spec skill.
+  if (metadataKind(title) === "precondition") {
+    warnings.push(`${sourceLabel}: metadata-only feature was skipped`);
+    return undefined;
+  }
+  for (const prefixLabel of METADATA_PREFIXES) {
+    const metadataPrefix = new RegExp(`^${prefixLabel}\\s*[:：]`, "u");
+    if (metadataPrefix.test(title))
+      title = title.replace(metadataPrefix, "").trim();
+  }
+  if (title.length === 0) {
+    warnings.push(`${sourceLabel}: metadata-only feature was skipped`);
+    return undefined;
+  }
+  return {
+    id,
+    title,
+    body,
+    ...(sourceFeatureId === undefined ? {} : { sourceFeatureId }),
+  };
+}
+/**
+ * Pure conversion from merged Area content to one spec-generator page batch
+ * per Area.  Keeping one Area per input file is intentional: the downstream
+ * skill rejects a file whose requirements belong to different owning pages.
+ */
+export function buildSpecInputBatches(sources) {
+  const usedStems = new Set();
+  return sources.flatMap((source, sourceIndex) => {
+    const warnings = [];
+    const sourceLabel =
+      source.sourceFile ?? source.areaId ?? `Area ${sourceIndex + 1}`;
+    const headers = preconditionsFromHeaders(
+      source.content.headerLines,
+      warnings,
+      sourceLabel,
+    );
+    const requirements = source.content.features.flatMap(
+      (feature, featureIndex) => {
+        const explicitId = featureIdFor(source, featureIndex);
+        const id =
+          explicitId === undefined
+            ? `${source.areaId ?? `area-${sourceIndex + 1}`}#${featureIndex + 1}`
+            : `${source.areaId ?? `area-${sourceIndex + 1}`}#${explicitId}`;
+        const requirement = normalizeFeatureEntry(
+          feature,
+          headers,
+          id,
+          warnings,
+          sourceLabel,
+          featureIndex,
+          explicitId,
+        );
+        return requirement === undefined ? [] : [requirement];
+      },
+    );
+    if (requirements.length === 0) {
+      warnings.push(`${sourceLabel}: no requirement was emitted for this Area`);
+      return [];
+    }
+    const firstTitle = requirements[0]?.title;
+    const owningPage =
+      oneLine(
+        source.areaName ??
+          (firstTitle === undefined ? "" : (inferAreaName(firstTitle) ?? "")),
+      ) || "__shared_capability__";
+    const pagePath =
+      source.pagePath === undefined
+        ? firstTitle === undefined
+          ? []
+          : inferPagePath(firstTitle, owningPage)
+        : uniqueNonEmpty(source.pagePath);
+    if (pagePath.length === 0 && owningPage !== "__shared_capability__") {
+      warnings.push(
+        `${sourceLabel}: page-path was not available without a verified Stage 1 graph`,
+      );
+    }
+    const stem = safeBatchStem(owningPage, sourceIndex, usedStems);
+    const text = `${requirements.map((item) => (item.body.length > 0 ? `${item.title}\n${item.body}` : item.title)).join("\n\n")}\n`;
+    return [
+      {
+        batchId: stem,
+        ...(source.areaId === undefined ? {} : { areaId: source.areaId }),
+        owningPage,
+        pagePath,
+        requirements,
+        text,
+        ...(source.sourceFile === undefined
+          ? {}
+          : { sourceFile: source.sourceFile }),
+        warnings,
+      },
+    ];
+  });
+}
+async function isFile(file) {
+  try {
+    return (await stat(file)).isFile();
+  } catch {
+    return false;
+  }
+}
+async function isDirectory(directory) {
+  try {
+    return (await stat(directory)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function hasStage2Markers(directory) {
+  try {
+    const entries = await readdir(directory, { withFileTypes: true });
+    return entries.some(
+      (entry) =>
+        (entry.isFile() &&
+          (/^(?:req|REQ)(?:-\d+)?\.txt$/u.test(entry.name) ||
+            entry.name === "req.md" ||
+            entry.name === "render-manifest.json")) ||
+        (entry.isDirectory() && entry.name === "rendering"),
+    );
+  } catch {
+    return false;
+  }
+}
+/**
+ * Resolve the conventional Stage 2 directory without making callers of the
+ * text-only compatibility path know whether they were handed a complete
+ * Stage 1 run or the `generation/` directory itself.  An explicitly supplied
+ * `stage2Directory` always wins; otherwise a real `<input>/generation`
+ * directory is preferred, and a directory that already contains Stage 2
+ * files is used as-is.
+ */
+async function resolveStage2Directory(inputDirectory, explicitDirectory) {
+  if (explicitDirectory !== undefined) return path.resolve(explicitDirectory);
+  const conventional = path.join(inputDirectory, "generation");
+  if (await isDirectory(conventional)) return conventional;
+  if (await hasStage2Markers(inputDirectory)) return inputDirectory;
+  // Let readTextSources produce the more specific missing-directory error.
+  return conventional;
+}
+async function readTextSources(stage2Directory) {
+  let entries;
+  try {
+    entries = await readdir(stage2Directory, { withFileTypes: true });
+  } catch (error) {
+    throw new Error(
+      `Stage 2 output directory does not exist: ${stage2Directory}`,
+      { cause: error },
+    );
+  }
+  const numbered = entries
+    .filter((entry) => entry.isFile() && /^req-\d+\.txt$/iu.test(entry.name))
+    .sort(
+      (left, right) =>
+        Number(left.name.match(/\d+/u)?.[0] ?? 0) -
+        Number(right.name.match(/\d+/u)?.[0] ?? 0),
+    );
+  const legacy = entries
+    .filter(
+      (entry) =>
+        entry.isFile() && /^(?:REQ|req)(?:-\d+)?\.txt$/u.test(entry.name),
+    )
+    .filter((entry) => !numbered.some((item) => item.name === entry.name))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const selected = numbered.length > 0 ? numbered : legacy;
+  if (selected.length > 0) {
+    return Promise.all(
+      selected.map(async (entry) => ({
+        file: entry.name,
+        text: await readFile(path.join(stage2Directory, entry.name), "utf8"),
+      })),
+    );
+  }
+  const markdown = path.join(stage2Directory, "req.md");
+  if (await isFile(markdown)) {
+    return [{ file: "req.md", text: await readFile(markdown, "utf8") }];
+  }
+  return [];
+}
+function idsForModel(reqModel) {
+  return {
+    areaIds: new Set(reqModel.areas.map((area) => area.id)),
+    featureIds: new Set(
+      reqModel.areas.flatMap((area) =>
+        area.features.map((feature) => feature.id),
+      ),
+    ),
+  };
+}
+async function detectRenderMode(stage2Directory, reqModel, requested) {
+  if (requested !== "auto") return requested;
+  const ids = idsForModel(reqModel);
+  const manifestPath = path.join(stage2Directory, "render-manifest.json");
+  if (await isFile(manifestPath)) {
+    try {
+      const value = JSON.parse(await readFile(manifestPath, "utf8"));
+      const entryIds = (value.entries ?? [])
+        .map((entry) => (typeof entry.id === "string" ? entry.id : undefined))
+        .filter((id) => id !== undefined);
+      const area = entryIds.some((id) => ids.areaIds.has(id));
+      const feature = entryIds.some((id) => ids.featureIds.has(id));
+      if (area && !feature) return "area";
+      if (feature && !area) return "feature";
+    } catch {
+      // A malformed optional manifest should not hide valid output.json files.
+    }
+  }
+  const renderDir = path.join(stage2Directory, "rendering");
+  for (const area of reqModel.areas) {
+    if (await isFile(path.join(renderDir, areaDirFor(area.id), "output.json")))
+      return "area";
+    if (
+      await Promise.all(
+        area.features.map((feature) =>
+          isFile(path.join(renderDir, renderDirFor(feature.id), "output.json")),
+        ),
+      ).then((values) => values.some(Boolean))
+    )
+      return "feature";
+  }
+  return "text";
+}
+async function collectAreaResults(renderDirectory, reqModel) {
+  const pairs = await Promise.all(
+    reqModel.areas.map(async (area) => {
+      const result = await readAreaAttempt(
+        path.join(renderDirectory, areaDirFor(area.id), "output.json"),
+      );
+      // The directory name is the primary association, but finalized Area
+      // output must also carry the same non-empty embedded id.  A copied or
+      // malformed output.json must not silently overwrite another Area's
+      // requirements.
+      if (
+        result === undefined ||
+        typeof result.areaId !== "string" ||
+        result.areaId.length === 0 ||
+        result.areaId !== area.id
+      ) {
+        return undefined;
+      }
+      return [area.id, result];
+    }),
+  );
+  return new Map(pairs.filter((pair) => pair !== undefined));
+}
+async function collectFeatureResults(renderDirectory, reqModel) {
+  const pairs = await Promise.all(
+    reqModel.areas.flatMap((area) =>
+      area.features.map(async (feature) => {
+        const result = await readAttempt(
+          path.join(renderDirectory, renderDirFor(feature.id), "output.json"),
+        );
+        return result === undefined ? undefined : [feature.id, result];
+      }),
+    ),
+  );
+  return new Map(pairs.filter((pair) => pair !== undefined));
+}
+function sourceFromMerged(merged, reqModel) {
+  const areas = new Map(reqModel.areas.map((area) => [area.id, area]));
+  return merged.flatMap((entry) => {
+    const area = areas.get(entry.areaId);
+    if (area === undefined) return [];
+    const remaining = [...area.features];
+    const featureIds = entry.content.features.map((feature) => {
+      const title = normalizeTitle(feature.title);
+      const matchIndex = remaining.findIndex((candidate) => {
+        const name =
+          candidate.displayName.status === "resolved"
+            ? oneLine(candidate.displayName.value)
+            : "";
+        return (
+          name.length > 0 &&
+          (title.endsWith(` - ${name}`) || title.includes(` - ${name} - `))
+        );
+      });
+      if (matchIndex < 0) return undefined;
+      const [match] = remaining.splice(matchIndex, 1);
+      return match?.id;
+    });
+    return [
+      {
+        areaId: area.id,
+        areaName: areaNameFor(area),
+        pagePath: pagePathForArea(area),
+        content: entry.content,
+        featureIds,
+      },
+    ];
+  });
+}
+function knownTitlesFor(reqModel, graph) {
+  return new Set(
+    reqModel.areas.flatMap((area) =>
+      buildAreaContentTxt(area, graph).features.map((feature) =>
+        normalizeTitle(feature.title),
+      ),
+    ),
+  );
+}
+function matchAreaForTitle(title, reqModel, graph) {
+  const normalized = normalizeTitle(title);
+  const comparable = comparableTitle(normalized);
+  const exact = reqModel.areas.find((area) =>
+    buildAreaContentTxt(area, graph).features.some(
+      (feature) => comparableTitle(feature.title) === comparable,
+    ),
+  );
+  if (exact !== undefined) return exact;
+  const candidates = reqModel.areas.filter((area) => {
+    const name = areaNameFor(area);
+    return name !== undefined && titleSegments(normalized).includes(name);
+  });
+  return candidates.length === 1 ? candidates[0] : undefined;
+}
+function sourcesFromText(
+  textSources,
+  reqModel,
+  graph,
+  includeUnreachableAreas,
+) {
+  const warnings = [];
+  const known =
+    reqModel === undefined || graph === undefined
+      ? new Set()
+      : knownTitlesFor(reqModel, graph);
+  const grouped = new Map();
+  for (const source of textSources) {
+    const parsed = parseStage2ReqText(source.text, source.file, known);
+    warnings.push(...parsed.warnings);
+    for (const entry of parsed.entries) {
+      const area =
+        reqModel === undefined || graph === undefined
+          ? undefined
+          : matchAreaForTitle(entry.title, reqModel, graph);
+      if (reqModel !== undefined && area === undefined) {
+        warnings.push(
+          `${source.file} block ${entry.sourceIndex}: title could not be matched to a Stage 1 Area; page metadata is inferred`,
+        );
+      }
+      const inferredName =
+        area === undefined
+          ? (inferAreaName(entry.title) ?? source.file)
+          : (areaNameFor(area) ?? inferAreaName(entry.title) ?? source.file);
+      const key = area?.id ?? `${source.file}:${inferredName}`;
+      const current = grouped.get(key);
+      if (current === undefined) {
+        grouped.set(key, {
+          ...(area === undefined ? {} : { area }),
+          file: source.file,
+          preconditions: [...entry.preconditions],
+          features: [{ title: entry.title, body: entry.body }],
+        });
+      } else {
+        current.features.push({ title: entry.title, body: entry.body });
+        current.preconditions.push(...entry.preconditions);
+      }
+    }
+  }
+  const groups = [...grouped.entries()];
+  const orderedGroups =
+    reqModel === undefined
+      ? groups
+      : [
+          ...groups.filter(
+            ([, group]) => group.area?.canonicalPath.status !== "unreachable",
+          ),
+          ...groups.filter(
+            ([, group]) => group.area?.canonicalPath.status === "unreachable",
+          ),
+        ];
+  const sources = [];
+  for (const [key, group] of orderedGroups) {
+    if (
+      !includeUnreachableAreas &&
+      group.area?.canonicalPath.status === "unreachable"
+    ) {
+      warnings.push(
+        `${group.file}: dropped unreachable Area ${areaNameFor(group.area) ?? group.area.id}`,
+      );
+      continue;
+    }
+    const area = group.area;
+    const headers = uniqueNonEmpty(group.preconditions).map(
+      (value) => `前置条件：${value}`,
+    );
+    sources.push({
+      ...(area === undefined
+        ? { areaId: key }
+        : {
+            areaId: area.id,
+            areaName: areaNameFor(area),
+            pagePath: pagePathForArea(area),
+          }),
+      content: { headerLines: headers, features: group.features },
+      sourceFile: group.file,
+    });
+  }
+  if (sources.length > 0)
+    warnings.push(
+      "使用了 req-N.txt/req.md 兼容解析；建议在下一次 Stage 2 运行中保留 rendering/output.json 以获得结构化合并",
+    );
+  return { sources, warnings };
+}
+async function loadStage1IfAvailable(inputDirectory) {
+  const required = ["run-report.json", "req-model.json", "area-graph.json"];
+  const available = await Promise.all(
+    required.map((name) => isFile(path.join(inputDirectory, name))),
+  );
+  if (!available.every(Boolean)) return undefined;
+  const loaded = await loadStage2InputWithReport(inputDirectory);
+  const graph = await loadStage2AreaGraph(
+    inputDirectory,
+    loaded.report,
+    loaded.reqModel,
+  );
+  const completeness =
+    loaded.report.semanticCompleteness ?? loaded.reqModel.semanticCompleteness;
+  return {
+    reqModel: sortAreasReachableFirst(loaded.reqModel),
+    graph,
+    ...(completeness !== undefined && completeness !== "complete"
+      ? {
+          semanticWarning: `Stage 1 标记为 ${completeness}；本 handoff 保留该质量提示，未伪装为完整分析`,
+        }
+      : {}),
+  };
+}
+async function readReportMetadata(inputDirectory) {
+  try {
+    const value = JSON.parse(
+      await readFile(path.join(inputDirectory, "run-report.json"), "utf8"),
+    );
+    return {
+      ...(typeof value.caseId === "string" ? { caseId: value.caseId } : {}),
+      ...(typeof value.runId === "string" ? { runId: value.runId } : {}),
+    };
+  } catch {
+    return {};
+  }
+}
+async function replaceOutputDirectory(outputDirectory, replace) {
+  const absolute = path.resolve(outputDirectory);
+  if (absolute === path.parse(absolute).root || absolute === process.cwd()) {
+    throw new Error(
+      `Refusing to use a broad handoff output directory: ${absolute}`,
+    );
+  }
+  let exists = false;
+  try {
+    exists = (await stat(absolute)).isDirectory();
+  } catch {
+    // The directory will be created below.
+  }
+  if (exists) {
+    const entries = await readdir(absolute);
+    if (entries.length > 0 && !replace) {
+      throw new Error(
+        `Handoff output directory is not empty: ${absolute}; pass --replace to regenerate it`,
+      );
+    }
+    if (replace) await rm(absolute, { recursive: true, force: true });
+  }
+  await mkdir(absolute, { recursive: true });
+}
+function relativePath(from, to) {
+  const value = path.relative(from, to).replaceAll(path.sep, "/");
+  return value.length === 0 ? "." : value;
+}
+/**
+ * Export a completed Stage 2 run as page-local `REQ.txt` batches consumable by
+ * `$a2h-spec-generate`.  The exporter never invokes a model or UTG/StageM;
+ * it only adapts the already finalized Lint + Stage 2 result.
+ */
+export async function exportSpecHandoff(options) {
+  const inputDirectory = path.resolve(options.inputDirectory);
+  const stage2Directory = await resolveStage2Directory(
+    inputDirectory,
+    options.stage2Directory,
+  );
+  const outputDirectory = path.resolve(
+    options.outputDirectory ?? path.join(stage2Directory, "spec-input"),
+  );
+  if (
+    outputDirectory === stage2Directory ||
+    outputDirectory === inputDirectory
+  ) {
+    throw new Error(
+      "Spec handoff output must be a separate directory from Stage 1/Stage 2 input",
+    );
+  }
+  const isAncestor = (parent, child) =>
+    child.startsWith(`${parent}${path.sep}`);
+  if (
+    isAncestor(outputDirectory, inputDirectory) ||
+    isAncestor(outputDirectory, stage2Directory)
+  ) {
+    throw new Error(
+      "Spec handoff output cannot contain the Stage 1 or Stage 2 input directory",
+    );
+  }
+  const requestedMode = options.mode ?? "auto";
+  const loaded = await loadStage1IfAvailable(inputDirectory);
+  const warnings = [];
+  let textSources = [];
+  try {
+    textSources = await readTextSources(stage2Directory);
+  } catch (error) {
+    if (loaded === undefined) throw error;
+    warnings.push("未找到 Stage 2 输出目录，将使用 Stage 1 确定性草稿");
+  }
+  let sources = [];
+  let selectedMode = "text";
+  let structuredModeAttempted = false;
+  if (loaded !== undefined && requestedMode !== "text") {
+    selectedMode = await detectRenderMode(
+      stage2Directory,
+      loaded.reqModel,
+      requestedMode,
+    );
+    if (selectedMode === "area" || selectedMode === "feature") {
+      const sorted = loaded.reqModel;
+      const renderable = filterRenderableAreas(sorted);
+      const renderDirectory = path.join(stage2Directory, "rendering");
+      if (selectedMode === "area") {
+        const areaResults = await collectAreaResults(
+          renderDirectory,
+          renderable,
+        );
+        if (areaResults.size > 0 || textSources.length === 0) {
+          structuredModeAttempted = true;
+          const merged = mergeAreaReqContents(
+            sorted,
+            renderable,
+            areaResults,
+            loaded.graph,
+            {
+              includeUnreachableAreas: options.includeUnreachableAreas ?? false,
+            },
+          );
+          sources = sourceFromMerged(merged, sorted);
+        }
+      } else {
+        const featureResults = await collectFeatureResults(
+          renderDirectory,
+          renderable,
+        );
+        if (featureResults.size > 0 || textSources.length === 0) {
+          structuredModeAttempted = true;
+          const merged = mergeReqContents(
+            sorted,
+            renderable,
+            featureResults,
+            loaded.graph,
+            {
+              includeUnreachableAreas: options.includeUnreachableAreas ?? false,
+            },
+          );
+          sources = sourceFromMerged(merged, sorted);
+        }
+      }
+      if (sources.length === 0 && textSources.length > 0) {
+        warnings.push(
+          structuredModeAttempted
+            ? "结构化 rendering 已被读取但没有可发布的 Area；不会用旧文本复活已过滤的内容"
+            : "结构化 rendering 输出为空，回退到已有 req 文本",
+        );
+      }
+    }
+  }
+  if (
+    sources.length === 0 &&
+    textSources.length > 0 &&
+    !structuredModeAttempted
+  ) {
+    const textResult = sourcesFromText(
+      textSources,
+      loaded?.reqModel,
+      loaded?.graph,
+      options.includeUnreachableAreas ?? false,
+    );
+    sources = textResult.sources;
+    warnings.push(...textResult.warnings);
+    selectedMode = "text";
+  }
+  if (sources.length === 0 && loaded !== undefined) {
+    // A Stage 1-only directory is still exportable, but make the quality
+    // degradation observable: this is a deterministic draft, not an Agent
+    // rendered Stage 2 result.
+    const sorted = loaded.reqModel;
+    const renderable = filterRenderableAreas(sorted);
+    const fallbackSources = sorted.areas.flatMap((area) => {
+      const content = buildAreaContentTxt(area, loaded.graph);
+      if (
+        content.features.length === 0 ||
+        !renderable.areas.some((candidate) => candidate.id === area.id)
+      )
+        return [];
+      return [
+        {
+          areaId: area.id,
+          areaName: areaNameFor(area),
+          pagePath: pagePathForArea(area),
+          content,
+          featureIds: area.features.map((feature) => feature.id),
+        },
+      ];
+    });
+    sources = fallbackSources;
+    selectedMode = "text";
+    warnings.push(
+      "未找到 finalized Stage 2 输出；导出了 Stage 1 确定性草稿，请在交给 spec 前确认正文",
+    );
+  }
+  if (sources.length === 0) {
+    throw new Error(`No Stage 2 requirements found under ${stage2Directory}`);
+  }
+  if (loaded?.semanticWarning !== undefined)
+    warnings.push(loaded.semanticWarning);
+  const built = buildSpecInputBatches(sources);
+  warnings.push(...built.flatMap((batch) => batch.warnings));
+  if (built.length === 0)
+    throw new Error("Stage 2 output contains no non-empty requirement batch");
+  await replaceOutputDirectory(outputDirectory, options.replace ?? false);
+  const manifestBatches = [];
+  for (const batch of built) {
+    const batchDirectory = path.join(outputDirectory, batch.batchId);
+    await mkdir(batchDirectory, { recursive: true });
+    const requirementFile = `${batch.batchId}/REQ.txt`;
+    validateSpecInputText(batch.text, batch.requirements.length);
+    await writeFile(path.join(batchDirectory, "REQ.txt"), batch.text, "utf8");
+    if (/^(?:访问路径|区域说明)\s*[:：]/mu.test(batch.text)) {
+      throw new Error(
+        `Generated spec input still contains Stage 2 Area metadata: ${requirementFile}`,
+      );
+    }
+    manifestBatches.push({
+      batchId: batch.batchId,
+      ...(batch.areaId === undefined ? {} : { areaId: batch.areaId }),
+      owningPage: batch.owningPage,
+      pagePath: batch.pagePath,
+      requirementFile,
+      requirementCount: batch.requirements.length,
+      requirementIds: batch.requirements.map((requirement) => requirement.id),
+      ...(batch.sourceFile === undefined
+        ? {}
+        : { sourceFile: batch.sourceFile }),
+    });
+  }
+  const reportMetadata = await readReportMetadata(inputDirectory);
+  const manifest = {
+    contractVersion: SPEC_HANDOFF_CONTRACT_VERSION,
+    artifactKind: "spec-handoff-manifest",
+    inputFormat: SPEC_INPUT_FORMAT,
+    source: {
+      ...(loaded === undefined
+        ? {}
+        : { stage1Directory: relativePath(outputDirectory, inputDirectory) }),
+      stage2Directory: relativePath(outputDirectory, stage2Directory),
+      mode: selectedMode,
+    },
+    ...(reportMetadata.caseId === undefined
+      ? {}
+      : { caseId: reportMetadata.caseId }),
+    ...(reportMetadata.runId === undefined
+      ? {}
+      : { runId: reportMetadata.runId }),
+    batches: manifestBatches,
+    warnings: [...new Set(warnings)],
+  };
+  const manifestPath = path.join(outputDirectory, "manifest.json");
+  await writeFile(
+    manifestPath,
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8",
+  );
+  return { outputDirectory, manifestPath, manifest };
+}