ravensight-playtest 0.1.0

package/src/run/aggregate.js

@@ -0,0 +1,658 @@
+import { createHash } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseJsonArray, parseJsonObject } from './json.js';
+import { callStepWithRetry, ProxyError, STEPS } from './model.js';
+import { JOB_FILES } from './paths.js';
+import { assertNoSecrets } from './secretScan.js';
+
+/**
+ * The aggregate: every terminal run of a job merged into the one report a
+ * developer actually reads (the `aggregate-report` skill, spec 11 section 3).
+ *
+ * Two passes, and only the first of them needs a model:
+ *
+ * - **Pass 1, dedup.** Candidate clusters are built locally from a
+ *   normalised signature (category plus the title's key nouns, plus shared
+ *   evidence refs), and then a cheap yes/no per cluster decides whether the
+ *   members really are one issue. The clustering is local because it is
+ *   mechanical, and a model call per pair would cost more than the whole
+ *   report.
+ * - **Pass 2, ranking.** Entirely deterministic: the skill fixes the
+ *   formula, and same inputs must produce the same order. There is nothing
+ *   here for a model to decide, so nothing is asked of one.
+ *
+ * ## The aggregate run
+ *
+ * `aggregate.*` steps are only spendable from a run whose module is
+ * `aggregate_report`: the proxy maps a run's module onto a step prefix and
+ * answers 400 `step_not_allowed` otherwise. A job that asks for the
+ * `aggregate_report` module gets that run, so both passes are reachable and
+ * both are used.
+ *
+ * Pass 2's judgement is the part a developer actually reads, and it is the
+ * part only a model can do: which success criteria were met, which issues the
+ * brief already knew about, and which ones the game's stated design intent
+ * explains. All three are applied to the locally ranked issues rather than
+ * letting the model rewrite them, so the ranking stays deterministic and the
+ * model's job stays "decide", not "recompute".
+ *
+ * `aggregateRunId` is still optional, and without one the aggregate is the
+ * local clustering and ranking alone with `provenance.generated_from` set to
+ * `local_dedup`, so nobody mistakes it for a judged merge. That is the
+ * fallback for a job registered without the module, not the normal path.
+ */
+
+/** From the skill's ranking formula. */
+export const SEVERITY_WEIGHT = Object.freeze({ blocker: 100, major: 40, minor: 10, cosmetic: 2, praise: 0 });
+
+/** Severities that need evidence to survive the quality gate. */
+export const NEEDS_EVIDENCE = Object.freeze(['blocker', 'major', 'minor']);
+
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'is', 'are', 'was', 'were', 'to', 'of', 'in', 'on', 'at', 'for', 'and', 'or',
+  'it', 'its', 'this', 'that', 'with', 'when', 'after', 'before', 'from', 'by', 'you', 'your',
+  'but', 'not', 'no', 'can', 'cannot', 'does', 'do', 'did', 'be', 'been', 'has', 'have', 'had'
+]);
+
+/**
+ * `category | sorted key nouns`. Lowercased, stopwords stripped, sorted so
+ * two titles with the same words in a different order collide on purpose.
+ *
+ * @param {Object} finding
+ * @returns {string}
+ */
+export function signatureFor(finding) {
+  const tokens = String((finding && finding.title) || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter(token => token.length > 2 && !STOPWORDS.has(token))
+    .sort();
+  return `${(finding && finding.category) || 'unknown'}|${[...new Set(tokens)].join(' ')}`;
+}
+
+/**
+ * A stable id, derived from the cluster's signature rather than random.
+ *
+ * The skill asks for `iss_<ulid>` and for stable ids across regeneration.
+ * Those pull in opposite directions, and stability is the one that matters
+ * to a reader: an issue the developer marked last week has to be the same
+ * issue after a regenerate. So the id is a hash of the signature, which is
+ * stable by construction.
+ *
+ * @param {string} signature
+ * @returns {string}
+ */
+export function issueId(signature) {
+  return `iss_${createHash('sha256').update(signature, 'utf8').digest('hex').slice(0, 26)}`;
+}
+
+/**
+ * Candidate clusters: same signature, or a shared evidence ref.
+ *
+ * @param {Array<{runId: string, persona: string, findings: Array}>} runs
+ * @returns {Array<{signature: string, members: Array}>}
+ */
+export function clusterFindings(runs) {
+  /** @type {Map<string, Array>} */
+  const bySignature = new Map();
+  /** @type {Map<string, string>} */
+  const byEvidence = new Map();
+
+  for (const run of runs) {
+    for (const finding of run.findings || []) {
+      const member = {
+        ref: `${run.runId}:${finding.id}`,
+        runId: run.runId,
+        persona: run.persona,
+        finding
+      };
+      let signature = signatureFor(finding);
+      // A shared evidence ref is strong enough to pull two differently
+      // worded findings into one candidate cluster.
+      for (const item of finding.evidence || []) {
+        if (!item || (item.type !== 'screenshot' && item.type !== 'file_line')) continue;
+        const key = `${item.type}:${item.ref}`;
+        const existing = byEvidence.get(key);
+        if (existing) signature = existing;
+        else byEvidence.set(key, signature);
+      }
+      const bucket = bySignature.get(signature) || [];
+      bucket.push(member);
+      bySignature.set(signature, bucket);
+    }
+  }
+
+  return [...bySignature.entries()]
+    .map(([signature, members]) => ({ signature, members }))
+    .sort((a, b) => a.signature.localeCompare(b.signature));
+}
+
+/**
+ * Pass 1's model turn, batched: one call for all the multi-member clusters,
+ * asking only whether each really is one issue and what to call it.
+ *
+ * `aggregate.dedup` allows no client tools and 512 output tokens, so the
+ * answer has to be small: a JSON array, one entry per cluster.
+ *
+ * @returns {Promise<Map<string, {same: boolean, title: string|null}>>}
+ */
+export async function judgeClusters({ client, jobId, runId, clusters, log = () => {} }) {
+  const verdicts = new Map();
+  const ambiguous = clusters.filter(cluster => cluster.members.length > 1);
+  if (ambiguous.length === 0 || !runId) return verdicts;
+
+  const prompt = [
+    'For each cluster below, answer whether the findings describe the same underlying issue.',
+    'Answer with JSON only: [{"cluster": <index>, "same": true|false, "title": "<canonical title>"}].',
+    'Two findings in the same area are NOT the same issue unless their actual content says so.',
+    '',
+    ...ambiguous.map((cluster, index) => [
+      `cluster ${index}:`,
+      ...cluster.members.map(member => `  - [${member.finding.severity}/${member.finding.category}] ${member.finding.title}: ${String(member.finding.description || '').slice(0, 300)}`)
+    ].join('\n'))
+  ].join('\n');
+
+  try {
+    const answer = await callStepWithRetry({
+      client,
+      jobId,
+      runId,
+      step: STEPS.aggregateDedup,
+      messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+      maxTokens: 512
+    });
+    for (const entry of parseJsonArray(answer.text)) {
+      const cluster = ambiguous[Number(entry.cluster)];
+      if (!cluster) continue;
+      verdicts.set(cluster.signature, { same: entry.same !== false, title: entry.title || null });
+    }
+  } catch (error) {
+    // A dedup that could not be judged is not worth failing a job over: the
+    // local clustering is the fallback and it is deterministic. A budget
+    // refusal in particular has to reach the caller though, because it
+    // decides the exit code.
+    if (error instanceof ProxyError && (error.isBudget || error.isClosed)) throw error;
+    log(`dedup pass skipped: ${String(error && error.message)}`);
+  }
+  return verdicts;
+}
+
+/**
+ * The quality gate: a finding of `minor` or worse with no evidence is not an
+ * issue, it is an observation. Applied to MEMBER findings before clustering,
+ * as the skill specifies.
+ *
+ * @param {Array} runs
+ * @returns {{kept: Array, observations: Array}}
+ */
+export function applyQualityGate(runs) {
+  const kept = [];
+  const observations = [];
+  for (const run of runs) {
+    const findings = [];
+    for (const finding of run.findings || []) {
+      const hasEvidence = Array.isArray(finding.evidence) && finding.evidence.length > 0;
+      if (!hasEvidence && NEEDS_EVIDENCE.includes(finding.severity)) {
+        observations.push({ runId: run.runId, persona: run.persona, finding });
+        continue;
+      }
+      findings.push(finding);
+    }
+    kept.push({ ...run, findings });
+  }
+  return { kept, observations };
+}
+
+/**
+ * One cluster becomes one issue.
+ *
+ * @param {{signature: string, members: Array}} cluster
+ * @param {{same: boolean, title: string|null}|undefined} verdict
+ * @returns {Array<Object>} one issue, or one issue per member when the judge
+ *   said they are different
+ */
+export function toIssues(cluster, verdict) {
+  const split = cluster.members.length > 1 && verdict && verdict.same === false;
+  if (split) {
+    return cluster.members.map(member => buildIssue(`${cluster.signature}#${member.ref}`, [member], null));
+  }
+  return [buildIssue(cluster.signature, cluster.members, verdict ? verdict.title : null)];
+}
+
+function buildIssue(signature, members, canonicalTitle) {
+  const severities = members.map(member => member.finding.severity);
+  const worst = ['blocker', 'major', 'minor', 'cosmetic', 'praise'].find(level => severities.includes(level)) || 'minor';
+  const personas = [...new Set(members.map(member => member.persona).filter(Boolean))];
+  const evidence = [];
+  const seen = new Set();
+  for (const member of members) {
+    for (const item of member.finding.evidence || []) {
+      const key = `${item.type}:${item.ref}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      evidence.push(item);
+    }
+  }
+  const quotes = [];
+  const quoted = new Set();
+  for (const member of members) {
+    const quote = member.finding.persona_quote;
+    if (!quote || quoted.has(member.persona) || quotes.length >= 3) continue;
+    quoted.add(member.persona);
+    quotes.push({ persona: member.persona, text: quote });
+  }
+  // The shortest complete repro, not a concatenation: a developer has to be
+  // able to follow one of them standalone.
+  const repro = members
+    .map(member => member.finding.repro_steps || [])
+    .filter(steps => steps.length > 0)
+    .sort((a, b) => a.join(' ').length - b.join(' ').length)[0] || [];
+
+  return {
+    issue_id: issueId(signature),
+    label: null,
+    title: canonicalTitle || members[0].finding.title,
+    category: majority(members.map(member => member.finding.category)),
+    severity: worst,
+    personas_affected: personas,
+    occurrences: members.length,
+    repro_steps: repro,
+    evidence,
+    quotes,
+    member_findings: members.map(member => member.ref),
+    description: members[0].finding.description
+  };
+}
+
+function majority(values) {
+  const counts = new Map();
+  for (const value of values) counts.set(value, (counts.get(value) || 0) + 1);
+  return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0][0];
+}
+
+/**
+ * Pass 2, exactly the skill's formula. Deterministic, and there is a test
+ * that proves the same inputs give the same order.
+ *
+ * `confidence` is 1 for every member: the run report schema has no
+ * `confidence` field (`additionalProperties: false`, and the finding
+ * properties are fixed), so there is nothing to average. Kept in the formula
+ * rather than dropped, so adding the field later changes one line.
+ *
+ * `telemetry_bonus` is 1: it needs real-player analytics, which this CLI has
+ * no scope to read.
+ *
+ * @param {Array<Object>} issues
+ * @param {number} personasRun
+ * @returns {{issues: Array<Object>, praise: Array<Object>}}
+ */
+export function rankIssues(issues, personasRun) {
+  const scored = issues.map(issue => {
+    const breadth = personasRun > 0 ? issue.personas_affected.length / personasRun : 0;
+    const confidence = 1;
+    const kinds = new Set((issue.evidence || []).map(item => item && item.type));
+    const evidenceBonus = (kinds.has('screenshot') || kinds.has('video_ts') ? 1.2 : 1) * (kinds.has('file_line') ? 1.1 : 1);
+    const score = SEVERITY_WEIGHT[issue.severity] * (0.5 + 0.5 * breadth) * confidence * evidenceBonus * 1;
+    return { ...issue, score: Number(score.toFixed(6)), breadth: Number(breadth.toFixed(6)) };
+  });
+
+  const praise = scored
+    .filter(issue => issue.severity === 'praise')
+    .sort((a, b) => b.breadth - a.breadth || a.issue_id.localeCompare(b.issue_id));
+  const ranked = scored
+    .filter(issue => issue.severity !== 'praise')
+    .sort((a, b) => b.score - a.score || a.issue_id.localeCompare(b.issue_id))
+    .map((issue, index) => ({ ...issue, label: `I${index + 1}` }));
+  return { issues: ranked, praise: praise.map((issue, index) => ({ ...issue, label: `P${index + 1}` })) };
+}
+
+/**
+ * @param {Object} args
+ * @returns {Promise<{json: Object, markdown: string}>}
+ */
+export async function buildAggregate({
+  client,
+  jobId,
+  gameId,
+  aggregateRunId = null,
+  runs,
+  brief = null,
+  capabilityNotes = [],
+  intentNotes = [],
+  promptVersion = 'aggregate-report@0.1.0',
+  ledger = null,
+  log = () => {}
+}) {
+  const terminal = runs.filter(run => run && run.report);
+  const inputs = terminal.map(run => ({
+    runId: run.runId,
+    persona: run.persona,
+    state: run.state,
+    report: run.report,
+    findings: run.report.findings || []
+  }));
+  const personasRun = new Set(inputs.map(run => run.persona).filter(Boolean)).size;
+
+  const { kept, observations } = applyQualityGate(inputs);
+  const clusters = clusterFindings(kept);
+  const verdicts = aggregateRunId
+    ? await judgeClusters({ client, jobId, runId: aggregateRunId, clusters, log })
+    : new Map();
+
+  const issues = clusters.flatMap(cluster => toIssues(cluster, verdicts.get(cluster.signature)));
+  const ranked = rankIssues(issues, personasRun);
+
+  const partial = runs.some(run => !run.report || ['failed', 'canceled', 'budget_exceeded'].includes(run.state));
+  const judgement = aggregateRunId
+    ? await judgeAggregate({ client, jobId, runId: aggregateRunId, ranked, inputs, brief, intentNotes, ledger, log })
+    : null;
+  const applied = applyJudgement({ ranked, brief, intentNotes, judgement });
+  const json = {
+    schema_version: '1.0',
+    report_id: `agg_${createHash('sha256').update(jobId, 'utf8').digest('hex').slice(0, 26)}`,
+    report_version: 1,
+    job_id: jobId,
+    game_id: gameId,
+    provenance: {
+      brief_id: brief ? brief.brief_id || brief.briefId || null : null,
+      brief_version: brief ? brief.version ?? null : null,
+      prompt_version: promptVersion,
+      design_intent_version: intentNotes.length,
+      generated_from: aggregateRunId ? 'live_run' : 'local_dedup'
+    },
+    success_criteria: applied.successCriteria,
+    excluded_by_intent: applied.excludedByIntent,
+    known_issues: applied.known,
+    tldr: applied.tldr,
+    generated_at: new Date().toISOString(),
+    partial,
+    runs: inputs.map(run => ({
+      run_id: run.runId,
+      persona: run.persona,
+      state: run.state,
+      actions_taken: run.report.actions_taken,
+      quit_reason: run.report.quit_reason,
+      sentiment: run.report.sentiment,
+      would_continue: run.report.would_continue
+    })),
+    issues: applied.issues,
+    praise: ranked.praise,
+    observations: observations.map(entry => ({
+      run_id: entry.runId,
+      persona: entry.persona,
+      text: `${entry.finding.title}: ${entry.finding.description}`,
+      dropped_for: 'no evidence'
+    })),
+    capability_notes: capabilityNotes.length > 0 ? capabilityNotes : ['No capability limits noted for this job.'],
+    usage: ledger ? aggregateUsage(ledger) : { usd: 0, by_model: {} }
+  };
+
+  return { json, markdown: renderAggregateMarkdown(json) };
+}
+
+/**
+ * The aggregate's own usage, in the shape spec 11 documents for this report
+ * (`{ usd, by_model }`, a map rather than the run report's array).
+ *
+ * @param {Object} ledger
+ * @returns {{usd: number, by_model: Object}}
+ */
+export function aggregateUsage(ledger) {
+  const usage = ledger.toReportUsage();
+  return {
+    usd: usage.total_usd,
+    by_model: Object.fromEntries(usage.by_model.map(entry => [entry.model, {
+      input_tokens: entry.input_tokens,
+      cache_read_tokens: entry.cache_read_tokens,
+      output_tokens: entry.output_tokens
+    }]))
+  };
+}
+
+/**
+ * Pass 2's judgement: the three questions only a model can answer about a
+ * ranked list of issues.
+ *
+ * It is deliberately NOT allowed to reorder or rewrite the issues. The ranking
+ * is a formula the skill fixes and a test pins, so letting a model restate it
+ * would make the same inputs produce different orders. What comes back is a set
+ * of verdicts keyed by id, applied locally by `applyJudgement`.
+ *
+ * `aggregate.synthesis` allows `read_file`; nothing is sent, because every
+ * input is already in the prompt and a tool the step does not need is a tool
+ * that can go wrong.
+ *
+ * @returns {Promise<Object|null>} null when the pass could not be made
+ */
+export async function judgeAggregate({ client, jobId, runId, ranked, inputs, brief, intentNotes, ledger, log = () => {} }) {
+  const fields = (brief && brief.fields) || {};
+  const criteria = criteriaFrom(brief);
+  const known = Array.isArray(fields.known_issues) ? fields.known_issues : [];
+  const intent = [
+    ...(Array.isArray(fields.design_intent_notes) ? fields.design_intent_notes : []).map(note => (typeof note === 'string' ? note : note.text || '')),
+    ...(intentNotes || []).map(note => note.text)
+  ].filter(Boolean);
+
+  const prompt = [
+    'You are finishing a playtest aggregate. The issues below are already merged and ranked; do not reorder or rewrite them.',
+    'Answer with JSON only, in this shape:',
+    '{"success_criteria":[{"criterion_id":"sc_1","result":"met|partly|not met|not testable","evidence":["iss_..."]}],',
+    ' "known":["iss_..."], "excluded_by_intent":[{"issue_id":"iss_...","intent":"<the stated intent it matches>"}],',
+    ' "tldr":["up to five short bullets: the most important fixes and the strongest positive signal"]}',
+    '',
+    'Rules. A criterion no run touched is "not testable"; never invent evidence for one. An issue is "known" only when the brief already describes it. An issue is excluded by intent only when the persona experience is CONSISTENT with the stated intent; when it CONTRADICTS the intent, leave it in the list, because that is the valuable case.',
+    '',
+    `success criteria:\n${criteria.length > 0 ? criteria.map(row => `  ${row.criterion_id}: ${row.text}`).join('\n') : '  (none stated)'}`,
+    `known issues from the brief:\n${known.length > 0 ? known.map(entry => `  - ${typeof entry === 'string' ? entry : JSON.stringify(entry)}`).join('\n') : '  (none)'}`,
+    `stated design intent:\n${intent.length > 0 ? intent.map(entry => `  - ${entry}`).join('\n') : '  (none)'}`,
+    '',
+    `issues:\n${ranked.issues.map(issue => `  ${issue.issue_id} [${issue.severity}/${issue.category}] ${issue.title}: ${String(issue.description || '').slice(0, 300)} (personas: ${issue.personas_affected.join(', ') || 'none'})`).join('\n') || '  (none)'}`,
+    `praise:\n${ranked.praise.map(issue => `  ${issue.issue_id} ${issue.title}`).join('\n') || '  (none)'}`,
+    `runs:\n${inputs.map(run => `  ${run.persona}: ${run.report.actions_taken} actions, ${run.report.quit_reason}, would_continue=${run.report.would_continue}`).join('\n') || '  (none)'}`
+  ].join('\n');
+
+  try {
+    const answer = await callStepWithRetry({
+      client,
+      jobId,
+      runId,
+      step: STEPS.aggregateSynthesis,
+      messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+      maxTokens: 8192
+    });
+    if (ledger) ledger.record({ model: answer.model, usage: answer.usage });
+    return parseJsonObject(answer.text);
+  } catch (error) {
+    // A budget or cancel refusal decides the caller's exit code and has to
+    // reach it. Anything else leaves the locally ranked aggregate standing,
+    // which is still the report a developer can read.
+    if (error instanceof ProxyError && (error.isBudget || error.isClosed)) throw error;
+    log(`aggregate synthesis skipped: ${String(error && error.message)}`);
+    return null;
+  }
+}
+
+/**
+ * Apply the judgement to the ranked issues. Every decision here is a lookup by
+ * id, so an answer naming an issue that does not exist is ignored rather than
+ * able to invent one.
+ *
+ * @returns {{issues: Array, known: Array, excludedByIntent: Array, successCriteria: Array, tldr: Array}}
+ */
+export function applyJudgement({ ranked, brief, judgement }) {
+  const criteria = criteriaFrom(brief);
+  if (!judgement) {
+    return { issues: ranked.issues, known: [], excludedByIntent: [], successCriteria: criteria, tldr: [] };
+  }
+
+  const byId = new Map(ranked.issues.map(issue => [issue.issue_id, issue]));
+  const knownIds = new Set((Array.isArray(judgement.known) ? judgement.known : []).filter(id => byId.has(id)));
+  const excluded = (Array.isArray(judgement.excluded_by_intent) ? judgement.excluded_by_intent : [])
+    .filter(entry => entry && byId.has(entry.issue_id));
+  const excludedIds = new Set(excluded.map(entry => entry.issue_id));
+
+  const verdicts = new Map(
+    (Array.isArray(judgement.success_criteria) ? judgement.success_criteria : [])
+      .map(row => [row && row.criterion_id, row])
+  );
+  const allowed = new Set(['met', 'partly', 'not met', 'not testable']);
+
+  return {
+    // A known or intent-explained issue leaves the ranked list, which is what
+    // "excluded from Top issues" means; it is still reported, in its own
+    // section, because a confirmed known issue is information too.
+    issues: ranked.issues
+      .filter(issue => !knownIds.has(issue.issue_id) && !excludedIds.has(issue.issue_id))
+      .map((issue, index) => ({ ...issue, label: `I${index + 1}` })),
+    known: ranked.issues.filter(issue => knownIds.has(issue.issue_id)).map(issue => ({ ...issue, known: true })),
+    excludedByIntent: excluded.map(entry => ({
+      issue_id: entry.issue_id,
+      title: byId.get(entry.issue_id).title,
+      matched_intent_entry: String(entry.intent || '')
+    })),
+    successCriteria: criteria.map(row => {
+      const verdict = verdicts.get(row.criterion_id);
+      const result = verdict && allowed.has(verdict.result) ? verdict.result : 'not testable';
+      const evidence = verdict && Array.isArray(verdict.evidence) ? verdict.evidence.filter(id => byId.has(id)) : [];
+      return { ...row, result, evidence };
+    }),
+    tldr: (Array.isArray(judgement.tldr) ? judgement.tldr : []).map(line => String(line)).slice(0, 5)
+  };
+}
+
+/**
+ * The criteria the brief actually states, one row each, every one starting at
+ * `not testable`. `success_criteria` is a single string in the brief schema, so
+ * one line is one criterion.
+ *
+ * Starting at `not testable` rather than at `met` is the point: a verdict has
+ * to be earned by the judgement pass, and a job that never made that pass
+ * should say "not testable" rather than imply anything.
+ *
+ * @param {Object|null} brief
+ * @returns {Array<{criterion_id: string, text: string, result: string, evidence: Array}>}
+ */
+export function criteriaFrom(brief) {
+  const fields = (brief && brief.fields) || brief || {};
+  const text = typeof fields.success_criteria === 'string' ? fields.success_criteria.trim() : '';
+  if (!text) return [];
+  return text
+    .split('\n')
+    .map(line => line.replace(/^[-*\d.\s]+/, '').trim())
+    .filter(Boolean)
+    .map((criterion, index) => ({ criterion_id: `sc_${index + 1}`, text: criterion, result: 'not testable', evidence: [] }));
+}
+
+/**
+ * The fixed headings, in the skill's order, so the dashboard and any future
+ * parser can find a section by name.
+ *
+ * @param {Object} json
+ * @returns {string}
+ */
+export function renderAggregateMarkdown(json) {
+  const lines = [];
+  lines.push(`# Playtest Report: ${json.game_id}`);
+  lines.push(`**Job:** ${json.job_id} - **Date:** ${json.generated_at} - **Personas:** ${json.runs.length}`);
+  if (json.partial) {
+    lines.push('');
+    lines.push('> Partial: at least one run did not finish, so this report does not cover the whole pack.');
+  }
+  lines.push('');
+  lines.push('## TL;DR');
+  const top = json.issues.slice(0, 5);
+  if (Array.isArray(json.tldr) && json.tldr.length > 0) {
+    lines.push(json.tldr.map(line => `- ${line}`).join('\n'));
+  } else {
+    lines.push(top.length > 0
+      ? top.map(issue => `- ${issue.label} ${issue.title} (${issue.severity}, ${issue.occurrences} of ${json.runs.length} personas)`).join('\n')
+      : '- No ranked issues: no run produced an evidenced finding.');
+  }
+  lines.push('');
+  lines.push('## Against your success criteria');
+  lines.push('| Criterion | Result | Evidence |');
+  lines.push('|---|---|---|');
+  for (const row of json.success_criteria) lines.push(`| ${row.text} | ${row.result} | ${row.evidence.join(', ') || 'none'} |`);
+  if (json.success_criteria.length === 0) lines.push('| (the brief states no success criteria) | not testable | none |');
+  lines.push('');
+  lines.push('## Scorecard');
+  lines.push('| Persona | Actions | Quit reason | Fun | Clarity | Frustration | Would continue |');
+  lines.push('|---|---|---|---|---|---|---|');
+  for (const run of json.runs) {
+    const sentiment = run.sentiment || {};
+    lines.push(`| ${run.persona} | ${run.actions_taken} | ${run.quit_reason} | ${sentiment.fun ?? '-'} | ${sentiment.clarity ?? '-'} | ${sentiment.frustration ?? '-'} | ${run.would_continue ? 'yes' : 'no'} |`);
+  }
+  lines.push('');
+  lines.push('## Top issues (ranked)');
+  if (json.issues.length === 0) lines.push('None.');
+  for (const issue of json.issues) {
+    lines.push(`### ${issue.label}: ${issue.title}  \`${issue.severity}\` - ${issue.category} - ${issue.occurrences}/${json.runs.length} personas`);
+    lines.push(`**Why it matters:** ${issue.description || ''}`);
+    if (issue.repro_steps.length > 0) lines.push(`**Repro:** ${issue.repro_steps.map((step, i) => `${i + 1}. ${step}`).join(' ')}`);
+    lines.push(`**Evidence:** ${issue.evidence.map(item => `${item.type} ${item.ref}`).join(', ') || 'none'}`);
+    for (const quote of issue.quotes) lines.push(`**Voices:** > "${quote.text}" (${quote.persona})`);
+    lines.push('');
+  }
+  lines.push("## What's working");
+  lines.push(json.praise.length > 0
+    ? json.praise.map(issue => `- ${issue.title} (${issue.personas_affected.join(', ')})`).join('\n')
+    : '- Nothing was logged as praise.');
+  lines.push('');
+  lines.push('## Confirmed known issues');
+  lines.push((json.known_issues || []).length > 0
+    ? json.known_issues.map(issue => `- ${issue.title} (${issue.severity}, ${issue.occurrences} occurrence(s))`).join('\n')
+    : 'None: nothing this pack found matches an issue the brief already describes.');
+  if ((json.excluded_by_intent || []).length > 0) {
+    lines.push('');
+    lines.push('### Suppressed as intended');
+    lines.push(json.excluded_by_intent.map(entry => `- ${entry.title} (matches: ${entry.matched_intent_entry})`).join('\n'));
+  }
+  lines.push('');
+  lines.push('## Capability notes');
+  lines.push(json.capability_notes.map(note => `- ${note}`).join('\n'));
+  lines.push('');
+  lines.push('## Appendix');
+  lines.push(json.observations.length > 0
+    ? `Observations dropped for lack of evidence:\n${json.observations.map(o => `- ${o.persona}: ${o.text}`).join('\n')}`
+    : 'No dropped observations.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Write both aggregate files into the job directory.
+ *
+ * @param {string} jobDirectory
+ * @param {{json: Object, markdown: string}} aggregate
+ * @returns {Promise<{jsonPath: string, markdownPath: string}>}
+ */
+export async function writeAggregate(jobDirectory, aggregate) {
+  const body = `${JSON.stringify(aggregate.json, null, 2)}\n`;
+  assertNoSecrets('aggregate-report.json', body);
+  assertNoSecrets('aggregate-report.md', aggregate.markdown);
+  const jsonPath = path.join(jobDirectory, JOB_FILES.aggregateJson);
+  const markdownPath = path.join(jobDirectory, JOB_FILES.aggregateMd);
+  await writeFile(jsonPath, body, 'utf8');
+  await writeFile(markdownPath, aggregate.markdown, 'utf8');
+  return { jsonPath, markdownPath };
+}
+
+export { parseJsonArray };
+
+export default {
+  buildAggregate,
+  judgeAggregate,
+  applyJudgement,
+  criteriaFrom,
+  aggregateUsage,
+  clusterFindings,
+  rankIssues,
+  applyQualityGate,
+  renderAggregateMarkdown,
+  writeAggregate,
+  signatureFor,
+  issueId,
+  parseJsonArray
+};