certainty-units 0.2.0

package/src/adapters/linear.js

@@ -0,0 +1,130 @@
+// Linear adapter — maps Linear issues to CU items via GraphQL
+
+import {
+  applyMap, mergeFieldMap,
+  extractAcceptanceCriteria, validationFromLabels, tierFromLabels,
+} from './util.js'
+
+const LINEAR_API = 'https://api.linear.app/graphql'
+
+const ISSUES_QUERY = `
+  query Issues($teamId: ID!, $after: String) {
+    issues(
+      filter: { team: { id: { eq: $teamId } } }
+      first: 100
+      after: $after
+    ) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        id
+        identifier
+        title
+        description
+        priority
+        estimate
+        state { name type }
+        assignee { name }
+        labels { nodes { name } }
+        comments { nodes { id } }
+        createdAt
+        updatedAt
+        url
+      }
+    }
+  }
+`
+
+async function graphql(apiKey, query, variables = {}) {
+  const res = await fetch(LINEAR_API, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: apiKey,
+    },
+    body: JSON.stringify({ query, variables }),
+  })
+  if (!res.ok) throw new Error(`Linear API ${res.status}: ${await res.text()}`)
+  const json = await res.json()
+  if (json.errors) throw new Error(`Linear GraphQL: ${json.errors.map(e => e.message).join(', ')}`)
+  return json.data
+}
+
+async function fetchAllIssues(apiKey, teamId) {
+  const issues = []
+  let after = null
+  do {
+    const data = await graphql(apiKey, ISSUES_QUERY, { teamId, after })
+    issues.push(...data.issues.nodes)
+    after = data.issues.pageInfo.hasNextPage ? data.issues.pageInfo.endCursor : null
+  } while (after)
+  return issues
+}
+
+// Default field mapping — overridable via certainty.config.yaml fieldMap
+const DEFAULT_MAP = {
+  validation_status: {
+    field: 'state.type',
+    map: {
+      completed: 'validated',
+      started:   'assumed',
+      triage:    'needs_clarification',
+      backlog:   'unvalidated',
+      cancelled: 'unvalidated',
+    },
+    default: 'unvalidated',
+  },
+  workflow_status: {
+    field: 'state.type',
+    map: {
+      completed: 'done',
+      started:   'in_progress',
+      triage:    'todo',
+      backlog:   'todo',
+      cancelled: 'todo',
+    },
+    default: 'todo',
+  },
+  cu_tier: {
+    field: 'priority',
+    map: { 1: 'advanced', 2: 'intermediate', 3: 'basic', 4: 'basic' },
+    default: null,
+  },
+}
+
+export async function fetchItems(config) {
+  const { apiKey, teamId, fieldMap: userFieldMap } = config
+  if (!apiKey) throw new Error('linear.apiKey is required')
+  if (!teamId) throw new Error('linear.teamId is required')
+
+  const issues = await fetchAllIssues(apiKey, teamId)
+  const fieldMap = mergeFieldMap(DEFAULT_MAP, userFieldMap)
+
+  return issues.map(issue => {
+    const labels = issue.labels?.nodes?.map(l => l.name) ?? []
+    const description = issue.description || ''
+
+    return {
+      id:                 issue.id,
+      external_id:        issue.identifier,
+      title:              issue.title,
+      description,
+      url:                issue.url,
+      // an explicit validation label beats inferring validation from workflow state
+      validation_status:  validationFromLabels(labels) ?? applyMap(issue, fieldMap.validation_status),
+      workflow_status:    applyMap(issue, fieldMap.workflow_status),
+      cu_tier:            tierFromLabels(labels) ?? applyMap(issue, fieldMap.cu_tier),
+      cu_value:           issue.estimate ?? 1,
+      evidence:           description,
+      acceptance_criteria: extractAcceptanceCriteria(description),
+      novelty_rating:     null,
+      complexity_rating:  null,
+      dependency_rating:  null,
+      citation_count:     issue.comments?.nodes?.length ?? 0,
+      assignee:           issue.assignee?.name ?? null,
+      labels,
+      created_at:         issue.createdAt,
+      updated_at:         issue.updatedAt,
+      source:             'linear',
+    }
+  })
+}

package/src/adapters/notion.js

@@ -0,0 +1,143 @@
+// Notion adapter — maps a Notion database to CU items via Notion API
+
+import { mergeFieldMap, validationFromLabels, tierFromLabels } from './util.js'
+
+const NOTION_API = 'https://api.notion.com/v1'
+const NOTION_VERSION = '2022-06-28'
+
+async function notionFetch(apiKey, path, body = null) {
+  const res = await fetch(`${NOTION_API}${path}`, {
+    method: body ? 'POST' : 'GET',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Notion-Version': NOTION_VERSION,
+      'Content-Type': 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  if (!res.ok) throw new Error(`Notion API ${res.status}: ${await res.text()}`)
+  return res.json()
+}
+
+async function fetchAllPages(apiKey, databaseId) {
+  const pages = []
+  let cursor = null
+
+  do {
+    const body = { page_size: 100 }
+    if (cursor) body.start_cursor = cursor
+    const data = await notionFetch(apiKey, `/databases/${databaseId}/query`, body)
+    pages.push(...data.results)
+    cursor = data.has_more ? data.next_cursor : null
+  } while (cursor)
+
+  return pages
+}
+
+// Extract plain text from a Notion rich_text array
+function richText(arr) {
+  return arr?.map(r => r.plain_text).join('') ?? ''
+}
+
+// Extract value from a Notion property by type
+function extractProp(prop) {
+  if (!prop) return null
+  switch (prop.type) {
+    case 'title':        return richText(prop.title)
+    case 'rich_text':   return richText(prop.rich_text)
+    case 'select':      return prop.select?.name ?? null
+    case 'status':      return prop.status?.name ?? null
+    case 'multi_select': return prop.multi_select?.map(s => s.name) ?? []
+    case 'number':      return prop.number
+    case 'checkbox':    return prop.checkbox
+    case 'date':        return prop.date?.start ?? null
+    case 'people':      return prop.people?.map(p => p.name).join(', ') ?? null
+    case 'url':         return prop.url
+    default:            return null
+  }
+}
+
+// Default field map — teams override column names via config
+const DEFAULT_MAP = {
+  validation_status: {
+    field: 'Status',  // Notion column name
+    map: {
+      Done:        'validated',
+      'In Progress': 'assumed',
+      'To Do':     'unvalidated',
+      Backlog:     'unvalidated',
+    },
+    default: 'unvalidated',
+  },
+  workflow_status: {
+    field: 'Status',
+    map: {
+      Done:          'done',
+      'In Progress': 'in_progress',
+      'To Do':       'todo',
+      Backlog:       'todo',
+    },
+    default: 'todo',
+  },
+  cu_tier: {
+    field: 'Priority',
+    map: {
+      High:   'advanced',
+      Medium: 'intermediate',
+      Low:    'basic',
+    },
+    default: null,
+  },
+  title_field:       { field: 'Name' },
+  assignee_field:    { field: 'Assignee' },
+  estimate_field:    { field: 'Estimate' },
+  labels_field:      { field: 'Tags' },                 // multi_select
+  description_field: { field: 'Description' },          // rich_text
+  acceptance_field:  { field: 'Acceptance Criteria' },  // rich_text
+}
+
+export async function fetchItems(config) {
+  const { apiKey, databaseId } = config
+  if (!apiKey)     throw new Error('notion.apiKey is required')
+  if (!databaseId) throw new Error('notion.databaseId is required')
+
+  const pages = await fetchAllPages(apiKey, databaseId)
+  const fm = mergeFieldMap(DEFAULT_MAP, config.fieldMap)
+
+  return pages.map(page => {
+    const props = page.properties
+    const statusRaw = extractProp(props[fm.validation_status.field])
+    const labelsRaw = extractProp(props[fm.labels_field?.field])
+    const labels = Array.isArray(labelsRaw) ? labelsRaw : []
+    const description = extractProp(props[fm.description_field?.field]) ?? ''
+    const acceptance = extractProp(props[fm.acceptance_field?.field])
+
+    return {
+      id:                  page.id,
+      external_id:         page.id.slice(0, 8),
+      title:               extractProp(props[fm.title_field.field]) ?? 'Untitled',
+      description,
+      url:                 page.url,
+      // an explicit validation tag beats inferring validation from workflow state
+      validation_status:   validationFromLabels(labels)
+                             ?? fm.validation_status.map[statusRaw] ?? fm.validation_status.default,
+      workflow_status:     fm.workflow_status.map[statusRaw] ?? fm.workflow_status.default,
+      cu_tier:             tierFromLabels(labels) ?? (() => {
+        const raw = extractProp(props[fm.cu_tier.field])
+        return fm.cu_tier.map[raw] ?? fm.cu_tier.default
+      })(),
+      cu_value:            extractProp(props[fm.estimate_field?.field]) ?? 1,
+      evidence:            description,
+      acceptance_criteria: typeof acceptance === 'string' && acceptance.trim() ? acceptance : null,
+      novelty_rating:      null,
+      complexity_rating:   null,
+      dependency_rating:   null,
+      citation_count:      0,
+      assignee:            extractProp(props[fm.assignee_field?.field]),
+      labels,
+      created_at:          page.created_time,
+      updated_at:          page.last_edited_time,
+      source:              'notion',
+    }
+  })
+}

package/src/adapters/util.js

@@ -0,0 +1,90 @@
+// Shared adapter helpers: field mapping + signal extraction from real work items.
+
+export function getField(obj, path) {
+  return path.split('.').reduce((o, k) => o?.[k], obj)
+}
+
+export function applyMap(issue, fieldDef) {
+  const raw = getField(issue, fieldDef.field)
+  return fieldDef.map[raw] ?? fieldDef.default
+}
+
+export function mergeFieldMap(defaults, userMap = {}) {
+  const merged = structuredClone(defaults)
+  for (const [field, def] of Object.entries(userMap)) {
+    if (typeof def === 'object' && def !== null && def.map) {
+      merged[field] = {
+        field:   def.field ?? merged[field]?.field,
+        map:     { ...merged[field]?.map, ...def.map },
+        default: def.default ?? merged[field]?.default ?? null,
+      }
+    } else {
+      merged[field] = def
+    }
+  }
+  return merged
+}
+
+// Pull an acceptance-criteria block out of a free-text description.
+// Recognizes a heading containing "acceptance criteria" (markdown #, bold, or
+// plain line ending in ":"), or falls back to markdown checklist items.
+export function extractAcceptanceCriteria(text) {
+  if (!text?.trim()) return null
+
+  const lines = text.split('\n')
+  const headingRe = /^\s*(?:#{1,6}\s*|\*\*)?\s*acceptance criteria\b/i
+
+  const start = lines.findIndex(l => headingRe.test(l))
+  if (start !== -1) {
+    const block = []
+    for (let i = start + 1; i < lines.length; i++) {
+      // stop at the next heading
+      if (/^\s*#{1,6}\s/.test(lines[i]) || /^\s*\*\*[^*]+\*\*\s*$/.test(lines[i])) break
+      block.push(lines[i])
+    }
+    const body = block.join('\n').trim()
+    if (body) return body
+  }
+
+  // fallback: markdown checklist anywhere in the description
+  const checklist = lines.filter(l => /^\s*[-*]\s*\[[ xX]\]/.test(l))
+  if (checklist.length) return checklist.join('\n')
+
+  return null
+}
+
+// Labels are the cheapest place for a team to record validation explicitly.
+// A label like "validated" beats inferring validation from workflow state.
+const VALIDATION_LABELS = {
+  'validated':            'validated',
+  'validation:validated': 'validated',
+  'assumed':              'assumed',
+  'assumption':           'assumed',
+  'validation:assumed':   'assumed',
+  'needs-clarification':  'needs_clarification',
+  'needs clarification':  'needs_clarification',
+  'unvalidated':          'unvalidated',
+}
+
+export function validationFromLabels(labels = []) {
+  for (const label of labels) {
+    const hit = VALIDATION_LABELS[String(label).toLowerCase().trim()]
+    if (hit) return hit
+  }
+  return null
+}
+
+// cu:basic / cu:intermediate / cu:advanced labels set the tier explicitly.
+const TIER_LABELS = {
+  'cu:basic':        'basic',
+  'cu:intermediate': 'intermediate',
+  'cu:advanced':     'advanced',
+}
+
+export function tierFromLabels(labels = []) {
+  for (const label of labels) {
+    const hit = TIER_LABELS[String(label).toLowerCase().trim()]
+    if (hit) return hit
+  }
+  return null
+}

package/src/certainty.js

@@ -0,0 +1,152 @@
+// Certainty Score engine — ported from Propozel (MIT)
+// Items must conform to the CU shape: { validation_status, workflow_status,
+// cu_tier, cu_value, evidence, acceptance_criteria, novelty_rating,
+// complexity_rating, dependency_rating, certainty_score }
+
+export const DEFAULT_CU_CONFIG = {
+  signal_weight: 0.6,
+  signals: {
+    validation: 40,
+    workflow: 20,
+    citations: 15,
+    acceptance: 10,
+    tier: 10,
+    evidence: 5,
+  },
+  dimension_weight: 0.4,
+  dimensions: {
+    novelty: 0.45,
+    complexity: 0.35,
+    dependencies: 0.20,
+  },
+}
+
+const VALIDATION_SCORE = {
+  validated: 40,
+  assumed: 10,
+  needs_clarification: 5,
+  unvalidated: 0,
+}
+
+const WORKFLOW_SCORE = {
+  done: 20,
+  in_progress: 10,
+  review: 15,
+  todo: 0,
+  blocked: 0,
+}
+
+// Per-signal breakdown: points earned, max possible, why, and what would earn the rest.
+// This is the single source of truth for the signal score.
+export function computeScoreBreakdown(item, citationCount = 0) {
+  const validation = VALIDATION_SCORE[item.validation_status] || 0
+  const workflow = WORKFLOW_SCORE[item.workflow_status] || 0
+  const citations = Math.min(citationCount * 5, 15)
+  const acceptance = item.acceptance_criteria?.trim() ? 10 : 0
+  const tier = item.cu_tier ? 10 : 0
+  const evidence = item.evidence?.trim() ? 5 : 0
+
+  return [
+    {
+      signal: 'validation', points: validation, max: 40,
+      reason: item.validation_status || 'unvalidated',
+      hint: 'validate the assumption (label it, or link evidence)',
+    },
+    {
+      signal: 'workflow', points: workflow, max: 20,
+      reason: item.workflow_status || 'todo',
+      hint: 'progress the item through the workflow',
+    },
+    {
+      signal: 'discussion', points: citations, max: 15,
+      reason: `${citationCount} comment${citationCount === 1 ? '' : 's'}`,
+      hint: 'discuss it — undebated items hide risk',
+    },
+    {
+      signal: 'acceptance criteria', points: acceptance, max: 10,
+      reason: acceptance ? 'defined' : 'none found',
+      hint: 'add an "Acceptance Criteria" section or checklist',
+    },
+    {
+      signal: 'CU tier', points: tier, max: 10,
+      reason: item.cu_tier || 'not set',
+      hint: 'size it (basic / intermediate / advanced)',
+    },
+    {
+      signal: 'evidence', points: evidence, max: 5,
+      reason: evidence ? 'has description' : 'empty description',
+      hint: 'write down what is known',
+    },
+  ]
+}
+
+export function computeSignalScore(item, citationCount = 0) {
+  const total = computeScoreBreakdown(item, citationCount)
+    .reduce((sum, s) => sum + s.points, 0)
+  return Math.min(total, 100)
+}
+
+// Largest missing signals first — "what would raise certainty on this item"
+export function biggestGaps(item, citationCount = 0, limit = 3) {
+  return computeScoreBreakdown(item, citationCount)
+    .map(s => ({ ...s, gap: s.max - s.points }))
+    .filter(s => s.gap > 0)
+    .sort((a, b) => b.gap - a.gap)
+    .slice(0, limit)
+}
+
+export function computeDimensionScore(item, config = DEFAULT_CU_CONFIG) {
+  const n = item.novelty_rating || 3
+  const c = item.complexity_rating || 3
+  const d = item.dependency_rating || 3
+  const w = config.dimensions
+  const weighted = n * w.novelty + c * w.complexity + d * w.dependencies
+  return Math.round(weighted * 20)
+}
+
+export function computeCertaintyScore(item, citationCount = 0, config = DEFAULT_CU_CONFIG) {
+  const signalScore = computeSignalScore(item, citationCount)
+  const dimensionScore = computeDimensionScore(item, config)
+  const hasDimensions = item.novelty_rating || item.complexity_rating || item.dependency_rating
+  if (!hasDimensions) return signalScore
+  return Math.min(
+    Math.round(signalScore * config.signal_weight + dimensionScore * config.dimension_weight),
+    100
+  )
+}
+
+export function certaintyLevel(score) {
+  if (score >= 80) return 'high'
+  if (score >= 50) return 'medium'
+  if (score >= 20) return 'low'
+  return 'uncertain'
+}
+
+export const CU_TIERS = [
+  { value: 'basic',        label: 'Basic',        multiplier: 1 },
+  { value: 'intermediate', label: 'Intermediate',  multiplier: 3 },
+  { value: 'advanced',     label: 'Advanced',      multiplier: 6 },
+]
+
+export function computeCUMetrics(items) {
+  const total = items.length
+  const withCU = items.filter(i => i.cu_tier)
+  const completed = withCU.filter(i => i.workflow_status === 'done')
+  const accepted = completed.filter(i => i.validation_status === 'validated')
+  const totalCUValue = withCU.reduce((sum, i) => sum + (i.cu_value || 1), 0)
+  const completedCUValue = completed.reduce((sum, i) => sum + (i.cu_value || 1), 0)
+  const scores = items.map(i => i.certainty_score || 0)
+  const avgCertainty = total ? Math.round(scores.reduce((a, b) => a + b, 0) / total) : 0
+  return {
+    totalItems: total,
+    cuItems: withCU.length,
+    totalCUValue,
+    completedCUValue,
+    completionRate: withCU.length ? Math.round((completed.length / withCU.length) * 100) : 0,
+    integrityScore: completed.length ? Math.round((accepted.length / completed.length) * 100) : 0,
+    avgCertaintyScore: avgCertainty,
+    velocity: completedCUValue,
+    uphill: items.filter(i => (i.certainty_score || 0) < 50).length,
+    downhill: items.filter(i => (i.certainty_score || 0) >= 50).length,
+  }
+}