clud-bug 0.6.34 → 0.7.0-rc.2

package/{lib/render-review.js → src/core/render-review.ts}

@@ -15,21 +15,52 @@
 // rendered shape is wrong). Centralising the markdown shape here means a
 // future format tweak edits one function rather than the prompt.
 
-const SEVERITY_EMOJI = { critical: '🔴', minor: '🟡', preexisting: '🟣' };
-const SEVERITY_LABEL = {
+import type {
+  DedicatedSection,
+  FindingSeverity,
+  PerSkillScanItem,
+  ReviewData,
+  ReviewFinding,
+  ReviewSummaryCounts,
+} from './review-schema.js';
+
+// Emoji constants: use explicit Unicode escape literals (`\u{HHHHH}`) so
+// every step of the TS→JS toolchain — tsc, vitest's transformer, the
+// publisher's tarball — emits the same byte sequence regardless of
+// editor encoding settings. Per SPEC §6 byte-identical contract:
+//   \u{1F534} = 🔴 (red circle, critical / "important")
+//   \u{1F7E1} = 🟡 (yellow circle, minor / "nit")
+//   \u{1F7E3} = 🟣 (purple circle, pre-existing)
+//   \u{1F41B} = 🐛 (bug, H2 anchor for `## 🐛 Clud Bug review`)
+const SEVERITY_EMOJI: Record<FindingSeverity, string> = {
+  critical: '\u{1F534}',
+  minor: '\u{1F7E1}',
+  preexisting: '\u{1F7E3}',
+};
+const SEVERITY_LABEL: Record<FindingSeverity, string> = {
   critical: 'important',
   minor: 'nit',
   preexisting: 'pre-existing',
 };
+// SEVERITY_LABEL is retained for callers that import the constant table
+// (the JS version exported it implicitly via module scope; keep the
+// export so future renderer extensions can reuse it).
+export { SEVERITY_LABEL };
+
+// Renderer input type — schema-aligned but defensively typed. The renderer
+// is the last line of defense against malformed JSON, so it accepts an
+// "unknown-ish" shape and degrades gracefully rather than throwing on
+// missing fields.
+type RenderReviewInput = Partial<ReviewData> & Record<string, unknown>;
 
 // Render the full summary comment markdown. `data` is the parsed JSON
-// matching the schema (see schema.js). Returns a string suitable for
-// `gh pr comment --body`.
-export function renderReview(data) {
+// matching the schema (see review-schema.ts). Returns a string suitable
+// for `gh pr comment --body`.
+export function renderReview(data: RenderReviewInput | null | undefined): string {
   if (!data || typeof data !== 'object') {
     throw new TypeError('renderReview: data must be an object');
   }
-  const out = [];
+  const out: string[] = [];
   out.push(renderHeader(data));
   out.push('');
   out.push(renderStatusLine(data.summary_counts));
@@ -77,9 +108,9 @@ export function renderReview(data) {
   return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '') + '\n';
 }
 
-function renderHeader(data) {
+function renderHeader(data: RenderReviewInput): string {
   const verdict = data.status_header;
-  const base = '## 🐛 Clud Bug review';
+  const base = '## \u{1F41B} Clud Bug review';
   if (verdict === 'critical findings') return `${base} — critical findings`;
   if (verdict === 'clean') return `${base} — clean`;
   // 'bare' (non-strict-mode default) OR an unexpected verdict — render
@@ -87,7 +118,7 @@ function renderHeader(data) {
   return base;
 }
 
-function renderStatusLine(counts) {
+function renderStatusLine(counts: ReviewSummaryCounts | undefined): string {
   const c = sanitizeCounts(counts);
   return `**This round:** ${c.critical} critical · ${c.minor} minor · ${c.resolved_from_prior} resolved from prior · ${c.still_open} still open`;
 }
@@ -95,13 +126,13 @@ function renderStatusLine(counts) {
 // Severity-emoji stats header. Counts pre-existing in 🟣 even though
 // it's not in summary_counts (the prompt counts pre-existing separately
 // in preexisting_findings.length).
-function renderStatsHeader(counts) {
+function renderStatsHeader(counts: ReviewSummaryCounts | undefined): string {
   const c = sanitizeCounts(counts);
-  return `Found: ${c.critical} 🔴 / ${c.minor} 🟡 / ${c.preexisting} 🟣`;
+  return `Found: ${c.critical} \u{1F534} / ${c.minor} \u{1F7E1} / ${c.preexisting} \u{1F7E3}`;
 }
 
-function renderPerSkillScan(scan) {
-  const out = ['### Per-skill scan'];
+function renderPerSkillScan(scan: PerSkillScanItem[] | undefined): string[] {
+  const out: string[] = ['### Per-skill scan'];
   if (!Array.isArray(scan) || scan.length === 0) {
     out.push('- (no skills loaded — review proceeded against the baseline.)');
     return out;
@@ -116,14 +147,14 @@ function renderPerSkillScan(scan) {
   return out;
 }
 
-function renderDedicatedSection(section) {
+function renderDedicatedSection(section: DedicatedSection | undefined): string[] {
   if (!section || typeof section !== 'object') return [];
   const name = String(section.section_name || '').trim();
   const skill = String(section.skill || '').trim();
   const header = skill && name
     ? `### ${name} [${skill}]`
     : `### ${name || skill || 'Dedicated section'}`;
-  const out = [header, ''];
+  const out: string[] = [header, ''];
   if (Array.isArray(section.findings) && section.findings.length > 0) {
     // Dedicated-section findings use the same emoji-prefix block.
     // Default severity for dedicated sections is "critical" — they're
@@ -135,9 +166,10 @@ function renderDedicatedSection(section) {
   return out;
 }
 
-function renderFindings(findings, severity) {
-  const emoji = SEVERITY_EMOJI[severity] || '🔴';
-  const out = [];
+function renderFindings(findings: ReviewFinding[] | undefined, severity: FindingSeverity): string[] {
+  const emoji = SEVERITY_EMOJI[severity] || SEVERITY_EMOJI.critical;
+  const out: string[] = [];
+  if (!Array.isArray(findings)) return out;
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue;
     const skill = String(f.skill || '').trim();
@@ -163,7 +195,7 @@ function renderFindings(findings, severity) {
   return out;
 }
 
-function renderSkillsReferenced(skills) {
+function renderSkillsReferenced(skills: string[] | undefined): string {
   if (!Array.isArray(skills) || skills.length === 0) {
     return 'Skills referenced: [none] — no installed skill applied to this diff.';
   }
@@ -172,12 +204,12 @@ function renderSkillsReferenced(skills) {
 
 // --- helpers ---
 
-function nonEmpty(arr) {
+function nonEmpty<T>(arr: T[] | undefined): arr is T[] {
   return Array.isArray(arr) && arr.length > 0;
 }
 
-function sanitizeCounts(counts) {
-  const c = counts && typeof counts === 'object' ? counts : {};
+function sanitizeCounts(counts: ReviewSummaryCounts | undefined): ReviewSummaryCounts {
+  const c = counts && typeof counts === 'object' ? counts : ({} as Partial<ReviewSummaryCounts>);
   return {
     critical: numOrZero(c.critical),
     minor: numOrZero(c.minor),
@@ -187,18 +219,18 @@ function sanitizeCounts(counts) {
   };
 }
 
-function numOrZero(v) {
+function numOrZero(v: unknown): number {
   const n = Number(v);
   return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
 }
 
-function locationAnchor(f) {
+function locationAnchor(f: ReviewFinding): string | null {
   const file = String(f.file || '').trim();
   if (!file) return null;
   const line = Number(f.line);
   return Number.isFinite(line) && line > 0 ? `${file}:${line}` : file;
 }
 
-function stripTrailingPunctuation(s) {
+function stripTrailingPunctuation(s: string): string {
   return s.replace(/[.!?]+$/, '');
 }

package/{lib/render.js → src/core/render.ts}

@@ -12,11 +12,28 @@ const PLACEHOLDER_RE = /\{\{([A-Z_]+)\}\}/g;
 // structured output to markdown. Pinning to the version that ran
 // `clud-bug init` guarantees the renderer's output shape matches the
 // prompt's expectations.
+//
+// IMPORTANT (v0.7.0 TS migration): the JS source lived at lib/render.js,
+// so `join(__dirname, '..', 'package.json')` reached the package root
+// from one level up. The TS port compiles to dist/core/render.js, which
+// is TWO levels deep (dist/core/) — so we walk up TWO levels to find
+// package.json. Without this adjustment, module-load would throw at
+// runtime with "ENOENT dist/package.json". Verify on rebuild via:
+//   node -e "import('./dist/core/render.js').then(m => console.log(m.DEFAULTS.CLUD_BUG_VERSION))"
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const PKG_VERSION = JSON.parse(
-  readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
+const PKG_VERSION: string = (
+  JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8')) as { version: string }
 ).version;
 
+// Public shape of the DEFAULTS map. Tests assert presence of CCA_VERSION
+// and CLUD_BUG_VERSION; REVIEW_SCHEMA is the serialized schema string the
+// templates inject via the {{REVIEW_SCHEMA}} placeholder.
+export interface RenderDefaults {
+  CCA_VERSION: string;
+  CLUD_BUG_VERSION: string;
+  REVIEW_SCHEMA: string;
+}
+
 // Default values for substitution tokens that every template uses.
 // Callers can override per-render by passing the same key in `vars`.
 //
@@ -26,19 +43,26 @@ const PKG_VERSION = JSON.parse(
 // workflows mid-cycle. Bumping the pin requires a clud-bug release, which
 // makes the upgrade visible + lets users opt out by pinning a different
 // version in their own forked workflow.
-export const DEFAULTS = {
+export const DEFAULTS: RenderDefaults = {
   CCA_VERSION: 'v1.0.133',
   CLUD_BUG_VERSION: PKG_VERSION,
   REVIEW_SCHEMA: serializedReviewSchema(),
 };
 
+// Caller-supplied substitution vars: any extra placeholders the template
+// uses (REVIEW_PROMPT, PROJECT_DESCRIPTION, etc.). Values may be strings,
+// numbers, or anything String()-coercible. We accept a wider unknown type
+// because the JS callers freely pass numbers, arrays, etc., and the
+// String(value) coercion below handles them uniformly.
+export type RenderVars = Partial<RenderDefaults> & Record<string, unknown>;
+
 // Multi-line value substitution preserves YAML/Markdown indentation by
 // applying the placeholder line's leading whitespace to every
 // continuation line. Single-line values pass through unchanged so
 // existing tokens (CCA_VERSION, PROJECT_DESCRIPTION) keep current behavior.
-export function render(template, vars) {
-  const merged = { ...DEFAULTS, ...vars };
-  return template.replace(PLACEHOLDER_RE, (match, key, offset) => {
+export function render(template: string, vars: RenderVars): string {
+  const merged: Record<string, unknown> = { ...DEFAULTS, ...vars };
+  return template.replace(PLACEHOLDER_RE, (_match, key: string, offset: number) => {
     if (!(key in merged)) {
       throw new Error(`Missing template variable: ${key}`);
     }
@@ -48,7 +72,7 @@ export function render(template, vars) {
     }
     const lineStart = template.lastIndexOf('\n', offset - 1) + 1;
     const leadingWhitespaceMatch = template.slice(lineStart, offset).match(/^(\s*)/);
-    const indent = leadingWhitespaceMatch ? leadingWhitespaceMatch[1] : '';
+    const indent = leadingWhitespaceMatch ? (leadingWhitespaceMatch[1] ?? '') : '';
     return value
       .split('\n')
       .map((line, i) => (i === 0 || line === '' ? line : indent + line))
@@ -56,12 +80,12 @@ export function render(template, vars) {
   });
 }
 
-export async function renderFile(path, vars) {
+export async function renderFile(path: string, vars: RenderVars): Promise<string> {
   const tmpl = await readFile(path, 'utf8');
   return render(tmpl, vars);
 }
 
-export function pickTemplate(languages) {
+export function pickTemplate(languages: string[]): string {
   if (languages.includes('typescript') || languages.includes('javascript')) {
     return 'workflow-ts.yml.tmpl';
   }
@@ -74,7 +98,9 @@ export function pickTemplate(languages) {
 // Map a pickTemplate() filename to the language key that `reviewPrompt`
 // accepts. Keeps the mapping in one place so callers don't repeat the
 // switch when computing the REVIEW_PROMPT token.
-export function templateLanguage(tmplName) {
+export type TemplateLanguage = 'ts' | 'py' | 'generic';
+
+export function templateLanguage(tmplName: string): TemplateLanguage {
   if (tmplName === 'workflow-ts.yml.tmpl') return 'ts';
   if (tmplName === 'workflow-py.yml.tmpl') return 'py';
   return 'generic';

package/src/core/review-schema-zod.ts

@@ -0,0 +1,262 @@
+// Zod-typed review schema for the AI-Gateway-shape consumer (clud-bug-app).
+//
+// The CLI runtime in `./review-schema.ts` ships a plain JSON-Schema object
+// because that's what the Agent SDK validator expects on the
+// `--json-schema '<JSON>'` argument. The App's runtime instead funnels the
+// model output through the Vercel AI SDK, which derives a JSON Schema from
+// a Zod schema. Both consumers need to agree on the WIRE shape — separate
+// `critical_findings[] / minor_findings[] / preexisting_findings[]` arrays
+// per SPEC §1.8.1 — but each builds its validator from a different source.
+//
+// This module ports the App's Zod schemas + flat-shape helpers into core
+// so a future drift between the App's Zod and the CLI's JSON-Schema lives
+// in one repo. The equivalence test (test/review-schema-zod.test.js)
+// asserts the two schemas describe the same wire shape (required fields,
+// finding-item shape) for every release.
+//
+// Ported from clud-bug-app/lib/review-schema.ts (commit shipped 2026-06-08).
+// The pure helpers (`flattenFindings`, `unflattenFindings`,
+// `deriveSummaryCounts`, `deriveSkillsReferenced`, `buildReviewFromFindings`)
+// are byte-equivalent to the App's helpers — see test for the equivalence
+// fixtures.
+
+import { z } from 'zod';
+
+// Severity buckets per SPEC §1.8.1. Only used by the internal `Finding`
+// type — the wire `findingItemSchema` does NOT carry severity.
+export const severityValues = ['critical', 'minor', 'preexisting'] as const;
+export const severitySchema = z.enum(severityValues);
+export type Severity = z.infer<typeof severitySchema>;
+
+// Status header at the top of the review file.
+export const statusHeaderValues = [
+  'critical findings',
+  'clean',
+  'bare',
+] as const;
+export const statusHeaderSchema = z.enum(statusHeaderValues);
+export type StatusHeader = z.infer<typeof statusHeaderSchema>;
+
+export const summaryCountsSchema = z.object({
+  critical: z.number().int().min(0),
+  minor: z.number().int().min(0),
+  preexisting: z.number().int().min(0),
+  resolved_from_prior: z.number().int().min(0),
+  still_open: z.number().int().min(0),
+});
+export type SummaryCounts = z.infer<typeof summaryCountsSchema>;
+
+/**
+ * Wire-shape finding item — NO severity field (mirrors the CLI's
+ * `FINDING_ITEM` JSON Schema in `./review-schema.ts`). Severity is implicit
+ * in which array the item lives in (`critical_findings`/`minor_findings`/
+ * `preexisting_findings`).
+ */
+export const findingItemSchema = z.object({
+  skill: z.string().min(1),
+  file: z.string().optional(),
+  line: z.number().int().min(1).optional(),
+  summary: z.string().min(1),
+  reasoning: z.string().optional(),
+});
+export type FindingItem = z.infer<typeof findingItemSchema>;
+
+/** Per-skill scan report — one entry per loaded skill (even silent ones). */
+export const perSkillScanItemSchema = z.object({
+  skill: z.string(),
+  outcome: z.string(),
+});
+export type PerSkillScanItem = z.infer<typeof perSkillScanItemSchema>;
+
+/** Dedicated-section block for `review_mode: dedicated` skills. */
+export const dedicatedSectionSchema = z.object({
+  section_name: z.string(),
+  skill: z.string(),
+  findings: z.array(findingItemSchema),
+});
+export type DedicatedSection = z.infer<typeof dedicatedSectionSchema>;
+
+/**
+ * Full review payload — wire shape. The model produces this; the App
+ * orchestrator immediately flattens to the internal `Finding[]` shape via
+ * `flattenFindings()` for multi-pass + aggregator work, then unflattens
+ * back via `unflattenFindings()` before writeback.
+ */
+export const reviewSchema = z.object({
+  status_header: statusHeaderSchema,
+  summary_counts: summaryCountsSchema,
+  per_skill_scan: z.array(perSkillScanItemSchema),
+  critical_findings: z.array(findingItemSchema),
+  minor_findings: z.array(findingItemSchema),
+  preexisting_findings: z.array(findingItemSchema),
+  dedicated_sections: z.array(dedicatedSectionSchema).optional(),
+  diagnostics: z.array(z.string()).optional(),
+  skills_referenced: z.array(z.string()),
+  last_reviewed_sha: z.string(),
+});
+export type Review = z.infer<typeof reviewSchema>;
+
+/**
+ * Internal flat-finding type used by App orchestrator, multi-pass
+ * aggregator, skill-usage telemetry, etc. Created from a wire-shape
+ * `Review` via `flattenFindings()`. Has explicit `severity` field so
+ * internal code doesn't need to track which array a finding came from.
+ *
+ * Exported from the core barrel as `ZodFinding` to disambiguate from
+ * the CLI-shape `ReviewFinding` (which never carries severity — its
+ * severity comes from the array it lives in).
+ */
+export type Finding = FindingItem & { severity: Severity };
+
+/**
+ * Zod schema describing the internal Finding shape (for tests + cross-check
+ * Pass 2 independentFindings). The wire equivalent is `findingItemSchema`
+ * which does NOT have severity.
+ */
+export const findingSchema = findingItemSchema.extend({
+  severity: severitySchema,
+});
+
+/**
+ * Flatten wire-shape `Review.critical_findings / minor_findings /
+ * preexisting_findings` into a single `Finding[]` with severity tagged.
+ * Preserves ordering: criticals first, then minors, then preexistings.
+ */
+export function flattenFindings(review: Review): Finding[] {
+  const out: Finding[] = [];
+  for (const f of review.critical_findings) out.push({ ...f, severity: 'critical' });
+  for (const f of review.minor_findings) out.push({ ...f, severity: 'minor' });
+  for (const f of review.preexisting_findings) out.push({ ...f, severity: 'preexisting' });
+  return out;
+}
+
+/**
+ * Inverse of `flattenFindings`: split a flat `Finding[]` back into the
+ * three wire-shape arrays. Used at writeback time after multi-pass
+ * aggregation has produced the final flat list.
+ */
+export function unflattenFindings(findings: Finding[]): {
+  critical_findings: FindingItem[];
+  minor_findings: FindingItem[];
+  preexisting_findings: FindingItem[];
+} {
+  const stripSeverity = (f: Finding): FindingItem => {
+    const { severity: _s, ...rest } = f;
+    return rest;
+  };
+  return {
+    critical_findings: findings.filter((f) => f.severity === 'critical').map(stripSeverity),
+    minor_findings: findings.filter((f) => f.severity === 'minor').map(stripSeverity),
+    preexisting_findings: findings.filter((f) => f.severity === 'preexisting').map(stripSeverity),
+  };
+}
+
+/**
+ * Derive `summary_counts` from a flat `Finding[]` list. Canonical
+ * source-of-truth used by the orchestrator after flattening, to
+ * overwrite the model's potentially-drifted counts.
+ */
+export function deriveSummaryCounts(findings: Finding[]): SummaryCounts {
+  return {
+    critical: findings.filter((f) => f.severity === 'critical').length,
+    minor: findings.filter((f) => f.severity === 'minor').length,
+    preexisting: findings.filter((f) => f.severity === 'preexisting').length,
+    resolved_from_prior: 0,
+    still_open: 0,
+  };
+}
+
+/**
+ * Derive `skills_referenced` from a flat `Finding[]` list, preserving
+ * citation order (first appearance wins) and deduplicating.
+ */
+export function deriveSkillsReferenced(findings: Finding[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const f of findings) {
+    if (seen.has(f.skill)) continue;
+    seen.add(f.skill);
+    out.push(f.skill);
+  }
+  return out;
+}
+
+/**
+ * Test helper: build a wire-shape `Review` from a flat `Finding[]` list.
+ * Tests historically built reviews with a flat `findings: [...]` field; the
+ * wire shape (separate severity arrays + per_skill_scan + last_reviewed_sha
+ * required) is more verbose. This helper keeps fixtures short — pass a
+ * flat list, get back a valid wire-shape Review with derived counts and
+ * skills.
+ *
+ * Production code should NOT use this; it constructs reviews from AI output
+ * directly. This is purely for test ergonomics.
+ */
+export function buildReviewFromFindings(opts: {
+  findings: Finding[];
+  status_header?: StatusHeader;
+  last_reviewed_sha?: string;
+  per_skill_scan?: PerSkillScanItem[];
+  dedicated_sections?: DedicatedSection[];
+  diagnostics?: string[];
+}): Review {
+  const split = unflattenFindings(opts.findings);
+  // Default status_header is derived from severity, NOT just emptiness.
+  // The App's original buildReviewFromFindings defaulted to
+  // 'critical findings' for ANY non-empty list, including minor-only and
+  // preexisting-only inputs. That was a bug (caught by clud-bug-review
+  // on PR #158): a review with only minor findings should be 'clean', not
+  // 'critical findings'. Fixed here on port to core.
+  //
+  // Callers that need the old behavior can pass `status_header` explicitly.
+  // Callers that want SPEC §1.8.1 semantics (the default) get the correct
+  // bucket: criticals present → 'critical findings'; else → 'clean'.
+  const hasCritical = opts.findings.some((f) => f.severity === 'critical');
+  const defaultStatus = hasCritical ? 'critical findings' : 'clean';
+  return {
+    status_header: opts.status_header ?? defaultStatus,
+    summary_counts: deriveSummaryCounts(opts.findings),
+    skills_referenced: deriveSkillsReferenced(opts.findings),
+    per_skill_scan: opts.per_skill_scan ?? [],
+    critical_findings: split.critical_findings,
+    minor_findings: split.minor_findings,
+    preexisting_findings: split.preexisting_findings,
+    ...(opts.dedicated_sections !== undefined
+      ? { dedicated_sections: opts.dedicated_sections }
+      : {}),
+    ...(opts.diagnostics !== undefined ? { diagnostics: opts.diagnostics } : {}),
+    last_reviewed_sha: opts.last_reviewed_sha ?? '',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// D.2.5 — cross-check pass schema
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-finding verdict from a cross-check pass. The pass2 model echoes
+ * back Pass 1's findings by 0-indexed `pass1Index` + `agreed`/`disagreed`
+ * + rationale. The aggregator stitches these into
+ * `MultiPassReview.findings[].attributions`.
+ *
+ * Cross-check Pass 2 operates on a flat finding list (its own
+ * representation), so its independentFindings carry severity — uses the
+ * legacy `findingSchema` shape.
+ */
+export const crossCheckVerdictSchema = z.object({
+  pass1Index: z.number().int().min(0),
+  verdict: z.enum(['agreed', 'disagreed']),
+  rationale: z.string().optional(),
+});
+export type CrossCheckVerdictSchema = z.infer<typeof crossCheckVerdictSchema>;
+
+/**
+ * Full cross-check response. Pass 2 outputs verdicts on Pass-1 findings
+ * plus its own independent finds (in the internal `findingSchema` shape
+ * with severity, since cross-check works on already-flattened lists).
+ */
+export const crossCheckSchema = z.object({
+  verdicts: z.array(crossCheckVerdictSchema),
+  independentFindings: z.array(findingSchema),
+});
+export type CrossCheck = z.infer<typeof crossCheckSchema>;

package/{lib/review-schema.js → src/core/review-schema.ts}

@@ -23,10 +23,21 @@
 //     keep the model from inventing fields.
 //
 // Bumped via deliberate edit; not derived from a TypeScript type. The
-// rendering side (lib/render-review.js) treats unknown fields permissively
+// rendering side (./render-review.ts) treats unknown fields permissively
 // — schema and renderer can drift up to one minor version safely.
 
-const FINDING_ITEM = {
+// The JSON Schema shape is structurally rich (oneOf, enum, conditional
+// required fields) and is consumed as a raw JSON object by Agent SDK
+// validators that have their own runtime semantics. Typing it as
+// `Record<string, unknown>` would erase the literal-property structure
+// callers rely on for IDE navigation; typing each sub-object exactly
+// would tightly couple every test that asserts a specific path. We use
+// a structural alias `JSONSchemaObject` here so the export keeps its
+// rich literal type (caller-visible field names) without forcing a
+// schema-spec round-trip.
+type JSONSchemaObject = Record<string, unknown>;
+
+const FINDING_ITEM: JSONSchemaObject = {
   type: 'object',
   additionalProperties: false,
   properties: {
@@ -55,7 +66,7 @@ const FINDING_ITEM = {
   required: ['skill', 'summary'],
 };
 
-const PER_SKILL_SCAN_ITEM = {
+const PER_SKILL_SCAN_ITEM: JSONSchemaObject = {
   type: 'object',
   additionalProperties: false,
   properties: {
@@ -68,7 +79,7 @@ const PER_SKILL_SCAN_ITEM = {
   required: ['skill', 'outcome'],
 };
 
-export const REVIEW_SCHEMA = {
+export const REVIEW_SCHEMA: JSONSchemaObject = {
   type: 'object',
   additionalProperties: false,
   properties: {
@@ -154,6 +165,58 @@ export const REVIEW_SCHEMA = {
 // `--json-schema '<JSON>'` argument. Single-line (the workflow YAML uses
 // the pipe block; single-quoted JSON inside that needs to stay flat to
 // avoid YAML parser surprises with embedded newlines).
-export function serializedReviewSchema() {
+export function serializedReviewSchema(): string {
   return JSON.stringify(REVIEW_SCHEMA);
 }
+
+// --- Schema-derived runtime types for renderReview() input ---
+//
+// The TypeScript types below mirror the JSON Schema shape above so that
+// render-review.ts can consume the parsed JSON with structural typing.
+// They are intentionally permissive (every field optional except where
+// the schema's `required` list forces it) because the renderer is the
+// last line of defense — malformed JSON should degrade rather than throw.
+
+export type FindingSeverity = 'critical' | 'minor' | 'preexisting';
+
+export interface ReviewFinding {
+  skill: string;
+  summary: string;
+  file?: string;
+  line?: number;
+  reasoning?: string;
+}
+
+export interface PerSkillScanItem {
+  skill: string;
+  outcome: string;
+}
+
+export interface DedicatedSection {
+  section_name: string;
+  skill: string;
+  findings: ReviewFinding[];
+}
+
+export interface ReviewSummaryCounts {
+  critical: number;
+  minor: number;
+  preexisting: number;
+  resolved_from_prior: number;
+  still_open: number;
+}
+
+export type ReviewStatusHeader = 'critical findings' | 'clean' | 'bare';
+
+export interface ReviewData {
+  status_header: ReviewStatusHeader | string;
+  summary_counts: ReviewSummaryCounts;
+  per_skill_scan: PerSkillScanItem[];
+  critical_findings: ReviewFinding[];
+  minor_findings: ReviewFinding[];
+  preexisting_findings: ReviewFinding[];
+  skills_referenced: string[];
+  last_reviewed_sha: string;
+  dedicated_sections?: DedicatedSection[];
+  diagnostics?: string[];
+}