android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/stage2-cli.js

@@ -0,0 +1,109 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runAgentStage2 } from "./agent-render/index.js";
+export { loadStage2Input } from "./stage2-input.js";
+export { loadStage2NameTraceabilityInput } from "./stage2-name-trace-input.js";
+export { parseAgentArguments, runAgentStage2 } from "./agent-render/index.js";
+export {
+  buildSpecInputBatches,
+  exportSpecHandoff,
+  parseStage2ReqText,
+  SPEC_HANDOFF_CONTRACT_VERSION,
+  SPEC_INPUT_FORMAT,
+  validateSpecInputText,
+} from "./spec-handoff.js";
+export const STAGE2_USAGE = `Usage (default, --mode subagent, ADR-0005):
+  pnpm stage2 -- --input <successful-stage1-run-directory> \\
+    --project-root <android-project> [--output <directory>] \\
+    [--per-feature] [--with-unreachable-area] [--spec-output <directory>]
+
+  Writes rendering/<unit>/{task.md,expected.json} for every renderable Area
+  (or Feature, with --per-feature) and prints a manifest — it does NOT spawn
+  any backend. Turning each manifest entry into a rendering/<unit>/output.json
+  is done by dispatching the Claude Code Agent tool outside this process; see
+  ../references/subagent-render.md for the full protocol
+  (self-check via scripts/reqgen-selfcheck.mjs, retry/skip/abort policy).
+
+Usage (--mode shell):
+  pnpm stage2 -- --mode shell --input <successful-stage1-run-directory> \\
+    --project-root <android-project> \\
+    [--backend claude|opencode] [--agent-name reqgen-renderer] \\
+    [--ai-command <executable>] [--concurrency 8] \\
+    [--max-retries 5] [--backoff-ms 5000] [--output <directory> | --resume <directory>] \\
+    [--per-feature] [--with-unreachable-area] [--spec-output <directory>]
+
+  Renders REQ prose by spawning a backend (claude, opencode, or --ai-command)
+  per unit, then writes BOTH req.md (markdown) and per-area req-{idx}.txt
+  (plain text, no markdown) into the output directory. --backend defaults to
+  "claude" (the \`claude\` CLI's own -p/--print headless mode, dispatched with
+  --agent <agent-name> so it picks up the same .claude/agents/<agent-name>.md
+  config the default subagent mode uses). The default output directory is
+  <input>/generation.
+
+  The default Claude backend uses the unified protocol (task.md +
+  self-check/finalize via reqgen-selfcheck.mjs); custom --ai-command and
+  opencode use the inline-prompt path. Use --mode shell-legacy to force the
+  old inline-prompt path for Claude as well.
+
+  --per-feature           render one session per Feature instead of the
+                          default one session per Area.
+  --with-unreachable-area keep Areas judged unreachable in output (sunk
+                          after every reachable Area) instead of dropping
+                          them. In per-feature mode the judgment falls back
+                          to static analysis (canonicalPath.status).
+  --resume <directory>    resume --mode shell from an existing output directory;
+                          finalized units are reused and unfinished units rerun.
+
+Usage (--mode shell-legacy):
+  pnpm stage2 -- --mode shell-legacy --input <successful-stage1-run-directory> \\
+    --project-root <android-project> \\
+    [--backend claude|opencode] [--agent-name reqgen-renderer] \\
+    [--ai-command <executable>] [--concurrency 8] \\
+    [--max-retries 5] [--backoff-ms 5000] [--output <directory>] \\
+    [--per-feature] [--with-unreachable-area] [--spec-output <directory>]
+
+  Pre-normalize shell interaction: ALL backends (including claude) use the
+  inline-prompt path — the full prompt is passed on stdin, JSON is parsed
+  from stdout, and validation/retry is done by this process. Unlike --mode
+  shell (which uses task.md + self-check/finalize for the claude backend),
+  this mode does NOT delegate validation to the subprocess. Same output as
+  unified self-check protocol is not available in the target environment.
+
+Usage (either mode):
+  pnpm stage2 -- --input <run-directory> --snapshot \\
+    [--output <directory>] [--per-feature] [--with-unreachable-area] \\
+    [--spec-output <directory>]
+
+  --snapshot merges already-persisted rendering results offline into both
+  a timestamped req-<timestamp>.md and per-area req-{idx}.txt files, without
+  contacting any backend.
+
+  --spec-output <directory> additionally writes page-local
+  <batch>/REQ.txt files and manifest.json for $a2h-spec-generate after the
+  Stage 2 merge. Each batch contains one Area/page boundary; the option may
+  be used with shell rendering or --snapshot. It is rejected during the
+  subagent preparation-only phase because no finalized output exists yet.
+
+  When --output is explicitly set (all modes except --snapshot), the target
+  directory must be empty or non-existent. Use --resume <directory> with
+  --mode shell to continue an interrupted run; finalized output.json files
+  are reused and the remaining units are rendered. --snapshot is exempt
+  because it must read existing output.json. Default paths are never guarded.
+`;
+const defaultIo = {
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
+};
+export async function runStage2Cli(argv, io = defaultIo) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    io.stdout(STAGE2_USAGE);
+    return 0;
+  }
+  return runAgentStage2(argv, io);
+}
+const isDirectExecution =
+  process.argv[1] !== undefined &&
+  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+if (isDirectExecution) {
+  process.exitCode = await runStage2Cli(process.argv.slice(2));
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/stage2-input.js

@@ -0,0 +1,419 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  GAP_AUDIT_CONTRACT_VERSION,
+  semanticCompletenessValues,
+} from "./contracts/index.js";
+import { sha256Text } from "./pipeline/output.js";
+export class GenerationError extends Error {
+  code;
+  status;
+  details;
+  constructor(code, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = "GenerationError";
+    this.code = code;
+    this.status = options.status;
+    this.details = options.details;
+  }
+}
+export function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function parseJson(text, filename) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new GenerationError(
+      "STAGE2_INPUT_JSON_INVALID",
+      `${filename} is not valid JSON`,
+    );
+  }
+}
+async function readInputFiles(inputDirectory) {
+  try {
+    const [reportText, reqModelText] = await Promise.all([
+      readFile(join(inputDirectory, "run-report.json"), "utf8"),
+      readFile(join(inputDirectory, "req-model.json"), "utf8"),
+    ]);
+    return { reportText, reqModelText };
+  } catch (error) {
+    throw new GenerationError(
+      "STAGE2_INPUT_MISSING",
+      "Stage 2 requires run-report.json and req-model.json from one Stage 1 run",
+      { cause: error },
+    );
+  }
+}
+function completenessOf(value) {
+  if (!isRecord(value) || !Object.hasOwn(value, "semanticCompleteness")) {
+    return undefined;
+  }
+  return typeof value.semanticCompleteness === "string"
+    ? value.semanticCompleteness
+    : undefined;
+}
+function assertReportCompleteness(reportValue) {
+  const reportCompleteness = completenessOf(reportValue);
+  const invalidReport =
+    Object.hasOwn(reportValue, "semanticCompleteness") &&
+    (reportCompleteness === undefined ||
+      !semanticCompletenessValues.includes(reportCompleteness));
+  const inconsistentReport =
+    (reportValue.publishable === false &&
+      reportCompleteness !== "incomplete-known") ||
+    (reportValue.publishable === true &&
+      reportCompleteness === "incomplete-known");
+  if (invalidReport || inconsistentReport) {
+    throw new GenerationError(
+      "STAGE2_INPUT_QUALITY_STATE_INVALID",
+      "run-report.json has an inconsistent publishable/semanticCompleteness state",
+    );
+  }
+}
+function assertReqModelCompleteness(reportValue, reqModelValue) {
+  const reqModelCompleteness = completenessOf(reqModelValue);
+  const invalidReqModel =
+    Object.hasOwn(reqModelValue, "semanticCompleteness") &&
+    (reqModelCompleteness === undefined ||
+      !semanticCompletenessValues.includes(reqModelCompleteness));
+  if (
+    invalidReqModel ||
+    (reportValue.publishable === true &&
+      reqModelCompleteness === "incomplete-known")
+  ) {
+    throw new GenerationError(
+      "STAGE2_INPUT_QUALITY_STATE_INVALID",
+      "req-model.json has an inconsistent semanticCompleteness state",
+    );
+  }
+}
+function assertReportReady(reportValue) {
+  if (
+    !isRecord(reportValue) ||
+    reportValue.status !== "succeeded" ||
+    (reportValue.publishable !== true && reportValue.publishable !== false) ||
+    reportValue.completedStage !== "validate" ||
+    !Array.isArray(reportValue.artifacts)
+  ) {
+    throw new GenerationError(
+      "STAGE2_INPUT_NOT_READY",
+      "run-report.json does not describe a successful, validated Stage 1 run",
+    );
+  }
+}
+function assertReqModelEnvelope(reqModelValue) {
+  if (
+    !isRecord(reqModelValue) ||
+    reqModelValue.schemaVersion !== "1.0.0" ||
+    reqModelValue.artifactKind !== "req-model" ||
+    typeof reqModelValue.caseId !== "string" ||
+    !isRecord(reqModelValue.analysisContext) ||
+    !Array.isArray(reqModelValue.areas) ||
+    !Array.isArray(reqModelValue.unresolved)
+  ) {
+    throw new GenerationError(
+      "STAGE2_REQ_MODEL_INVALID",
+      "req-model.json has an unsupported envelope",
+    );
+  }
+}
+function assertReqModelHash(reportValue, reqModelText) {
+  const reqArtifact = reportValue.artifacts.find(
+    (artifact) =>
+      isRecord(artifact) &&
+      artifact.kind === "req-model" &&
+      artifact.relativePath === "req-model.json",
+  );
+  if (
+    !isRecord(reqArtifact) ||
+    typeof reqArtifact.sha256 !== "string" ||
+    reqArtifact.sha256 !== sha256Text(reqModelText)
+  ) {
+    throw new GenerationError(
+      "STAGE2_REQ_MODEL_HASH_MISMATCH",
+      "req-model.json does not match the artifact hash in run-report.json",
+    );
+  }
+}
+function assertSameContext(report, reqModel) {
+  if (
+    report.caseId !== reqModel.caseId ||
+    report.target === undefined ||
+    report.target.applicationModule !==
+      reqModel.analysisContext.applicationModule ||
+    report.target.buildVariant !== reqModel.analysisContext.buildVariant ||
+    JSON.stringify(report.target.resourceConfiguration) !==
+      JSON.stringify(reqModel.analysisContext.resourceConfiguration)
+  ) {
+    throw new GenerationError(
+      "STAGE2_INPUT_CONTEXT_MISMATCH",
+      "run-report.json and req-model.json do not describe the same analysis context",
+    );
+  }
+}
+function assertAreaGraphEnvelope(graphValue) {
+  if (
+    !isRecord(graphValue) ||
+    graphValue.schemaVersion !== "1.0.0" ||
+    graphValue.artifactKind !== "area-graph" ||
+    typeof graphValue.caseId !== "string" ||
+    !isRecord(graphValue.analysisContext) ||
+    !Array.isArray(graphValue.areas) ||
+    !Array.isArray(graphValue.controls) ||
+    !Array.isArray(graphValue.unresolved)
+  ) {
+    throw new GenerationError(
+      "STAGE2_AREA_GRAPH_INVALID",
+      "area-graph.json has an unsupported envelope",
+    );
+  }
+}
+function assertAreaGraphHash(report, graphText) {
+  const graphArtifact = report.artifacts.find(
+    (artifact) =>
+      artifact.kind === "area-graph" &&
+      artifact.relativePath === "area-graph.json",
+  );
+  if (
+    graphArtifact === undefined ||
+    graphArtifact.sha256 !== sha256Text(graphText)
+  ) {
+    throw new GenerationError(
+      "STAGE2_AREA_GRAPH_HASH_MISMATCH",
+      "area-graph.json does not match the artifact hash in run-report.json",
+    );
+  }
+}
+function assertAreaGraphContext(graph, reqModel) {
+  if (
+    graph.caseId !== reqModel.caseId ||
+    JSON.stringify(graph.analysisContext) !==
+      JSON.stringify(reqModel.analysisContext)
+  ) {
+    throw new GenerationError(
+      "STAGE2_AREA_GRAPH_CONTEXT_MISMATCH",
+      "area-graph.json does not match req-model.json",
+    );
+  }
+}
+/** Required alongside req-model.json to recompute the Stage 1 deterministic
+ * draft (renderReqDraft) as the merge template — recomputing instead of
+ * reading generation/req.md keeps the template hash-verified against
+ * the same req-model instead of trusting a plain text file on disk. */
+export async function loadStage2AreaGraph(inputDirectory, report, reqModel) {
+  let graphText;
+  try {
+    graphText = await readFile(join(inputDirectory, "area-graph.json"), "utf8");
+  } catch (error) {
+    throw new GenerationError(
+      "STAGE2_AREA_GRAPH_MISSING",
+      "Stage 2 requires area-graph.json from the same Stage 1 run",
+      { cause: error },
+    );
+  }
+  const graphValue = parseJson(graphText, "area-graph.json");
+  assertAreaGraphEnvelope(graphValue);
+  assertAreaGraphHash(report, graphText);
+  const graph = graphValue;
+  assertAreaGraphContext(graph, reqModel);
+  return graph;
+}
+function assertGapAuditEnvelope(gapAuditValue) {
+  if (
+    !isRecord(gapAuditValue) ||
+    gapAuditValue.contractVersion !== GAP_AUDIT_CONTRACT_VERSION ||
+    gapAuditValue.artifactKind !== "gap-audit" ||
+    typeof gapAuditValue.caseId !== "string" ||
+    !Array.isArray(gapAuditValue.categories) ||
+    !isRecord(gapAuditValue.summary) ||
+    !semanticCompletenessValues.includes(gapAuditValue.semanticCompleteness) ||
+    !Array.isArray(gapAuditValue.semanticLimitations)
+  ) {
+    throw new GenerationError(
+      "STAGE2_GAP_AUDIT_INVALID",
+      "gap-audit.json has an unsupported envelope",
+    );
+  }
+}
+function assertGapAuditHash(report, gapAuditText) {
+  const gapAuditArtifact = report.artifacts.find(
+    (artifact) =>
+      artifact.kind === "gap-audit" &&
+      artifact.relativePath === "gap-audit.json",
+  );
+  if (
+    gapAuditArtifact === undefined ||
+    gapAuditArtifact.sha256 !== sha256Text(gapAuditText)
+  ) {
+    throw new GenerationError(
+      "STAGE2_GAP_AUDIT_HASH_MISMATCH",
+      "gap-audit.json does not match the artifact hash in run-report.json",
+    );
+  }
+}
+function assertGapAuditContext(gapAudit, reqModel) {
+  if (gapAudit.caseId !== reqModel.caseId) {
+    throw new GenerationError(
+      "STAGE2_GAP_AUDIT_CONTEXT_MISMATCH",
+      "gap-audit.json does not match req-model.json",
+    );
+  }
+}
+/** Required alongside req-model.json so the AI Agent rendering route can
+ * surface gap-audit's unresolved/limited candidates in `## unresolved` —
+ * a purely additive Stage 2 signal (ADR-0004, PRD-0007). Mandatory like
+ * loadStage2AreaGraph: no silent-skip path when the file is missing. */
+export async function loadStage2GapAudit(inputDirectory, report, reqModel) {
+  let gapAuditText;
+  try {
+    gapAuditText = await readFile(
+      join(inputDirectory, "gap-audit.json"),
+      "utf8",
+    );
+  } catch (error) {
+    throw new GenerationError(
+      "STAGE2_GAP_AUDIT_MISSING",
+      "Stage 2 requires gap-audit.json from the same Stage 1 run",
+      { cause: error },
+    );
+  }
+  const gapAuditValue = parseJson(gapAuditText, "gap-audit.json");
+  assertGapAuditEnvelope(gapAuditValue);
+  assertGapAuditHash(report, gapAuditText);
+  const gapAudit = gapAuditValue;
+  assertGapAuditContext(gapAudit, reqModel);
+  return gapAudit;
+}
+/** True only when every branch a target could resolve to is a "kind: area"
+ * ReqFeatureAreaTarget — i.e. the destination is always one of the Areas
+ * already rendered elsewhere in this req-model. "history-back" and
+ * "conditional-area-set" are built (analysis/req-model/build.ts) only from
+ * resolved Area edges, so they qualify unconditionally; "external" and an
+ * unresolved target/branch never do, since no Area entry describes them.
+ * "alternative-target-set" is the one shape that can legitimately mix an
+ * Area branch with an external or unresolved branch (built as the fallback
+ * whenever an Action's edges resolve to more than one target kind, or include
+ * an unresolved edge) — such a Feature must not be skipped, since part of its
+ * behavior (the non-Area branch) has no Area entry to fall back on. */
+function targetResolvesOnlyToAreas(target) {
+  if ("status" in target) return false;
+  switch (target.kind) {
+    case "area":
+    case "history-back":
+    case "conditional-area-set":
+      return true;
+    case "external":
+      return false;
+    case "alternative-target-set":
+      return target.branches.every((branch) =>
+        isAreaBranchTarget(branch.target),
+      );
+  }
+}
+function isAreaBranchTarget(target) {
+  return !("status" in target) && target.kind === "area";
+}
+function isNavigationOnlyInteraction(interaction) {
+  return (
+    interaction.target !== undefined &&
+    interaction.effects.length === 0 &&
+    targetResolvesOnlyToAreas(interaction.target)
+  );
+}
+/** A Feature whose only observable behavior, across every way it can be
+ * triggered, is navigating to Area(s) that are themselves already rendered
+ * carries no independent requirement content — the destination Area already
+ * describes itself. Areas with no remaining Features are still rendered
+ * (static description + navigation), so this only ever removes Features,
+ * never their owning Area. */
+function isNavigationOnlyFeature(feature) {
+  const interactions = feature.interactions ?? [
+    { effects: feature.effects, target: feature.target },
+  ];
+  return (
+    interactions.length > 0 && interactions.every(isNavigationOnlyInteraction)
+  );
+}
+/**
+ * Filters what should not be rendered, unconditionally:
+ * - Features whose only behavior, on every trigger, is navigating to Area(s)
+ *   already rendered elsewhere (no independent req content). A Feature that
+ *   can also navigate to something that is not an Area in this req-model
+ *   (an external endpoint, or an unresolved target/branch) is kept, since
+ *   that part of its behavior has nowhere else to be described.
+ *
+ * Areas with unreachable canonicalPath are always kept — the Agent is asked
+ * to determine the actual access path (or confirm unreachability with
+ * evidence) itself rather than being skipped in favor of the deterministic
+ * "无法到达" placeholder.
+ *
+ * Areas are never dropped for having zero remaining Features — an Area with
+ * no dynamic Features still gets rendered for its static description and
+ * navigation.
+ */
+export function filterRenderableAreas(reqModel) {
+  return {
+    ...reqModel,
+    areas: reqModel.areas.map((area) => ({
+      ...area,
+      features: area.features.filter(
+        (feature) => !isNavigationOnlyFeature(feature),
+      ),
+    })),
+  };
+}
+/**
+ * Stable partition: Areas with a resolved/unresolved canonicalPath first (in
+ * their original relative order), followed by unreachable Areas (in their
+ * original relative order). Must run once, before both the deterministic
+ * template (renderReqDraft) and the Agent-render walk (filterRenderableAreas,
+ * merge*) see the req-model — they all read `reqModel.areas` positionally,
+ * so reordering later or only in one of them would desync the merge walk
+ * from the template it is walking.
+ */
+export function sortAreasReachableFirst(reqModel) {
+  const reachable = reqModel.areas.filter(
+    (area) => area.canonicalPath.status !== "unreachable",
+  );
+  const unreachable = reqModel.areas.filter(
+    (area) => area.canonicalPath.status === "unreachable",
+  );
+  return { ...reqModel, areas: [...reachable, ...unreachable] };
+}
+export async function loadStage2Input(inputDirectory) {
+  return (await loadStage2InputWithReport(inputDirectory)).reqModel;
+}
+export async function loadStage2InputWithReport(inputDirectory) {
+  const { reportText, reqModelText } = await readInputFiles(inputDirectory);
+  const reportValue = parseJson(reportText, "run-report.json");
+  const reqModelValue = parseJson(reqModelText, "req-model.json");
+  assertReportReady(reportValue);
+  assertReportCompleteness(reportValue);
+  assertReqModelHash(reportValue, reqModelText);
+  assertReqModelEnvelope(reqModelValue);
+  assertReqModelCompleteness(reportValue, reqModelValue);
+  const report = reportValue;
+  const reqModel = reqModelValue;
+  if (
+    report.publishable === false &&
+    reqModel.semanticCompleteness !== "incomplete-known"
+  ) {
+    throw new GenerationError(
+      "STAGE2_INPUT_QUALITY_STATE_INVALID",
+      "req-model.json does not match the incomplete Stage 1 quality state",
+    );
+  }
+  if (
+    report.semanticCompleteness !== undefined &&
+    reqModel.semanticCompleteness !== undefined &&
+    report.semanticCompleteness !== reqModel.semanticCompleteness
+  ) {
+    throw new GenerationError(
+      "STAGE2_SEMANTIC_COMPLETENESS_MISMATCH",
+      "run-report.json and req-model.json disagree about semantic completeness",
+    );
+  }
+  assertSameContext(report, reqModel);
+  return { reqModel, report };
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/stage2-name-trace-input.js

@@ -0,0 +1,95 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { sha256Text } from "./pipeline/output.js";
+import { GenerationError, isRecord, parseJson } from "./stage2-input.js";
+async function readOptionalText(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+      return undefined;
+    throw error;
+  }
+}
+/**
+ * Source locations are intentionally not copied into req-model.json. Read the
+ * two sibling Stage 1 artifacts only for the optional name-traceability
+ * output (human audit in openai-compatible mode, title/citation grounding in
+ * agent mode).
+ */
+export async function loadStage2NameTraceabilityInput(
+  inputDirectory,
+  reqModel,
+) {
+  const [sourceText, graphText] = await Promise.all([
+    readOptionalText(join(inputDirectory, "source-facts.json")),
+    readOptionalText(join(inputDirectory, "area-graph.json")),
+  ]);
+  if (sourceText === undefined && graphText === undefined) return undefined;
+  if (sourceText === undefined || graphText === undefined) {
+    throw new GenerationError(
+      "STAGE2_NAME_TRACE_INPUT_INCOMPLETE",
+      "Name traceability requires both source-facts.json and area-graph.json",
+    );
+  }
+  const sourceValue = parseJson(sourceText, "source-facts.json");
+  const graphValue = parseJson(graphText, "area-graph.json");
+  const reportValue = parseJson(
+    await readFile(join(inputDirectory, "run-report.json"), "utf8"),
+    "run-report.json",
+  );
+  if (
+    !isRecord(sourceValue) ||
+    sourceValue.schemaVersion !== "1.0.0" ||
+    sourceValue.artifactKind !== "source-facts" ||
+    !Array.isArray(sourceValue.evidence) ||
+    !Array.isArray(sourceValue.facts) ||
+    !Array.isArray(sourceValue.unresolved) ||
+    !isRecord(graphValue) ||
+    graphValue.schemaVersion !== "1.0.0" ||
+    graphValue.artifactKind !== "area-graph" ||
+    !Array.isArray(graphValue.areas) ||
+    !Array.isArray(graphValue.controls) ||
+    !Array.isArray(graphValue.unresolved)
+  ) {
+    throw new GenerationError(
+      "STAGE2_NAME_TRACE_INPUT_INVALID",
+      "source-facts.json or area-graph.json has an unsupported envelope",
+    );
+  }
+  const artifactHashMatches = (kind, relativePath, text) =>
+    isRecord(reportValue) &&
+    Array.isArray(reportValue.artifacts) &&
+    reportValue.artifacts.some(
+      (artifact) =>
+        isRecord(artifact) &&
+        artifact.kind === kind &&
+        artifact.relativePath === relativePath &&
+        artifact.sha256 === sha256Text(text),
+    );
+  if (
+    !artifactHashMatches("source-facts", "source-facts.json", sourceText) ||
+    !artifactHashMatches("area-graph", "area-graph.json", graphText)
+  ) {
+    throw new GenerationError(
+      "STAGE2_NAME_TRACE_HASH_MISMATCH",
+      "Name traceability inputs do not match the hashes in run-report.json",
+    );
+  }
+  const source = sourceValue;
+  const graph = graphValue;
+  if (
+    source.caseId !== reqModel.caseId ||
+    graph.caseId !== reqModel.caseId ||
+    JSON.stringify(source.analysisContext) !==
+      JSON.stringify(reqModel.analysisContext) ||
+    JSON.stringify(graph.analysisContext) !==
+      JSON.stringify(reqModel.analysisContext)
+  ) {
+    throw new GenerationError(
+      "STAGE2_NAME_TRACE_CONTEXT_MISMATCH",
+      "Name traceability inputs do not match req-model.json",
+    );
+  }
+  return { source, graph };
+}