android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/orchestrate.js

@@ -0,0 +1,1324 @@
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildAreaExpected,
+  buildAreaInputMd,
+  buildAreaTaskMdForSubagent,
+  buildFeatureExpected,
+  buildInputMd,
+  buildTaskMdForSubagent,
+  featureTitleParts,
+  hasUnresolvedPathSegmentNames,
+} from "./prompt.js";
+import { stripLeadingTitle } from "./merge.js";
+import { runPool } from "./pool.js";
+import { computeShortIds } from "./short-id.js";
+import {
+  validateCitations,
+  validateRestatedFacts,
+  validateTitle,
+  validateTitleForMembers,
+} from "./validate.js";
+export function renderDirFor(requirementId) {
+  return requirementId.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+const TOOL_CALL_PATTERN =
+  /message=evaluated permission=(grep|read|glob) pattern=(?:"((?:[^"\\]|\\.)*)"|(\S+))/g;
+export function extractToolCalls(stderr) {
+  const calls = [];
+  for (const match of stderr.matchAll(TOOL_CALL_PATTERN)) {
+    const [, tool, quoted, bare] = match;
+    calls.push({
+      tool,
+      pattern: quoted !== undefined ? quoted.replace(/\\(.)/g, "$1") : bare,
+    });
+  }
+  return calls;
+}
+const RETRYABLE_REASONS = new Set(["execution-failed", "json-decode-error"]);
+function buildRetryPrompt(errorReason, errorMessage) {
+  const description =
+    errorReason === "json-decode-error"
+      ? `你上一次的回复没有提供合法的 JSON 代码块（解析错误：${errorMessage}）。`
+      : `你上一次的调用执行失败（错误：${errorMessage}）。`;
+  return `${description}请重新按照最初的 "# Output" 一节要求，只输出一个合法的 \`\`\`json 代码块，代码块之外不要有任何文字。`;
+}
+async function defaultSleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+function planEvent(opts, perFeature, total) {
+  return {
+    phase: "plan",
+    total,
+    mode: opts.launchMode,
+    perFeature,
+    projectRoot: opts.projectRoot,
+    ...(opts.inputDirectory === undefined
+      ? {}
+      : { inputDirectory: opts.inputDirectory }),
+    ...(opts.outputDirectory === undefined
+      ? {}
+      : { outputDirectory: opts.outputDirectory }),
+  };
+}
+async function appendStatusEvent(renderDir, event, clock) {
+  await appendFile(
+    path.join(renderDir, "status.ndjson"),
+    `${JSON.stringify({ timestamp: clock(), ...event })}\n`,
+    "utf8",
+  );
+}
+async function validateOutput(
+  output,
+  item,
+  projectRoot,
+  attempt,
+  toolCalls,
+  nameTrace,
+) {
+  const parts = featureTitleParts(item, nameTrace);
+  const citationsResult = await validateCitations(
+    output.citations ?? [],
+    projectRoot,
+  );
+  const restatedResult = validateRestatedFacts(
+    output.restatedFacts ?? {},
+    item.feature,
+  );
+  const titleResult =
+    output.title === undefined
+      ? { valid: false, problems: ["title-missing"] }
+      : validateTitle(output.title, parts);
+  const warnings = [
+    ...citationsResult.invalid.map((inv) => ({ source: "citation", ...inv })),
+    ...restatedResult.mismatches.map((field) => ({
+      source: "restatedFacts",
+      field,
+    })),
+    ...titleResult.problems.map((reason) => ({
+      source: "title",
+      reason,
+    })),
+  ];
+  return {
+    ...output,
+    body:
+      output.body === undefined
+        ? undefined
+        : stripLeadingTitle(output.body, parts.title),
+    status: "ok",
+    titleValid: titleResult.valid,
+    warnings,
+    citationsValid: citationsResult.valid,
+    invalidCitations: citationsResult.invalid,
+    restatedFactsValid: restatedResult.valid,
+    restatedFactsMismatches: restatedResult.mismatches,
+    toolCalls,
+    attempt,
+  };
+}
+async function persistAttempt(dir, attempt, dispatch) {
+  await writeFile(
+    path.join(dir, `attempt-${attempt}.stdout`),
+    dispatch.stdout,
+    "utf8",
+  );
+  await writeFile(
+    path.join(dir, `attempt-${attempt}.stderr`),
+    dispatch.stderr,
+    "utf8",
+  );
+  if (dispatch.stats !== undefined) {
+    await writeFile(
+      path.join(dir, `attempt-${attempt}.stats.json`),
+      JSON.stringify(dispatch.stats, null, 2),
+      "utf8",
+    );
+  }
+}
+async function attemptOnce(item, ctx, prompt, sessionId, attempt) {
+  const dispatch = await ctx.opts.backend.run({
+    prompt,
+    cwd: ctx.opts.projectRoot,
+    agentName: ctx.opts.agentName ?? "reqgen-renderer",
+    ...(sessionId === undefined ? {} : { sessionId }),
+  });
+  const toolCalls = extractToolCalls(dispatch.stderr);
+  if (dispatch.status !== "ok") {
+    return {
+      dispatch,
+      result: {
+        status: "error",
+        errorReason: dispatch.errorReason,
+        error: dispatch.error,
+        citationsValid: false,
+        restatedFactsValid: false,
+        toolCalls,
+        attempt,
+      },
+    };
+  }
+  const result = await validateOutput(
+    dispatch.output,
+    item,
+    ctx.opts.projectRoot,
+    attempt,
+    toolCalls,
+    ctx.opts.nameTrace,
+  );
+  return { dispatch, result };
+}
+async function finalizeAttempt(
+  dir,
+  renderDir,
+  requirementId,
+  result,
+  clock,
+  stats,
+) {
+  // finalized mirrors the marker reqgen-selfcheck.mjs's `finalize` subcommand
+  // sets for subagent mode (ADR-0005) — only true on an actual success, so
+  // snapshot.ts's readAttempt treats the two modes' output.json identically.
+  const finalizedResult = { ...result, finalized: result.status === "ok" };
+  await writeFile(
+    path.join(dir, "output.json"),
+    JSON.stringify(finalizedResult, null, 2),
+    "utf8",
+  );
+  await appendStatusEvent(
+    renderDir,
+    {
+      phase: "finish",
+      requirementId,
+      status: result.status,
+      attempt: result.attempt,
+      ...(stats ? { stats } : {}),
+    },
+    clock,
+  );
+  return finalizedResult;
+}
+export async function renderFeatureToDisk(item, ctx) {
+  const maxRetries = ctx.opts.maxRetries ?? 5;
+  const backoffMs = ctx.opts.backoffMs ?? 5000;
+  const sleepFn = ctx.opts.sleepFn ?? defaultSleep;
+  const clock = ctx.opts.clock ?? Date.now;
+  const dir = path.join(ctx.opts.renderDir, renderDirFor(item.feature.id));
+  await mkdir(dir, { recursive: true });
+  const inputMd = buildInputMd(
+    item,
+    ctx.reqModel,
+    ctx.promptContext,
+    ctx.opts.gapAuditLinks,
+    ctx.opts.nameTrace,
+  );
+  await writeFile(path.join(dir, "input.md"), inputMd, "utf8");
+  let attempt = 1;
+  let sessionId;
+  let prompt = inputMd;
+  while (true) {
+    await appendStatusEvent(
+      ctx.opts.renderDir,
+      {
+        phase: "start",
+        requirementId: item.feature.id,
+        attempt,
+      },
+      clock,
+    );
+    const { dispatch, result } = await attemptOnce(
+      item,
+      ctx,
+      prompt,
+      sessionId,
+      attempt,
+    );
+    sessionId = dispatch.sessionId ?? sessionId;
+    await persistAttempt(dir, attempt, dispatch);
+    const canRetry =
+      dispatch.status !== "ok" &&
+      dispatch.errorReason !== undefined &&
+      RETRYABLE_REASONS.has(dispatch.errorReason) &&
+      attempt <= maxRetries;
+    if (!canRetry) {
+      return finalizeAttempt(
+        dir,
+        ctx.opts.renderDir,
+        item.feature.id,
+        result,
+        clock,
+        dispatch.stats,
+      );
+    }
+    const delayMs = backoffMs * 2 ** (attempt - 1);
+    await appendStatusEvent(
+      ctx.opts.renderDir,
+      {
+        phase: "retry-scheduled",
+        requirementId: item.feature.id,
+        attempt: attempt + 1,
+        reason: dispatch.errorReason,
+        delayMs,
+        retryAt: clock() + delayMs,
+      },
+      clock,
+    );
+    await sleepFn(delayMs);
+    prompt = buildRetryPrompt(dispatch.errorReason, dispatch.error);
+    attempt += 1;
+  }
+}
+export { runPool } from "./pool.js";
+export function expandRenderItems(reqModel) {
+  return reqModel.areas.flatMap((area) =>
+    area.features.map((feature) => ({ area, feature })),
+  );
+}
+export async function renderAllFeatures(items, reqModel, opts) {
+  const clock = opts.clock ?? Date.now;
+  await mkdir(opts.renderDir, { recursive: true });
+  await writeFile(path.join(opts.renderDir, "status.ndjson"), "", "utf8");
+  await appendStatusEvent(
+    opts.renderDir,
+    planEvent(opts, true, items.length),
+    clock,
+  );
+  const ctx = {
+    reqModel,
+    promptContext: {
+      projectRoot: opts.projectRoot,
+      module: reqModel.analysisContext.applicationModule,
+      variant: reqModel.analysisContext.buildVariant,
+      analysisMode: opts.analysisMode,
+    },
+    opts,
+  };
+  const results = new Map();
+  await runPool(items, opts.concurrency ?? 4, async (item) => {
+    let result;
+    try {
+      result = await renderFeatureToDisk(item, ctx);
+    } catch (error) {
+      result = {
+        status: "error",
+        error: error instanceof Error ? error.message : String(error),
+        citationsValid: false,
+        restatedFactsValid: false,
+        attempt: 0,
+      };
+      await appendStatusEvent(
+        opts.renderDir,
+        {
+          phase: "finish",
+          requirementId: item.feature.id,
+          status: result.status,
+        },
+        clock,
+      );
+    }
+    results.set(item.feature.id, result);
+  });
+  return results;
+}
+// =============================================================================
+// Per-Area rendering (one session per Area)
+// =============================================================================
+export function areaDirFor(areaId) {
+  return areaId.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+function resolveAreaKind(area) {
+  if (area.canonicalPath.status === "unreachable") return "unreachable";
+  if (hasUnresolvedPathSegmentNames(area)) return "path-needs-names";
+  return "normal";
+}
+export function expandAreaRenderItems(reqModel) {
+  return reqModel.areas.map((area) => ({ area }));
+}
+/** Every requirementId a single AreaRenderOutput.features entry covers: just
+ * its own `requirementId` normally, or every id listed in
+ * `mergedRequirementIds` (including its own) when the Agent merged several
+ * Controls into one req item — see FeatureRenderResult.mergedRequirementIds. */
+function coveredRequirementIds(entry) {
+  return entry.mergedRequirementIds !== undefined &&
+    entry.mergedRequirementIds.length > 0
+    ? entry.mergedRequirementIds
+    : [entry.requirementId ?? ""];
+}
+function isAgentAddedFeature(entry) {
+  return entry.kind === "agent-added";
+}
+async function validateAgentAddedFeature(featureOutput, projectRoot) {
+  const citations = featureOutput.citations ?? [];
+  const citationsResult = await validateCitations(citations, projectRoot);
+  const title = featureOutput.title?.trim();
+  const body = featureOutput.body?.trim();
+  const error =
+    title === undefined || title.length === 0
+      ? "agent-added-feature-title-missing"
+      : body === undefined || body.length === 0
+        ? "agent-added-feature-body-missing"
+        : citations.length === 0
+          ? "agent-added-feature-citations-missing"
+          : citationsResult.valid
+            ? undefined
+            : "agent-added-feature-citations-invalid";
+  return {
+    status: error === undefined ? "ok" : "error",
+    ...(error === undefined ? {} : { error }),
+    ...(title === undefined || title.length === 0
+      ? {}
+      : { title: featureOutput.title }),
+    ...(body === undefined || body.length === 0
+      ? {}
+      : { body: featureOutput.body }),
+    ...(featureOutput.citations === undefined
+      ? {}
+      : { citations: featureOutput.citations }),
+    ...(featureOutput.confidence === undefined
+      ? {}
+      : { confidence: featureOutput.confidence }),
+    citationsValid: citationsResult.valid,
+    ...(citationsResult.invalid.length === 0
+      ? {}
+      : { invalidCitations: citationsResult.invalid }),
+  };
+}
+/** `members` is every Feature this one output entry covers, in Area.features
+ * order — length 1 for the ordinary one-Feature case, length > 1 for a
+ * merged req item. restatedFacts is checked against `members[0]` (the
+ * earliest member in Area order, deterministic regardless of how the Agent
+ * ordered mergedRequirementIds); title is checked against every member's own
+ * name-inclusion requirement (validateTitleForMembers) so a merged title
+ * must still name each Control it covers. */
+async function validateFeatureOutput(
+  featureOutput,
+  members,
+  projectRoot,
+  nameTrace,
+) {
+  const citationsResult = await validateCitations(
+    featureOutput.citations ?? [],
+    projectRoot,
+  );
+  const restatedResult = validateRestatedFacts(
+    featureOutput.restatedFacts ?? {},
+    members[0].feature,
+  );
+  const partsList = members.map((member) =>
+    featureTitleParts(member, nameTrace),
+  );
+  const titleResult =
+    featureOutput.title === undefined
+      ? { valid: false, problems: ["title-missing"] }
+      : validateTitleForMembers(featureOutput.title, partsList);
+  const warnings = [
+    ...citationsResult.invalid.map((inv) => ({ source: "citation", ...inv })),
+    ...restatedResult.mismatches.map((field) => ({
+      source: "restatedFacts",
+      field,
+    })),
+    ...titleResult.problems.map((reason) => ({
+      source: "title",
+      reason,
+    })),
+  ];
+  // A merged entry's echoed leading-title-line (if any) is the Agent's own
+  // merged title, not any single member's individually computed template —
+  // there is no one template that represents the whole group.
+  const stripTitle =
+    members.length > 1
+      ? (featureOutput.title ?? partsList[0].title)
+      : partsList[0].title;
+  return {
+    status: "ok",
+    title: featureOutput.title,
+    titleValid: titleResult.valid,
+    body:
+      featureOutput.body === undefined
+        ? undefined
+        : stripLeadingTitle(featureOutput.body, stripTitle),
+    restatedFacts: featureOutput.restatedFacts,
+    citations: featureOutput.citations,
+    confidence: featureOutput.confidence,
+    citationsValid: citationsResult.valid,
+    invalidCitations: citationsResult.invalid,
+    restatedFactsValid: restatedResult.valid,
+    restatedFactsMismatches: restatedResult.mismatches,
+    warnings,
+    ...(members.length > 1
+      ? { mergedFeatureIds: members.map((m) => m.feature.id) }
+      : {}),
+  };
+}
+async function validateAreaOutput(output, item, projectRoot, nameTrace) {
+  const results = new Map();
+  const shortIds = computeShortIds(item.area.features);
+  const outputFeatures = output.features ?? [];
+  const hasFeatureError =
+    item.area.features.length === 0 && outputFeatures.length === 0
+      ? output.hasFeature === false
+        ? undefined
+        : "has-feature-marker-missing-in-agent-output"
+      : output.hasFeature === false
+        ? "has-feature-marker-conflicts-with-features"
+        : undefined;
+  const addedFeatures = await Promise.all(
+    outputFeatures
+      .filter(isAgentAddedFeature)
+      .map((featureOutput) =>
+        validateAgentAddedFeature(featureOutput, projectRoot),
+      ),
+  );
+  const byRequirementId = new Map();
+  for (const entry of outputFeatures) {
+    if (isAgentAddedFeature(entry)) continue;
+    for (const shortId of coveredRequirementIds(entry)) {
+      const group = byRequirementId.get(shortId);
+      if (group === undefined) {
+        byRequirementId.set(shortId, [entry]);
+      } else {
+        group.push(entry);
+      }
+    }
+  }
+  // A merge group's single FeatureOutput is validated once and its result
+  // shared by every member id it covers, instead of re-running citation/
+  // title checks once per member.
+  const evaluated = new Map();
+  for (const [index, feature] of item.area.features.entries()) {
+    const shortId = shortIds.get(feature.id);
+    const group = byRequirementId.get(shortId);
+    if (group === undefined) {
+      results.set(feature.id, {
+        status: "error",
+        error: "feature-missing-in-agent-output",
+        citationsValid: false,
+        restatedFactsValid: false,
+      });
+      continue;
+    }
+    if (group.length > 1) {
+      results.set(feature.id, {
+        status: "error",
+        error: "feature-id-collision-in-agent-output",
+        citationsValid: false,
+        restatedFactsValid: false,
+      });
+      continue;
+    }
+    const featureOutput = group[0];
+    const coveredIds = coveredRequirementIds(featureOutput);
+    const merged = coveredIds.length > 1;
+    // Redundant cross-check: requirementId is a real id, but a real id can
+    // still be attached to the wrong Feature's content (correct id, wrong
+    // pairing) without any duplicate ever occurring — controlIndex is an
+    // independent signal that must agree with the enumeration position this
+    // requirementId was given at. A disagreement here is exactly the
+    // PermissionAuthorizationDialog/UsbStorageFolderDialog mixup, caught
+    // instead of silently merged. Omitted controlIndex (older/custom
+    // backends) is not treated as a mismatch. Skipped for a merged entry —
+    // its controlIndex names just one representative member, not every
+    // covered position, so it is not a meaningful cross-check there.
+    if (
+      !merged &&
+      featureOutput.controlIndex !== undefined &&
+      featureOutput.controlIndex !== index + 1
+    ) {
+      results.set(feature.id, {
+        status: "error",
+        error: "feature-index-mismatch-in-agent-output",
+        citationsValid: false,
+        restatedFactsValid: false,
+      });
+      continue;
+    }
+    let evaluation = evaluated.get(featureOutput);
+    if (evaluation === undefined) {
+      const coveredIdSet = new Set(coveredIds);
+      const members = item.area.features
+        .filter((f) => coveredIdSet.has(shortIds.get(f.id)))
+        .map((f) => ({ area: item.area, feature: f }));
+      evaluation = validateFeatureOutput(
+        featureOutput,
+        members.length > 0 ? members : [{ area: item.area, feature }],
+        projectRoot,
+        nameTrace,
+      );
+      evaluated.set(featureOutput, evaluation);
+    }
+    results.set(feature.id, await evaluation);
+  }
+  return {
+    features: results,
+    addedFeatures,
+    ...(output.hasFeature === false && hasFeatureError === undefined
+      ? { hasFeature: false }
+      : {}),
+    ...(hasFeatureError === undefined ? {} : { error: hasFeatureError }),
+  };
+}
+async function attemptAreaOnce(item, ctx, prompt, sessionId, attempt) {
+  const dispatch = await ctx.opts.backend.run({
+    prompt,
+    cwd: ctx.opts.projectRoot,
+    agentName: ctx.opts.agentName ?? "reqgen-renderer",
+    ...(sessionId === undefined ? {} : { sessionId }),
+  });
+  const toolCalls = extractToolCalls(dispatch.stderr);
+  if (dispatch.status !== "ok") {
+    return {
+      dispatch,
+      result: {
+        status: "error",
+        errorReason: dispatch.errorReason,
+        error: dispatch.error,
+        areaId: item.area.id,
+        features: new Map(),
+        toolCalls,
+        attempt,
+      },
+    };
+  }
+  const output = dispatch.output;
+  const validated = await validateAreaOutput(
+    output,
+    item,
+    ctx.opts.projectRoot,
+    ctx.opts.nameTrace,
+  );
+  if (validated.error !== undefined) {
+    return {
+      dispatch,
+      result: {
+        status: "error",
+        error: validated.error,
+        areaId: item.area.id,
+        features: new Map(),
+        toolCalls,
+        attempt,
+      },
+    };
+  }
+  return {
+    dispatch,
+    result: {
+      status: "ok",
+      areaId: item.area.id,
+      ...(output.areaDescription === undefined
+        ? {}
+        : { areaDescription: output.areaDescription }),
+      ...(output.accessPath === undefined
+        ? {}
+        : { accessPath: output.accessPath }),
+      ...(output.reachable === undefined
+        ? {}
+        : { reachable: output.reachable }),
+      features: validated.features,
+      ...(validated.addedFeatures.length === 0
+        ? {}
+        : { addedFeatures: validated.addedFeatures }),
+      ...(validated.hasFeature === false ? { hasFeature: false } : {}),
+      toolCalls,
+      attempt,
+    },
+  };
+}
+async function finalizeAreaAttempt(dir, renderDir, result, clock, stats) {
+  // Convert Map to plain object for JSON serialization
+  const featuresObj = {};
+  for (const [id, featureResult] of result.features) {
+    featuresObj[id] = featureResult;
+  }
+  // finalized mirrors the marker reqgen-selfcheck.mjs's `finalize` subcommand
+  // sets for subagent mode (ADR-0005) — only true on an actual success, so
+  // snapshot.ts's readAreaAttempt treats the two modes' output.json
+  // identically.
+  const serializable = {
+    ...result,
+    finalized: result.status === "ok",
+    features: featuresObj,
+  };
+  await writeFile(
+    path.join(dir, "output.json"),
+    JSON.stringify(serializable, null, 2),
+    "utf8",
+  );
+  await appendStatusEvent(
+    renderDir,
+    {
+      phase: "finish",
+      areaId: result.areaId,
+      status: result.status,
+      attempt: result.attempt,
+      featureCount: result.features.size,
+      ...(stats ? { stats } : {}),
+    },
+    clock,
+  );
+  return { ...result, finalized: result.status === "ok" };
+}
+export async function renderAreaToDisk(item, ctx) {
+  const maxRetries = ctx.opts.maxRetries ?? 5;
+  const backoffMs = ctx.opts.backoffMs ?? 5000;
+  const sleepFn = ctx.opts.sleepFn ?? defaultSleep;
+  const clock = ctx.opts.clock ?? Date.now;
+  const dir = path.join(ctx.opts.renderDir, areaDirFor(item.area.id));
+  await mkdir(dir, { recursive: true });
+  const inputMd = buildAreaInputMd(
+    item,
+    ctx.reqModel,
+    ctx.promptContext,
+    ctx.opts.gapAuditLinks,
+    ctx.opts.nameTrace,
+  );
+  await writeFile(path.join(dir, "input.md"), inputMd, "utf8");
+  const kind = resolveAreaKind(item.area);
+  let attempt = 1;
+  let sessionId;
+  let prompt = inputMd;
+  while (true) {
+    await appendStatusEvent(
+      ctx.opts.renderDir,
+      {
+        phase: "start",
+        areaId: item.area.id,
+        attempt,
+        featureCount: item.area.features.length,
+        kind,
+      },
+      clock,
+    );
+    const { dispatch, result } = await attemptAreaOnce(
+      item,
+      ctx,
+      prompt,
+      sessionId,
+      attempt,
+    );
+    sessionId = dispatch.sessionId ?? sessionId;
+    await persistAttempt(dir, attempt, dispatch);
+    const canRetry =
+      dispatch.status !== "ok" &&
+      dispatch.errorReason !== undefined &&
+      RETRYABLE_REASONS.has(dispatch.errorReason) &&
+      attempt <= maxRetries;
+    if (!canRetry) {
+      return finalizeAreaAttempt(
+        dir,
+        ctx.opts.renderDir,
+        result,
+        clock,
+        dispatch.stats,
+      );
+    }
+    const delayMs = backoffMs * 2 ** (attempt - 1);
+    await appendStatusEvent(
+      ctx.opts.renderDir,
+      {
+        phase: "retry-scheduled",
+        areaId: item.area.id,
+        attempt: attempt + 1,
+        reason: dispatch.errorReason,
+        delayMs,
+        retryAt: clock() + delayMs,
+      },
+      clock,
+    );
+    await sleepFn(delayMs);
+    prompt = buildRetryPrompt(dispatch.errorReason, dispatch.error);
+    attempt += 1;
+  }
+}
+export async function renderAllAreas(items, reqModel, opts) {
+  const clock = opts.clock ?? Date.now;
+  await mkdir(opts.renderDir, { recursive: true });
+  await writeFile(path.join(opts.renderDir, "status.ndjson"), "", "utf8");
+  await appendStatusEvent(
+    opts.renderDir,
+    planEvent(opts, false, items.length),
+    clock,
+  );
+  const ctx = {
+    reqModel,
+    promptContext: {
+      projectRoot: opts.projectRoot,
+      module: reqModel.analysisContext.applicationModule,
+      variant: reqModel.analysisContext.buildVariant,
+      analysisMode: opts.analysisMode,
+    },
+    opts,
+  };
+  const results = new Map();
+  await runPool(items, opts.concurrency ?? 4, async (item) => {
+    let result;
+    try {
+      result = await renderAreaToDisk(item, ctx);
+    } catch (error) {
+      result = {
+        status: "error",
+        error: error instanceof Error ? error.message : String(error),
+        areaId: item.area.id,
+        features: new Map(),
+        attempt: 0,
+      };
+      await appendStatusEvent(
+        opts.renderDir,
+        {
+          phase: "finish",
+          areaId: item.area.id,
+          status: result.status,
+        },
+        clock,
+      );
+    }
+    results.set(item.area.id, result);
+  });
+  return results;
+}
+// =============================================================================
+// Unified protocol dispatch (ADR-0005, 2026-07-25 revision): writes task.md +
+// expected.json via the same prepare builders as subagent mode, spawns backend
+// with the taskPath, and checks output.json on disk for finalized:true instead
+// of parsing stdout. Only the claude backend uses this path; opencode and
+// --ai-command keep the legacy inline-prompt + validate.ts path.
+// =============================================================================
+async function readFinalizedFeatureOutput(outputPath) {
+  try {
+    const parsed = JSON.parse(await readFile(outputPath, "utf8"));
+    if (
+      parsed.finalized === true &&
+      parsed.status === "ok" &&
+      typeof parsed.body === "string"
+    ) {
+      return parsed;
+    }
+  } catch {
+    /* file missing or unreadable — not finalized */
+  }
+  return undefined;
+}
+async function readFinalizedAreaOutput(outputPath) {
+  try {
+    const parsed = JSON.parse(await readFile(outputPath, "utf8"));
+    if (parsed.status !== "ok" || parsed.finalized !== true) return undefined;
+    const features = new Map();
+    for (const [id, fr] of Object.entries(parsed.features ?? {})) {
+      if (fr.status === "ok" && typeof fr.body === "string")
+        features.set(id, fr);
+    }
+    return {
+      status: "ok",
+      areaId: parsed.areaId ?? "",
+      ...(parsed.areaDescription === undefined
+        ? {}
+        : { areaDescription: parsed.areaDescription }),
+      ...(parsed.accessPath === undefined
+        ? {}
+        : { accessPath: parsed.accessPath }),
+      ...(parsed.reachable === undefined
+        ? {}
+        : { reachable: parsed.reachable }),
+      features,
+      ...(parsed.addedFeatures === undefined
+        ? {}
+        : { addedFeatures: parsed.addedFeatures }),
+      ...(parsed.hasFeature === false ? { hasFeature: false } : {}),
+      attempt: parsed.attempt ?? 1,
+    };
+  } catch {
+    /* file missing or unreadable */
+  }
+  return undefined;
+}
+export async function renderFeatureUnified(item, ctx) {
+  const maxRetries = ctx.opts.maxRetries ?? 5;
+  const backoffMs = ctx.opts.backoffMs ?? 5000;
+  const sleepFn = ctx.opts.sleepFn ?? defaultSleep;
+  const clock = ctx.opts.clock ?? Date.now;
+  const dir = path.join(ctx.opts.renderDir, renderDirFor(item.feature.id));
+  await mkdir(dir, { recursive: true });
+  const checkScriptPath = defaultCheckScriptPath();
+  const outputPath = path.join(dir, "output.json");
+  const expectedPath = path.join(dir, "expected.json");
+  const taskPath = path.join(dir, "task.md");
+  const paths = { expectedPath, outputPath, checkScriptPath };
+  if (ctx.opts.resume) {
+    const existing = await readFinalizedFeatureOutput(outputPath);
+    if (existing !== undefined) {
+      await appendStatusEvent(
+        ctx.opts.renderDir,
+        {
+          phase: "finish",
+          requirementId: item.feature.id,
+          status: "ok",
+          attempt: existing.attempt,
+          resumed: true,
+        },
+        clock,
+      );
+      return existing;
+    }
+  }
+  const taskMd = buildTaskMdForSubagent(
+    item,
+    ctx.reqModel,
+    ctx.promptContext,
+    ctx.opts.gapAuditLinks,
+    paths,
+    ctx.opts.nameTrace,
+  );
+  await writeFile(taskPath, taskMd, "utf8");
+  await writeFile(
+    expectedPath,
+    JSON.stringify(buildFeatureExpected(item, ctx.opts.nameTrace), null, 2),
+    "utf8",
+  );
+  for (let attempt = 1; ; attempt += 1) {
+    await appendStatusEvent(
+      ctx.opts.renderDir,
+      {
+        phase: "start",
+        requirementId: item.feature.id,
+        attempt,
+      },
+      clock,
+    );
+    const dispatch = await ctx.opts.backend.run({
+      prompt: taskPath,
+      cwd: ctx.opts.projectRoot,
+      agentName: ctx.opts.agentName ?? "reqgen-renderer",
+    });
+    await persistAttempt(dir, attempt, dispatch);
+    const result = await readFinalizedFeatureOutput(outputPath);
+    if (result !== undefined) {
+      await appendStatusEvent(
+        ctx.opts.renderDir,
+        {
+          phase: "finish",
+          requirementId: item.feature.id,
+          status: "ok",
+          attempt,
+          ...(dispatch.stats ? { stats: dispatch.stats } : {}),
+        },
+        clock,
+      );
+      return result;
+    }
+    if (attempt > maxRetries) {
+      const errorResult = {
+        status: "error",
+        error:
+          dispatch.status !== "ok"
+            ? (dispatch.error ?? "backend process failed")
+            : "subprocess exited but output.json was not finalized",
+        citationsValid: false,
+        restatedFactsValid: false,
+        attempt,
+      };
+      await writeFile(outputPath, JSON.stringify(errorResult, null, 2), "utf8");
+      await appendStatusEvent(
+        ctx.opts.renderDir,
+        {
+          phase: "finish",
+          requirementId: item.feature.id,
+          status: "error",
+          attempt,
+        },
+        clock,
+      );
+      return errorResult;
+    }
+    const delayMs = backoffMs * 2 ** (attempt - 1);
+    await appendStatusEvent(
+      ctx.opts.renderDir,
+      {
+        phase: "retry-scheduled",
+        requirementId: item.feature.id,
+        attempt: attempt + 1,
+        reason:
+          dispatch.status !== "ok"
+            ? (dispatch.errorReason ?? "execution-failed")
+            : "output-not-finalized",
+        delayMs,
+        retryAt: clock() + delayMs,
+      },
+      clock,
+    );
+    await sleepFn(delayMs);
+  }
+}
+export async function renderAreaUnified(item, ctx) {
+  const maxRetries = ctx.opts.maxRetries ?? 5;
+  const backoffMs = ctx.opts.backoffMs ?? 5000;
+  const sleepFn = ctx.opts.sleepFn ?? defaultSleep;
+  const clock = ctx.opts.clock ?? Date.now;
+  const dir = path.join(ctx.opts.renderDir, areaDirFor(item.area.id));
+  await mkdir(dir, { recursive: true });
+  const checkScriptPath = defaultCheckScriptPath();
+  const outputPath = path.join(dir, "output.json");
+  const expectedPath = path.join(dir, "expected.json");
+  const taskPath = path.join(dir, "task.md");
+  const paths = { expectedPath, outputPath, checkScriptPath };
+  if (ctx.opts.resume) {
+    const existing = await readFinalizedAreaOutput(outputPath);
+    if (existing !== undefined) {
+      await appendStatusEvent(
+        ctx.opts.renderDir,
+        {
+          phase: "finish",
+          areaId: item.area.id,
+          status: "ok",
+          attempt: existing.attempt,
+          featureCount: existing.features.size,
+          resumed: true,
+        },
+        clock,
+      );
+      return existing;
+    }
+  }
+  const taskMd = buildAreaTaskMdForSubagent(
+    item,
+    ctx.reqModel,
+    ctx.promptContext,
+    ctx.opts.gapAuditLinks,
+    paths,
+    ctx.opts.nameTrace,
+  );
+  await writeFile(taskPath, taskMd, "utf8");
+  await writeFile(
+    expectedPath,
+    JSON.stringify(buildAreaExpected(item, ctx.opts.nameTrace), null, 2),
+    "utf8",
+  );
+  const kind = resolveAreaKind(item.area);
+  for (let attempt = 1; ; attempt += 1) {
+    await appendStatusEvent(
+      ctx.opts.renderDir,
+      {
+        phase: "start",
+        areaId: item.area.id,
+        attempt,
+        featureCount: item.area.features.length,
+        kind,
+      },
+      clock,
+    );
+    const dispatch = await ctx.opts.backend.run({
+      prompt: taskPath,
+      cwd: ctx.opts.projectRoot,
+      agentName: ctx.opts.agentName ?? "reqgen-renderer",
+    });
+    await persistAttempt(dir, attempt, dispatch);
+    const result = await readFinalizedAreaOutput(outputPath);
+    if (result !== undefined) {
+      await appendStatusEvent(
+        ctx.opts.renderDir,
+        {
+          phase: "finish",
+          areaId: item.area.id,
+          status: "ok",
+          attempt,
+          featureCount: result.features.size,
+          ...(dispatch.stats ? { stats: dispatch.stats } : {}),
+        },
+        clock,
+      );
+      return result;
+    }
+    if (attempt > maxRetries) {
+      const errorResult = {
+        status: "error",
+        error:
+          dispatch.status !== "ok"
+            ? (dispatch.error ?? "backend process failed")
+            : "subprocess exited but output.json was not finalized",
+        areaId: item.area.id,
+        features: new Map(),
+        attempt,
+      };
+      const featuresObj = {};
+      await writeFile(
+        outputPath,
+        JSON.stringify(
+          { ...errorResult, finalized: false, features: featuresObj },
+          null,
+          2,
+        ),
+        "utf8",
+      );
+      await appendStatusEvent(
+        ctx.opts.renderDir,
+        {
+          phase: "finish",
+          areaId: item.area.id,
+          status: "error",
+          attempt,
+        },
+        clock,
+      );
+      return errorResult;
+    }
+    const delayMs = backoffMs * 2 ** (attempt - 1);
+    await appendStatusEvent(
+      ctx.opts.renderDir,
+      {
+        phase: "retry-scheduled",
+        areaId: item.area.id,
+        attempt: attempt + 1,
+        reason:
+          dispatch.status !== "ok"
+            ? (dispatch.errorReason ?? "execution-failed")
+            : "output-not-finalized",
+        delayMs,
+        retryAt: clock() + delayMs,
+      },
+      clock,
+    );
+    await sleepFn(delayMs);
+  }
+}
+export async function renderAllFeaturesUnified(items, reqModel, opts) {
+  const clock = opts.clock ?? Date.now;
+  await mkdir(opts.renderDir, { recursive: true });
+  if (!opts.resume)
+    await writeFile(path.join(opts.renderDir, "status.ndjson"), "", "utf8");
+  await appendStatusEvent(
+    opts.renderDir,
+    planEvent(opts, true, items.length),
+    clock,
+  );
+  const ctx = {
+    reqModel,
+    promptContext: {
+      projectRoot: opts.projectRoot,
+      module: reqModel.analysisContext.applicationModule,
+      variant: reqModel.analysisContext.buildVariant,
+      analysisMode: opts.analysisMode,
+    },
+    opts,
+  };
+  const results = new Map();
+  await runPool(items, opts.concurrency ?? 4, async (item) => {
+    let result;
+    try {
+      result = await renderFeatureUnified(item, ctx);
+    } catch (error) {
+      result = {
+        status: "error",
+        error: error instanceof Error ? error.message : String(error),
+        citationsValid: false,
+        restatedFactsValid: false,
+        attempt: 0,
+      };
+      await appendStatusEvent(
+        opts.renderDir,
+        {
+          phase: "finish",
+          requirementId: item.feature.id,
+          status: result.status,
+        },
+        clock,
+      );
+    }
+    results.set(item.feature.id, result);
+  });
+  return results;
+}
+export async function renderAllAreasUnified(items, reqModel, opts) {
+  const clock = opts.clock ?? Date.now;
+  await mkdir(opts.renderDir, { recursive: true });
+  if (!opts.resume)
+    await writeFile(path.join(opts.renderDir, "status.ndjson"), "", "utf8");
+  await appendStatusEvent(
+    opts.renderDir,
+    planEvent(opts, false, items.length),
+    clock,
+  );
+  const ctx = {
+    reqModel,
+    promptContext: {
+      projectRoot: opts.projectRoot,
+      module: reqModel.analysisContext.applicationModule,
+      variant: reqModel.analysisContext.buildVariant,
+      analysisMode: opts.analysisMode,
+    },
+    opts,
+  };
+  const results = new Map();
+  await runPool(items, opts.concurrency ?? 4, async (item) => {
+    let result;
+    try {
+      result = await renderAreaUnified(item, ctx);
+    } catch (error) {
+      result = {
+        status: "error",
+        error: error instanceof Error ? error.message : String(error),
+        areaId: item.area.id,
+        features: new Map(),
+        attempt: 0,
+      };
+      await appendStatusEvent(
+        opts.renderDir,
+        {
+          phase: "finish",
+          areaId: item.area.id,
+          status: result.status,
+        },
+        clock,
+      );
+    }
+    results.set(item.area.id, result);
+  });
+  return results;
+}
+/** Absolute path to the self-check script bundled with this skill (not this
+ * TS runtime's own build), resolved relative to this module rather than
+ * process.cwd() so it works regardless of where `pnpm stage2` is invoked
+ * from. The script lives beside the runtime directory under the skill root,
+ * so it travels with the skill wherever it's installed. */
+export function defaultCheckScriptPath() {
+  return path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "..",
+    "reqgen-selfcheck.mjs",
+  );
+}
+export async function prepareFeatureInputs(items, reqModel, opts) {
+  await mkdir(opts.renderDir, { recursive: true });
+  const promptContext = {
+    projectRoot: opts.projectRoot,
+    module: reqModel.analysisContext.applicationModule,
+    variant: reqModel.analysisContext.buildVariant,
+    analysisMode: opts.analysisMode,
+  };
+  const checkScriptPath = defaultCheckScriptPath();
+  const entries = [];
+  for (const item of items) {
+    const dir = path.join(opts.renderDir, renderDirFor(item.feature.id));
+    await mkdir(dir, { recursive: true });
+    const paths = {
+      expectedPath: path.join(dir, "expected.json"),
+      outputPath: path.join(dir, "output.json"),
+      checkScriptPath,
+    };
+    const taskMd = buildTaskMdForSubagent(
+      item,
+      reqModel,
+      promptContext,
+      opts.gapAuditLinks,
+      paths,
+      opts.nameTrace,
+    );
+    const taskPath = path.join(dir, "task.md");
+    await writeFile(taskPath, taskMd, "utf8");
+    await writeFile(
+      paths.expectedPath,
+      JSON.stringify(buildFeatureExpected(item, opts.nameTrace), null, 2),
+      "utf8",
+    );
+    entries.push({
+      id: item.feature.id,
+      taskPath,
+      expectedPath: paths.expectedPath,
+      outputPath: paths.outputPath,
+    });
+  }
+  return entries;
+}
+export async function prepareAreaInputs(items, reqModel, opts) {
+  await mkdir(opts.renderDir, { recursive: true });
+  const promptContext = {
+    projectRoot: opts.projectRoot,
+    module: reqModel.analysisContext.applicationModule,
+    variant: reqModel.analysisContext.buildVariant,
+    analysisMode: opts.analysisMode,
+  };
+  const checkScriptPath = defaultCheckScriptPath();
+  const entries = [];
+  for (const item of items) {
+    const dir = path.join(opts.renderDir, areaDirFor(item.area.id));
+    await mkdir(dir, { recursive: true });
+    const paths = {
+      expectedPath: path.join(dir, "expected.json"),
+      outputPath: path.join(dir, "output.json"),
+      checkScriptPath,
+    };
+    const taskMd = buildAreaTaskMdForSubagent(
+      item,
+      reqModel,
+      promptContext,
+      opts.gapAuditLinks,
+      paths,
+      opts.nameTrace,
+    );
+    const taskPath = path.join(dir, "task.md");
+    await writeFile(taskPath, taskMd, "utf8");
+    await writeFile(
+      paths.expectedPath,
+      JSON.stringify(buildAreaExpected(item, opts.nameTrace), null, 2),
+      "utf8",
+    );
+    entries.push({
+      id: item.area.id,
+      taskPath,
+      expectedPath: paths.expectedPath,
+      outputPath: paths.outputPath,
+    });
+  }
+  return entries;
+}
+async function isUnitDone(outputPath) {
+  try {
+    const parsed = JSON.parse(await readFile(outputPath, "utf8"));
+    // finalized, not just status === "ok": in subagent mode outputPath is
+    // written once by the subagent's own raw (pre-check) judgment and then
+    // overwritten in place by `finalize` (ADR-0005) — a raw draft can
+    // legitimately have status "ok" (the subagent's own self-assessment)
+    // before it has actually passed self-check, so status alone would
+    // mark an interrupted, never-finalized unit as done.
+    return parsed.finalized === true && parsed.status === "ok";
+  } catch {
+    return false;
+  }
+}
+/** Safe to call every time prepare runs, including on resume: it always
+ * reflects which output.json files exist *right now*, never what a prior
+ * dispatch session merely believed it had finished — so a fresh session
+ * (with no memory of the last one) can trust it as ground truth rather than
+ * trusting its own or another session's bookkeeping. */
+export async function writeRenderList(
+  outputDirectory,
+  checkScriptPath,
+  entries,
+) {
+  const doneFlags = await Promise.all(
+    entries.map((entry) => isUnitDone(entry.outputPath)),
+  );
+  const lines = entries.map(
+    (entry, index) => `- [${doneFlags[index] ? "x" : " "}] ${entry.id}`,
+  );
+  const listPath = path.join(outputDirectory, "render-list.md");
+  await writeFile(
+    listPath,
+    `${lines.length === 0 ? "" : `${lines.join("\n")}\n`}`,
+    "utf8",
+  );
+  const manifestPath = path.join(outputDirectory, "render-manifest.json");
+  await writeFile(
+    manifestPath,
+    JSON.stringify({ checkScriptPath, entries }, null, 2),
+    "utf8",
+  );
+  const done = doneFlags.filter(Boolean).length;
+  return {
+    listPath,
+    manifestPath,
+    total: entries.length,
+    done,
+    pending: entries.length - done,
+  };
+}