@jaimevalasek/aioson 1.36.0 → 1.37.1

package/src/lib/briefing-refiner/feedback-schema.js

@@ -7,6 +7,12 @@ const VALID_SECTION_STATUSES = new Set(['unchanged', 'accepted', 'change_request
 const VALID_DECISION_STATUSES = new Set(['accepted', 'change_requested', 'remove', 'blocked', 'note']);
 const VALID_SEVERITIES = new Set(['note', 'suggestion', 'important', 'blocking']);
 const VALID_EXPORT_METHODS = new Set(['file-system-access', 'download', 'copy-paste', 'manual-save']);
+const VALID_FINDING_CATEGORIES = new Set(['ambiguity', 'redundancy', 'gap', 'risk', 'pending-decision', 'scope-suggestion']);
+const VALID_FINDING_SEVERITIES = new Set(['low', 'medium', 'high']);
+const VALID_FINDING_STATUSES = new Set(['pending', 'accepted', 'rejected', 'deferred']);
+// 1.0 = sections/comments/decisions/blocking_items only; 1.1 adds findings[] (the
+// agent's audit surfaced as reviewable items) and the refinement round counter.
+const SUPPORTED_SCHEMA_VERSIONS = new Set(['1.0', '1.1']);
 
 // Normalization only — NOT a security boundary. This strips well-formed tags
 // and normalizes newlines so the text round-trips cleanly into briefings.md.
@@ -34,17 +40,64 @@ function normalizeSection(section) {
   };
 }
 
-function buildInitialFeedback({ slug, sourcePath, sourceHash, sections, exportMethod = 'manual-save', now = new Date() }) {
+function normalizeFinding(finding, index) {
+  return {
+    id: String(finding.id || `F${index + 1}`),
+    section_id: String(finding.section_id || ''),
+    category: VALID_FINDING_CATEGORIES.has(finding.category) ? finding.category : 'gap',
+    severity: VALID_FINDING_SEVERITIES.has(finding.severity) ? finding.severity : 'medium',
+    blocking: Boolean(finding.blocking),
+    text: sanitizeText(finding.text),
+    recommendation: sanitizeText(finding.recommendation || ''),
+    status: VALID_FINDING_STATUSES.has(finding.status) ? finding.status : 'pending',
+    note: sanitizeText(finding.note || '')
+  };
+}
+
+/**
+ * Validate agent-supplied audit findings BEFORE they are baked into the review
+ * surface. Strict where normalizeFinding is lenient: the agent must name a real
+ * section and a valid category, and every finding must carry text.
+ */
+function validateFindingsInput(findings, { sectionIds = [] } = {}) {
+  const errors = [];
+  if (!Array.isArray(findings)) {
+    return { ok: false, errors: ['findings must be an array'] };
+  }
+  const known = new Set(sectionIds);
+  findings.forEach((finding, index) => {
+    const label = finding && finding.id ? String(finding.id) : `#${index + 1}`;
+    if (!finding || typeof finding !== 'object') {
+      errors.push(`finding ${label} must be an object`);
+      return;
+    }
+    if (!String(finding.text || '').trim()) errors.push(`finding ${label} has no text`);
+    if (!VALID_FINDING_CATEGORIES.has(finding.category)) {
+      errors.push(`finding ${label} has invalid category: ${finding.category}`);
+    }
+    if (finding.severity !== undefined && !VALID_FINDING_SEVERITIES.has(finding.severity)) {
+      errors.push(`finding ${label} has invalid severity: ${finding.severity}`);
+    }
+    if (known.size > 0 && !known.has(String(finding.section_id || ''))) {
+      errors.push(`finding ${label} points at unknown section_id: ${finding.section_id}`);
+    }
+  });
+  return { ok: errors.length === 0, errors };
+}
+
+function buildInitialFeedback({ slug, sourcePath, sourceHash, sections, findings = [], round = 1, exportMethod = 'manual-save', now = new Date() }) {
   const timestamp = now.toISOString();
   return {
-    schema_version: '1.0',
+    schema_version: '1.1',
     briefing_slug: slug,
     source_briefing_path: sourcePath,
     source_hash: sourceHash,
     review_generated_at: timestamp,
     last_modified_at: timestamp,
     export_method: exportMethod,
+    round: Number.isInteger(round) && round > 0 ? round : 1,
     sections: sections.map(normalizeSection),
+    findings: findings.map(normalizeFinding),
     comments: [],
     decisions: [],
     blocking_items: []
@@ -66,7 +119,7 @@ function validateFeedback(feedback, { slug, currentSourceHash, allowStale = fals
   if (!feedback || typeof feedback !== 'object') errors.push('feedback must be an object');
   if (errors.length > 0) return { ok: false, stale: false, errors, warnings };
 
-  if (feedback.schema_version !== '1.0') errors.push('schema_version must be 1.0');
+  if (!SUPPORTED_SCHEMA_VERSIONS.has(feedback.schema_version)) errors.push('schema_version must be 1.0 or 1.1');
   if (slug && feedback.briefing_slug !== slug) errors.push('briefing_slug does not match selected slug');
   if (!isPathInsideBriefing(feedback.source_briefing_path, feedback.briefing_slug || slug)) {
     errors.push('source_briefing_path must stay inside the selected briefing directory');
@@ -99,6 +152,17 @@ function validateFeedback(feedback, { slug, currentSourceHash, allowStale = fals
     }
   }
 
+  // findings[] is a 1.1 field; a 1.0 payload legitimately has none.
+  if (feedback.schema_version === '1.1' && !Array.isArray(feedback.findings)) {
+    errors.push('findings must be an array');
+  }
+  if (Array.isArray(feedback.findings)) {
+    for (const finding of feedback.findings) {
+      if (!VALID_FINDING_STATUSES.has(finding.status)) errors.push(`invalid finding status: ${finding.status}`);
+      if (!VALID_FINDING_CATEGORIES.has(finding.category)) errors.push(`invalid finding category: ${finding.category}`);
+    }
+  }
+
   const stale = Boolean(currentSourceHash && feedback.source_hash !== currentSourceHash);
   if (stale) warnings.push('source_hash differs from current briefings.md');
   if (stale && !allowStale) errors.push('feedback is stale');
@@ -116,7 +180,12 @@ function assertFeedbackPath(projectDir, slug, candidatePath) {
 
 module.exports = {
   buildInitialFeedback,
+  normalizeFinding,
   sanitizeText,
   validateFeedback,
-  assertFeedbackPath
+  validateFindingsInput,
+  assertFeedbackPath,
+  VALID_FINDING_CATEGORIES,
+  VALID_FINDING_SEVERITIES,
+  VALID_FINDING_STATUSES
 };

package/src/lib/briefing-refiner/refinement-report.js

@@ -7,6 +7,15 @@ function list(items, formatter) {
 
 function buildRefinementReport(data) {
   const nextAction = data.next_action || 'rerun_review';
+  const findings = Array.isArray(data.findings) ? data.findings : [];
+  const findingsBlock = findings.length > 0
+    ? [
+        '## Findings',
+        '',
+        list(findings, (finding) => `${finding.id} [${finding.category}/${finding.severity}${finding.blocking ? '/blocking' : ''}] (${finding.status}) ${finding.section_id}: ${finding.text}`),
+        ''
+      ]
+    : [];
   return [
     `# Refinement Report — ${data.briefing_slug}`,
     '',
@@ -15,8 +24,10 @@ function buildRefinementReport(data) {
     `- Source hash: ${data.source_hash || '-'}`,
     `- Applied hash: ${data.applied_hash || '-'}`,
     `- Status: ${data.status || 'review_generated'}`,
+    `- Round: ${data.round || 1}`,
     `- Next action: ${nextAction}`,
     '',
+    ...findingsBlock,
     '## Applied Changes',
     '',
     list(data.applied_changes, (change) => `${change.section_id || change.title}: ${change.summary || 'updated'}`),