@innofeight/global-workflow 0.0.1 → 0.0.2

package/scripts/lib/acceptance-mirror.mjs

@@ -0,0 +1,398 @@
+import { createHash } from 'node:crypto'
+
+export const MIRROR_EVIDENCE_VERSION = 1
+export const ACCEPTANCE_KINDS = ['TASK_AC', 'HUMAN_QA_AC']
+export const EVIDENCE_STRENGTHS = ['CONNECTOR-OBSERVED', 'HUMAN-ATTESTED']
+
+const contracts = {
+  TASK_AC: {
+    heading: 'Task Acceptance Criteria',
+    idPattern: /^TAC-\d{2}\b/u,
+    acceptedLabels: ['Task Acceptance Criteria', 'AC']
+  },
+  HUMAN_QA_AC: {
+    heading: 'Human QA Acceptance Criteria',
+    applicabilityHeading: 'Human QA Applicability',
+    idPattern: /^HQA-\d{2}\b/u,
+    acceptedLabels: ['Human QA Acceptance Criteria']
+  }
+}
+
+function contract(kind) {
+  const selected = contracts[kind]
+  if (!selected) throw new Error(`UNSUPPORTED ACCEPTANCE KIND: ${kind}`)
+  return selected
+}
+
+function normalizeLines(markdown) {
+  return String(markdown)
+    .replace(/\r\n?/gu, '\n')
+    .split('\n')
+    .map((line) => line.replace(/[ \t]+$/gu, ''))
+}
+
+function sectionLines(markdown, heading) {
+  const lines = normalizeLines(markdown)
+  const matchingHeadings = lines.flatMap((line, index) => {
+    const match = line.match(/^(#{1,6})\s+(.+?)\s*$/u)
+    return match && match[2] === heading
+      ? [{ index, level: match[1].length }]
+      : []
+  })
+  const headings = matchingHeadings.filter(({ level }) => level === 2)
+  if (headings.length !== 1)
+    return {
+      diagnostics: [
+        headings.length === 0 && matchingHeadings.length > 0
+          ? `WRONG-LEVEL CANONICAL HEADING: ${heading}`
+          : headings.length === 0
+            ? `MISSING CANONICAL HEADING: ${heading}`
+            : `AMBIGUOUS CANONICAL HEADING: ${heading}`
+      ],
+      lines: []
+    }
+
+  const [{ index }] = headings
+  let end = lines.length
+  for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+    const match = lines[cursor].match(/^(#{1,6})\s+/u)
+    if (match && match[1].length <= 2) {
+      end = cursor
+      break
+    }
+  }
+  return { diagnostics: [], lines: lines.slice(index + 1, end) }
+}
+
+function paragraphs(lines) {
+  return lines
+    .join('\n')
+    .split(/\n[ \t]*\n/gu)
+    .map((paragraph) => paragraph.replace(/^\n+|\n+$/gu, ''))
+    .filter(Boolean)
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value, 'utf8').digest('hex')
+}
+
+export function canonicalAcceptance(markdown, kind) {
+  const selected = contract(kind)
+  if (kind === 'HUMAN_QA_AC') {
+    const applicability = sectionLines(markdown, selected.applicabilityHeading)
+    if (applicability.diagnostics.length > 0)
+      return {
+        kind,
+        applicability: 'REQUIRED',
+        criteria: [],
+        ids: [],
+        normalized: '',
+        fingerprint: null,
+        diagnostics: applicability.diagnostics,
+        valid: false
+      }
+    if (applicability.diagnostics.length === 0) {
+      const applicabilityParagraphs = paragraphs(applicability.lines)
+      const none = applicabilityParagraphs.some((paragraph) =>
+        /^(none|not applicable)\b/iu.test(paragraph)
+      )
+      const required = applicabilityParagraphs.some((paragraph) =>
+        /^required\b/iu.test(paragraph)
+      )
+      if (none && required)
+        return {
+          kind,
+          applicability: 'REQUIRED',
+          criteria: [],
+          ids: [],
+          normalized: '',
+          fingerprint: null,
+          diagnostics: ['CONFLICTING HUMAN QA APPLICABILITY'],
+          valid: false
+        }
+      if (none) {
+        const criteriaSection = sectionLines(markdown, selected.heading)
+        if (criteriaSection.diagnostics.length === 0)
+          return {
+            kind,
+            applicability: 'REQUIRED',
+            criteria: [],
+            ids: [],
+            normalized: '',
+            fingerprint: null,
+            diagnostics: ['CONFLICTING HUMAN QA APPLICABILITY'],
+            valid: false
+          }
+        return {
+          kind,
+          applicability: 'NONE',
+          criteria: [],
+          ids: [],
+          normalized: '',
+          fingerprint: null,
+          diagnostics: [],
+          valid: true
+        }
+      }
+      if (required) {
+        // Continue into the canonical HQA criteria section below.
+      } else
+        return {
+          kind,
+          applicability: 'REQUIRED',
+          criteria: [],
+          ids: [],
+          normalized: '',
+          fingerprint: null,
+          diagnostics: ['INVALID HUMAN QA APPLICABILITY'],
+          valid: false
+        }
+    }
+  }
+  const section = sectionLines(markdown, selected.heading)
+  if (section.diagnostics.length > 0)
+    return {
+      kind,
+      applicability: 'REQUIRED',
+      criteria: [],
+      ids: [],
+      normalized: '',
+      fingerprint: null,
+      diagnostics: section.diagnostics,
+      valid: false
+    }
+  const sectionParagraphs = paragraphs(section.lines)
+  const criteria = sectionParagraphs.filter((paragraph) =>
+    selected.idPattern.test(paragraph)
+  )
+  const ids = criteria.map(
+    (criterion) => criterion.match(selected.idPattern)?.[0]
+  )
+  const diagnostics = [...section.diagnostics]
+
+  if (criteria.length === 0) diagnostics.push(`NO CANONICAL ${kind} CRITERIA`)
+  if (criteria.some((criterion) => criterion.includes('[truncated]')))
+    diagnostics.push(`TRUNCATED ${kind} CONTRACT`)
+  if (new Set(ids).size !== ids.length)
+    diagnostics.push(`DUPLICATE ${kind} IDS`)
+  if (
+    sectionParagraphs.some((paragraph) => {
+      const prefix = kind === 'TASK_AC' ? 'TAC-' : 'HQA-'
+      return paragraph.startsWith(prefix) && !selected.idPattern.test(paragraph)
+    })
+  )
+    diagnostics.push(`MALFORMED ${kind} ID`)
+
+  const normalized = criteria.join('\n\n')
+  return {
+    kind,
+    applicability: 'REQUIRED',
+    criteria,
+    ids,
+    normalized,
+    fingerprint: normalized ? `sha256:${sha256(normalized)}` : null,
+    diagnostics,
+    valid: diagnostics.length === 0
+  }
+}
+
+function field(block, name) {
+  return block.match(new RegExp(`(?:^|\\n)${name}:\\s*(.+)$`, 'mu'))?.[1].trim()
+}
+
+export function parseMirrorEvidence(text) {
+  const normalized = String(text)
+    .replace(/\r\n?/gu, '\n')
+    .replaceAll(' | ', '\n')
+  const starts = [
+    ...normalized.matchAll(/NATIVE ACCEPTANCE MIRROR EVIDENCE v(\d+)/gu)
+  ]
+  return starts.map((match, index) => {
+    const block = normalized.slice(
+      match.index,
+      starts[index + 1]?.index ?? normalized.length
+    )
+    const ids = field(block, 'Acceptance IDs')
+      ?.split(',')
+      .map((id) => id.trim())
+    return {
+      version: Number(match[1]),
+      taskId: field(block, 'ClickUp task ID') ?? null,
+      taskTitle: field(block, 'Task title') ?? null,
+      kind: field(block, 'Acceptance kind'),
+      fingerprint: field(block, 'Canonical fingerprint'),
+      ids: ids ?? [],
+      label: field(block, 'Native checklist label'),
+      strength: field(block, 'Evidence strength'),
+      mirrorMatched: field(block, 'Mirror matched canonical criteria'),
+      initialUnchecked: field(block, 'Initial unchecked state confirmed'),
+      recordedAt: field(block, 'Recorded at') ?? null
+    }
+  })
+}
+
+function sameValues(left, right) {
+  return (
+    left.length === right.length &&
+    left.every((value, index) => value === right[index])
+  )
+}
+
+export function validateMirrorEvidence(
+  evidence,
+  canonical,
+  { taskId, taskTitle } = {}
+) {
+  const selected = contract(canonical.kind)
+  const diagnostics = []
+  if (evidence.version !== MIRROR_EVIDENCE_VERSION)
+    diagnostics.push('UNSUPPORTED EVIDENCE VERSION')
+  if (evidence.kind !== canonical.kind)
+    diagnostics.push('ACCEPTANCE KIND MISMATCH')
+  if (evidence.fingerprint !== canonical.fingerprint)
+    diagnostics.push('CANONICAL FINGERPRINT MISMATCH')
+  if (!sameValues(evidence.ids, canonical.ids))
+    diagnostics.push('ACCEPTANCE IDS MISMATCH')
+  if (!selected.acceptedLabels.includes(evidence.label))
+    diagnostics.push('CHECKLIST LABEL NOT ACCEPTED')
+  if (!EVIDENCE_STRENGTHS.includes(evidence.strength))
+    diagnostics.push('INVALID EVIDENCE STRENGTH')
+  if (evidence.mirrorMatched !== 'YES')
+    diagnostics.push('MIRROR MATCH NOT CONFIRMED')
+  if (evidence.initialUnchecked !== 'YES')
+    diagnostics.push('INITIAL UNCHECKED STATE NOT CONFIRMED')
+  if (taskId && evidence.taskId !== taskId)
+    diagnostics.push('CLICKUP TASK ID MISMATCH')
+  if (taskTitle && evidence.taskTitle !== taskTitle)
+    diagnostics.push('TASK TITLE MISMATCH')
+  return { valid: canonical.valid && diagnostics.length === 0, diagnostics }
+}
+
+function reusableEvidence(records, canonical, binding) {
+  return (
+    records.find(
+      (record) => validateMirrorEvidence(record, canonical, binding).valid
+    ) ?? null
+  )
+}
+
+export function evaluateAcceptanceMirrors({
+  markdown,
+  checklistsCount,
+  evidenceText = '',
+  taskId,
+  taskTitle
+}) {
+  const task = canonicalAcceptance(markdown, 'TASK_AC')
+  const humanQa = canonicalAcceptance(markdown, 'HUMAN_QA_AC')
+  const evidence = parseMirrorEvidence(evidenceText)
+  const canonicalDiagnostics = [...task.diagnostics, ...humanQa.diagnostics]
+  if (canonicalDiagnostics.length > 0)
+    return {
+      pass: false,
+      blocked: true,
+      closeAgentSegment: true,
+      diagnostics: canonicalDiagnostics,
+      task,
+      humanQa,
+      reusable: [],
+      repair: [],
+      repairPrompt: null
+    }
+
+  const required = humanQa.applicability === 'REQUIRED' ? [humanQa] : []
+  const reusable = required.flatMap((canonical) => {
+    const matching = reusableEvidence(evidence, canonical, {
+      taskId,
+      taskTitle
+    })
+    return matching ? [{ kind: canonical.kind, evidence: matching }] : []
+  })
+  const repair = required
+    .filter(
+      (canonical) => !reusable.some(({ kind }) => kind === canonical.kind)
+    )
+    .map(({ kind }) => kind)
+  if (Number(checklistsCount) < required.length && repair.length === 0)
+    for (const { kind } of required)
+      if (!repair.includes(kind)) repair.push(kind)
+
+  return {
+    pass: repair.length === 0,
+    blocked: false,
+    closeAgentSegment: repair.length > 0,
+    diagnostics: [],
+    task,
+    humanQa,
+    reusable,
+    repair,
+    repairPrompt: repair.includes('HUMAN_QA_AC')
+      ? formatHqaChecklistRepair(humanQa)
+      : null
+  }
+}
+
+export function formatHqaChecklistRepair(humanQa) {
+  if (
+    humanQa.kind !== 'HUMAN_QA_AC' ||
+    humanQa.applicability !== 'REQUIRED' ||
+    !humanQa.valid
+  )
+    throw new Error('VALID REQUIRED HUMAN QA ACCEPTANCE CRITERIA REQUIRED')
+  return [
+    'HQA CHECKLIST REPAIR REQUIRED',
+    '',
+    'Checklist name:',
+    'Human QA Acceptance Criteria',
+    '',
+    '```text',
+    ...humanQa.criteria,
+    '```',
+    '',
+    'Then reply exactly:',
+    '',
+    '`checklist added`'
+  ].join('\n')
+}
+
+export function formatMirrorEvidence({
+  canonical,
+  label,
+  strength,
+  recordedAt,
+  taskId,
+  taskTitle
+}) {
+  const evidence = {
+    version: MIRROR_EVIDENCE_VERSION,
+    kind: canonical.kind,
+    fingerprint: canonical.fingerprint,
+    ids: canonical.ids,
+    label,
+    strength,
+    mirrorMatched: 'YES',
+    initialUnchecked: 'YES',
+    recordedAt: recordedAt ?? null,
+    taskId: taskId ?? null,
+    taskTitle: taskTitle ?? null
+  }
+  const result = validateMirrorEvidence(evidence, canonical)
+  if (!result.valid) throw new Error(result.diagnostics.join('; '))
+  return [
+    `NATIVE ACCEPTANCE MIRROR EVIDENCE v${MIRROR_EVIDENCE_VERSION}`,
+    ...(taskId ? [`ClickUp task ID: ${taskId}`] : []),
+    ...(taskTitle ? [`Task title: ${taskTitle}`] : []),
+    `Acceptance kind: ${canonical.kind}`,
+    `Canonical fingerprint: ${canonical.fingerprint}`,
+    `Acceptance IDs: ${canonical.ids.join(',')}`,
+    `Native checklist label: ${label}`,
+    `Evidence strength: ${strength}`,
+    'Mirror matched canonical criteria: YES',
+    'Initial unchecked state confirmed: YES',
+    ...(recordedAt ? [`Recorded at: ${recordedAt}`] : [])
+  ].join('\n')
+}
+
+export function formatMirrorEvidenceLedgerPage(options) {
+  return `\`\`\`text\n${formatMirrorEvidence(options)}\n\`\`\``
+}