/** * Content-aware gates for harness_artifact_ready (existence + minimal validity). */ import { constants } from "node:fs"; import { access, readFile, stat } from "node:fs/promises"; import { join } from "node:path"; import { parse as parseYaml } from "yaml"; import { validateAgainstHarnessSchema } from "./harness-schema-validate.js"; import { validateTaskClarificationHumanGate } from "./plan-human-gates.js"; import { TASK_CLARIFICATION_ARTIFACT, validateTaskClarificationDoc, } from "./plan-task-clarification.js"; export interface ArtifactGateContext { entries?: unknown[]; quick?: boolean; taskSummary?: string; lastOutcome?: string | null; } export interface ArtifactGateResult { ok: boolean; errors: string[]; } const ARTIFACT_SCHEMA: Record = { "artifacts/decomposition.yaml": "plan-decomposition-brief.schema.json", "artifacts/hypothesis.yaml": "plan-hypothesis-brief.schema.json", "artifacts/implementation-research.yaml": "plan-implementation-research-brief.schema.json", "artifacts/stack.yaml": "plan-stack-brief.schema.json", "artifacts/task-clarification.yaml": "plan-task-clarification.schema.json", "artifacts/planning-context.yaml": "plan-planning-context.schema.json", "artifacts/execution-plan-draft.yaml": "plan-execution-plan-brief.schema.json", "artifacts/eval-verdict.yaml": "eval-verdict.schema.json", "artifacts/adversary-report.yaml": "adversary-report.schema.json", "artifacts/sentrux-repair-plan.yaml": "sentrux-repair-plan.schema.json", "artifacts/review-round-consolidated.yaml": "plan-review-round-draft.schema.json", }; /** Round-indexed debate artifacts (submit_* output). */ const ROUND_ARTIFACT_SCHEMA: Array<{ pattern: RegExp; schemaFile: string }> = [ { pattern: /^artifacts\/hypothesis-validation-r\d+\.yaml$/, schemaFile: "plan-hypothesis-eval.schema.json", }, { pattern: /^artifacts\/validation-turn-r\d+\.yaml$/, schemaFile: "plan-validation-turn.schema.json", }, { pattern: /^artifacts\/adversary-brief-r\d+\.yaml$/, schemaFile: "plan-adversary-brief.schema.json", }, { pattern: /^artifacts\/sprint-audit-r\d+\.yaml$/, schemaFile: "plan-sprint-audit-turn.schema.json", }, { pattern: /^artifacts\/review-round-r\d+\.yaml$/, schemaFile: "plan-review-round-draft.schema.json", }, ]; export function resolveArtifactSchemaFile( normalizedPath: string, ): string | undefined { const exact = ARTIFACT_SCHEMA[normalizedPath]; if (exact) return exact; for (const entry of ROUND_ARTIFACT_SCHEMA) { if (entry.pattern.test(normalizedPath)) return entry.schemaFile; } return undefined; } const PREREQUISITE_ORDER: Record = { "artifacts/planning-context.yaml": [TASK_CLARIFICATION_ARTIFACT], "artifacts/hypothesis.yaml": ["artifacts/decomposition.yaml"], "artifacts/implementation-research.yaml": [ "artifacts/decomposition.yaml", "artifacts/hypothesis.yaml", ], "artifacts/stack.yaml": [ "artifacts/decomposition.yaml", "artifacts/hypothesis.yaml", ], "artifacts/execution-plan-draft.yaml": [ "artifacts/decomposition.yaml", "artifacts/hypothesis.yaml", "artifacts/implementation-research.yaml", "artifacts/stack.yaml", ], }; async function fileExists(path: string): Promise { try { await access(path, constants.R_OK); return true; } catch { return false; } } function artifactStatusBad(doc: Record): string | null { const status = String(doc.status ?? "ok").toLowerCase(); if (status === "partial" || status === "failed" || status === "error") { return `artifact status is "${status}"`; } return null; } async function validatePlanningContextArtifact( normalized: string, doc: Record, ): Promise { const errors: string[] = []; if (normalized !== "artifacts/planning-context.yaml") return errors; const statusErr = artifactStatusBad(doc); if (statusErr) errors.push(`${normalized}: ${statusErr}`); const coverage = doc.coverage as Record | undefined; if (!coverage || typeof coverage !== "object") return errors; for (const lane of ["architecture", "structure"] as const) { const laneDoc = coverage[lane] as Record | undefined; const laneStatus = String(laneDoc?.status ?? "").toLowerCase(); if (laneStatus !== "ok" && laneStatus !== "partial") { errors.push( `${normalized}: coverage.${lane}.status must be ok or partial (got "${laneStatus || "missing"}")`, ); } } return errors; } async function validateArtifactPrerequisites( runRoot: string, normalized: string, prereqs: string[], ): Promise { const errors: string[] = []; for (const prereq of prereqs) { const prereqPath = join(runRoot, prereq); if (!(await fileExists(prereqPath))) { errors.push(`${normalized}: prerequisite missing (${prereq})`); continue; } if (prereq !== TASK_CLARIFICATION_ARTIFACT) continue; try { const raw = await readFile(prereqPath, "utf-8"); const prereqDoc = parseYaml(raw) as Record; const clar = validateTaskClarificationDoc(prereqDoc, { requireReady: true, }); if (!clar.ok) { errors.push( ...clar.errors.map( (e) => `${normalized}: prerequisite ${prereq} — ${e}`, ), ); } } catch { errors.push( `${normalized}: prerequisite ${prereq} invalid or unreadable`, ); } } return errors; } export async function validateHarnessArtifactFile( runRoot: string, relPath: string, specsDir: string, gateCtx?: ArtifactGateContext & { skipPrerequisites?: boolean }, ): Promise { const normalized = relPath.replace(/\\/g, "/"); const abs = join(runRoot, normalized); const errors: string[] = []; if (!(await fileExists(abs))) { return { ok: false, errors: [`missing file: ${normalized}`] }; } const st = await stat(abs); if (st.size < 8) { errors.push(`${normalized}: file too small (${st.size} bytes)`); } let doc: Record | null = null; try { const raw = await readFile(abs, "utf-8"); if (!raw.trim()) { errors.push(`${normalized}: empty file`); } else { doc = parseYaml(raw) as Record; if (!doc || typeof doc !== "object" || Array.isArray(doc)) { errors.push(`${normalized}: root must be a YAML object`); } } } catch (e) { errors.push( `${normalized}: invalid YAML (${e instanceof Error ? e.message : String(e)})`, ); } const schemaFile = resolveArtifactSchemaFile(normalized); if (doc && schemaFile) { const validation = await validateAgainstHarnessSchema( specsDir, schemaFile, doc, ); if (!validation.ok) { errors.push( `${normalized}: schema validation failed — ${validation.errors.join("; ")}`, ); } } if (doc && normalized === TASK_CLARIFICATION_ARTIFACT) { const clar = validateTaskClarificationDoc(doc, { requireReady: true }); if (!clar.ok) { errors.push(...clar.errors.map((e) => `${normalized}: ${e}`)); } const human = validateTaskClarificationHumanGate( gateCtx?.entries ?? [], doc, { quick: gateCtx?.quick, taskSummary: gateCtx?.taskSummary, allowFollowUpMessage: gateCtx?.lastOutcome === "needs_clarification", }, ); if (!human.ok) { errors.push(...human.errors.map((e) => `${normalized}: ${e}`)); } } if (doc) { errors.push(...(await validatePlanningContextArtifact(normalized, doc))); } if (!gateCtx?.skipPrerequisites) { const prereqs = PREREQUISITE_ORDER[normalized] ?? []; errors.push( ...(await validateArtifactPrerequisites(runRoot, normalized, prereqs)), ); } return { ok: errors.length === 0, errors }; } export async function validateHarnessArtifactPaths( runRoot: string, paths: string[], specsDir: string, gateCtx?: ArtifactGateContext, ): Promise<{ ok: boolean; present: string[]; missing: string[]; errors: string[]; }> { const present: string[] = []; const missing: string[] = []; const errors: string[] = []; for (const rel of paths) { const normalized = rel.replace(/\\/g, "/"); const gate = await validateHarnessArtifactFile( runRoot, normalized, specsDir, gateCtx, ); if (gate.errors.some((e) => e.startsWith("missing file"))) { missing.push(normalized); continue; } if (!gate.ok) { errors.push(...gate.errors); continue; } present.push(normalized); } return { ok: missing.length === 0 && errors.length === 0, present, missing, errors, }; }