opencode-telos 1.0.0

package/src/sdd/promises/tracker.ts

@@ -0,0 +1,258 @@
+import type { KnowledgeGraph, RequirementNode, BusinessRuleNode, SpecPromise } from "../domain/types.js"
+import { getNodesByType } from "../graph/engine.js"
+import { getExclusionSets, isNodeExcludedOrDeprecated } from "../drift/exclusion.js"
+import { classifyPromiseVerifiability, type DependencyRule } from "./classifier.js"
+
+export interface PromiseReport {
+  total: number
+  pending: number
+  fulfilled: number
+  violated: number
+  unverifiable: number
+  fulfillment_rate: number
+  promises: SpecPromise[]
+}
+
+export function extractPromises(
+  graph: KnowledgeGraph,
+  options?: { autoClassify?: boolean; customRules?: DependencyRule[] },
+): SpecPromise[] {
+  const promises: SpecPromise[] = []
+  const { removed, deprecated } = getExclusionSets(graph)
+  const autoClassify = options?.autoClassify ?? true
+  const customRules = options?.customRules
+
+  // Build a map of persisted promise states from node metadata
+  const persistedStates = buildPersistedPromiseStates(graph)
+
+  const requirements = getNodesByType<RequirementNode>(graph, "requirement")
+    .filter((r) => !isNodeExcludedOrDeprecated(r.id, r.status, removed, deprecated))
+  for (const req of requirements) {
+    const criteria = req.metadata.acceptance_criteria || []
+    for (let i = 0; i < criteria.length; i++) {
+      const criterion = criteria[i]
+      if (typeof criterion !== "string") continue
+      const promiseId = `PRM-${req.id}-${String(i + 1).padStart(3, "0")}`
+      const persisted = persistedStates.get(promiseId)
+      let status: SpecPromise["status"] = (persisted?.status as SpecPromise["status"]) || "pending"
+
+      // Auto-classify unverifiable if infrastructure is missing
+      if (autoClassify && status === "pending") {
+        const classification = classifyPromiseVerifiability(criterion, graph, customRules)
+        if (!classification.verifiable) {
+          status = "unverifiable"
+        }
+      }
+
+      promises.push({
+        id: promiseId,
+        description: criterion,
+        source_node_id: req.id,
+        status,
+        evidence: persisted?.evidence,
+        verified_at: persisted?.verified_at,
+      })
+    }
+
+    if (criteria.length === 0 && req.description) {
+      const promiseId = `PRM-${req.id}-DESC`
+      const persisted = persistedStates.get(promiseId)
+      let status: SpecPromise["status"] = (persisted?.status as SpecPromise["status"]) || "pending"
+
+      if (autoClassify && status === "pending") {
+        const classification = classifyPromiseVerifiability(req.description, graph, customRules)
+        if (!classification.verifiable) {
+          status = "unverifiable"
+        }
+      }
+
+      promises.push({
+        id: promiseId,
+        description: req.description,
+        source_node_id: req.id,
+        status,
+        evidence: persisted?.evidence,
+        verified_at: persisted?.verified_at,
+      })
+    }
+  }
+
+  const rules = getNodesByType<BusinessRuleNode>(graph, "business_rule")
+    .filter((r) => !isNodeExcludedOrDeprecated(r.id, r.status, removed, deprecated))
+  for (const rule of rules) {
+    if (rule.metadata.rule_text) {
+      const promiseId = `PRM-${rule.id}`
+      const persisted = persistedStates.get(promiseId)
+      let status: SpecPromise["status"] = (persisted?.status as SpecPromise["status"]) || "pending"
+
+      if (autoClassify && status === "pending") {
+        const classification = classifyPromiseVerifiability(rule.metadata.rule_text, graph, customRules)
+        if (!classification.verifiable) {
+          status = "unverifiable"
+        }
+      }
+
+      promises.push({
+        id: promiseId,
+        description: rule.metadata.rule_text,
+        source_node_id: rule.id,
+        status,
+        evidence: persisted?.evidence,
+        verified_at: persisted?.verified_at,
+      })
+    }
+  }
+
+  return promises
+}
+
+/**
+ * Build a map of persisted promise states from node metadata.
+ * Promise states are stored in the node's metadata.promise_states object.
+ */
+function buildPersistedPromiseStates(graph: KnowledgeGraph): Map<string, { status: string; evidence?: string; verified_at?: string }> {
+  const states = new Map<string, { status: string; evidence?: string; verified_at?: string }>()
+
+  // Check requirement nodes for promise states
+  const requirements = graph.nodes.filter(n => n.type === "requirement")
+  for (const req of requirements) {
+    const meta = req.metadata as Record<string, unknown>
+    const promiseStates = meta.promise_states as Record<string, { status: string; evidence?: string; verified_at?: string }> | undefined
+    if (promiseStates) {
+      for (const [promiseId, state] of Object.entries(promiseStates)) {
+        states.set(promiseId, state)
+      }
+    }
+  }
+
+  // Check business_rule nodes for promise states
+  const rules = graph.nodes.filter(n => n.type === "business_rule")
+  for (const rule of rules) {
+    const meta = rule.metadata as Record<string, unknown>
+    const promiseStates = meta.promise_states as Record<string, { status: string; evidence?: string; verified_at?: string }> | undefined
+    if (promiseStates) {
+      for (const [promiseId, state] of Object.entries(promiseStates)) {
+        states.set(promiseId, state)
+      }
+    }
+  }
+
+  return states
+}
+
+export function verifyPromise(
+  graph: KnowledgeGraph,
+  promiseId: string,
+  evidence: string,
+): SpecPromise | null {
+  const allPromises = extractPromises(graph)
+  const promise = allPromises.find((p) => p.id === promiseId)
+  if (!promise) return null
+
+  promise.status = "fulfilled"
+  promise.evidence = evidence
+  promise.verified_at = new Date().toISOString()
+
+  // Persist the state in the source node's metadata
+  persistPromiseState(graph, promise.source_node_id, promiseId, {
+    status: "fulfilled",
+    evidence,
+    verified_at: promise.verified_at,
+  })
+
+  return promise
+}
+
+export function markPromiseViolated(
+  graph: KnowledgeGraph,
+  promiseId: string,
+): SpecPromise | null {
+  const allPromises = extractPromises(graph)
+  const promise = allPromises.find((p) => p.id === promiseId)
+  if (!promise) return null
+
+  promise.status = "violated"
+  promise.verified_at = new Date().toISOString()
+
+  // Persist the state in the source node's metadata
+  persistPromiseState(graph, promise.source_node_id, promiseId, {
+    status: "violated",
+    verified_at: promise.verified_at,
+  })
+
+  return promise
+}
+
+/**
+ * Persist a promise state in the source node's metadata.
+ * This ensures promise verification survives session restarts.
+ */
+function persistPromiseState(
+  graph: KnowledgeGraph,
+  sourceNodeId: string,
+  promiseId: string,
+  state: { status: string; evidence?: string; verified_at?: string },
+): void {
+  const node = graph.nodes.find(n => n.id === sourceNodeId)
+  if (!node) return
+
+  const meta = node.metadata as Record<string, unknown>
+  if (!meta.promise_states) {
+    meta.promise_states = {}
+  }
+  ;(meta.promise_states as Record<string, unknown>)[promiseId] = state
+
+  // Update graph timestamp for cross-process cache invalidation
+  graph.metadata.updated_at = new Date().toISOString()
+}
+
+export function getPromiseReport(graph: KnowledgeGraph): PromiseReport {
+  const promises = extractPromises(graph)
+
+  const pending = promises.filter((p) => p.status === "pending").length
+  const fulfilled = promises.filter((p) => p.status === "fulfilled").length
+  const violated = promises.filter((p) => p.status === "violated").length
+  const unverifiable = promises.filter((p) => p.status === "unverifiable").length
+  const verifiable = promises.length - unverifiable
+
+  return {
+    total: promises.length,
+    pending,
+    fulfilled,
+    violated,
+    unverifiable,
+    fulfillment_rate: verifiable > 0 ? fulfilled / verifiable : 1,
+    promises,
+  }
+}
+
+export function formatPromiseReport(report: PromiseReport): string {
+  const lines = [
+    `## Promise Report`,
+    `**Total:** ${report.total}`,
+    `**Pending:** ${report.pending}`,
+    `**Fulfilled:** ${report.fulfilled}`,
+    `**Violated:** ${report.violated}`,
+    `**Unverifiable:** ${report.unverifiable}`,
+    `**Fulfillment Rate:** ${(report.fulfillment_rate * 100).toFixed(1)}%`,
+  ]
+
+  if (report.violated > 0) {
+    lines.push("\n### Violated Promises")
+    for (const p of report.promises.filter((p) => p.status === "violated")) {
+      lines.push(`- **${p.id}** (${p.source_node_id}): ${p.description}`)
+    }
+  }
+
+  if (report.pending > 0) {
+    lines.push("\n### Pending Promises")
+    for (const p of report.promises.filter((p) => p.status === "pending").slice(0, 10)) {
+      lines.push(`- **${p.id}** (${p.source_node_id}): ${p.description}`)
+    }
+    if (report.pending > 10) {
+      lines.push(`- ... and ${report.pending - 10} more`)
+    }
+  }
+
+  return lines.join("\n")
+}

package/src/sdd/quality/scorer.ts

@@ -0,0 +1,263 @@
+import type { KnowledgeGraph } from "../domain/types.js"
+import { getNodesByType } from "../graph/engine.js"
+import { getExclusionSets, isNodeExcludedOrDeprecated } from "../drift/exclusion.js"
+import { validateGraph } from "../validation/validator.js"
+import { detectDrift } from "../drift/detector.js"
+import { getPromiseReport } from "../promises/tracker.js"
+import { validateAgainstConstitution } from "../constitution/validator.js"
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs"
+import { join, dirname } from "path"
+
+export interface QualityFactor {
+  name: string
+  score: number
+  weight: number
+  details: string
+}
+
+export interface QualityReport {
+  score: number
+  trend: "improving" | "stable" | "declining"
+  factors: QualityFactor[]
+  history: Array<{ timestamp: string; score: number }>
+}
+
+/**
+ * Options for controlling quality scoring scope.
+ */
+export interface QualityScoringOptions {
+  /** Only calculate these specific factors. */
+  focusFactors?: string[]
+  /** Skip these factors (use cached results instead). */
+  skipFactors?: string[]
+  /** Skip drift detection (uses cached result). */
+  skipDrift?: boolean
+  /** Skip promise calculation (uses cached result). */
+  skipPromises?: boolean
+  /** Skip constitution check (uses cached result). */
+  skipConstitution?: boolean
+  /** Skip validation (uses cached result). */
+  skipValidation?: boolean
+  /** Cache for individual factor scores (factor_name → score). Reuse if provided. */
+  factorCache?: Map<string, { score: number; details: string; timestamp: number }>
+  /** Maximum age in ms for cached factors to be considered fresh (default: 60000 = 1 min). */
+  cacheMaxAge?: number
+}
+
+const HISTORY_FILE = ".sdd/quality-history.json"
+const MAX_HISTORY = 20
+
+const FACTOR_WEIGHTS = {
+  validation: 0.25,
+  drift: 0.20,
+  promises: 0.20,
+  completeness: 0.15,
+  constitution: 0.10,
+  coverage: 0.10,
+}
+
+export function calculateQualityScore(
+  graph: KnowledgeGraph,
+  projectDir: string,
+  options?: QualityScoringOptions,
+): QualityReport {
+  const factors: QualityFactor[] = []
+  const focusSet = options?.focusFactors ? new Set(options.focusFactors) : null
+  const skipSet = options?.skipFactors ? new Set(options.skipFactors) : null
+
+  const shouldInclude = (name: string) => {
+    if (skipSet?.has(name)) return false
+    if (focusSet && !focusSet.has(name)) return false
+    return true
+  }
+
+  const getCachedFactor = (name: string): QualityFactor | null => {
+    if (!options?.factorCache) return null
+    const cached = options.factorCache.get(name)
+    if (!cached) return null
+    const maxAge = options.cacheMaxAge ?? 60000
+    if (Date.now() - cached.timestamp > maxAge) return null // Expired
+    return { name, score: cached.score, weight: FACTOR_WEIGHTS[name as keyof typeof FACTOR_WEIGHTS] || 0.1, details: cached.details }
+  }
+
+  const setCachedFactor = (name: string, score: number, details: string) => {
+    if (options?.factorCache) {
+      options.factorCache.set(name, { score, details, timestamp: Date.now() })
+    }
+  }
+
+  // Validation factor
+  if (shouldInclude("validation")) {
+    const cached = getCachedFactor("validation")
+    if (cached) {
+      factors.push(cached)
+    } else if (!options?.skipValidation) {
+      const validation = validateGraph(graph)
+      const validationScore = validation.errors.length === 0 ? 1 : Math.max(0, 1 - validation.errors.length / Math.max(graph.nodes.length, 1))
+      const details = `${validation.errors.length} errors, ${validation.warnings.length} warnings`
+      factors.push({ name: "validation", score: validationScore, weight: FACTOR_WEIGHTS.validation, details })
+      setCachedFactor("validation", validationScore, details)
+    } else {
+      factors.push({ name: "validation", score: 1, weight: FACTOR_WEIGHTS.validation, details: "Skipped (cached)" })
+    }
+  }
+
+  // Drift factor
+  if (shouldInclude("drift")) {
+    const cached = getCachedFactor("drift")
+    if (cached) {
+      factors.push(cached)
+    } else if (!options?.skipDrift) {
+      const drift = detectDrift(graph, projectDir)
+      const driftItems = drift.missing_files.length + drift.untracked_files.length + drift.spec_code_mismatches.length
+      const driftScore = driftItems === 0 ? 1 : Math.max(0, 1 - driftItems / Math.max(graph.nodes.length, 1))
+      const details = `${driftItems} drift items detected`
+      factors.push({ name: "drift", score: driftScore, weight: FACTOR_WEIGHTS.drift, details })
+      setCachedFactor("drift", driftScore, details)
+    } else {
+      factors.push({ name: "drift", score: 1, weight: FACTOR_WEIGHTS.drift, details: "Skipped (cached)" })
+    }
+  }
+
+  // Promises factor
+  if (shouldInclude("promises")) {
+    const cached = getCachedFactor("promises")
+    if (cached) {
+      factors.push(cached)
+    } else if (!options?.skipPromises) {
+      const promiseReport = getPromiseReport(graph)
+      const promisesScore = promiseReport.total === 0 ? 1 : promiseReport.fulfillment_rate
+      const details = `${promiseReport.fulfilled}/${promiseReport.total} fulfilled (${(promiseReport.fulfillment_rate * 100).toFixed(0)}%)`
+      factors.push({ name: "promises", score: promisesScore, weight: FACTOR_WEIGHTS.promises, details })
+      setCachedFactor("promises", promisesScore, details)
+    } else {
+      factors.push({ name: "promises", score: 1, weight: FACTOR_WEIGHTS.promises, details: "Skipped (cached)" })
+    }
+  }
+
+  // Completeness factor
+  if (shouldInclude("completeness")) {
+    const cached = getCachedFactor("completeness")
+    if (cached) {
+      factors.push(cached)
+    } else {
+      const expectedTypes = ["project", "feature", "requirement", "entity", "api"]
+      const presentTypes = expectedTypes.filter((t) => graph.nodes.some((n) => n.type === t))
+      const completenessScore = presentTypes.length / expectedTypes.length
+      const details = `${presentTypes.length}/${expectedTypes.length} expected node types present`
+      factors.push({ name: "completeness", score: completenessScore, weight: FACTOR_WEIGHTS.completeness, details })
+      setCachedFactor("completeness", completenessScore, details)
+    }
+  }
+
+  // Constitution factor
+  if (shouldInclude("constitution")) {
+    const cached = getCachedFactor("constitution")
+    if (cached) {
+      factors.push(cached)
+    } else if (!options?.skipConstitution) {
+      const constitutionResult = validateAgainstConstitution(graph)
+      const constitutionScore = constitutionResult.violations.length === 0 ? 1 : Math.max(0, 1 - constitutionResult.violations.length / Math.max(constitutionResult.total_principles, 1))
+      const details = `${constitutionResult.violations.length}/${constitutionResult.total_principles} principles violated`
+      factors.push({ name: "constitution", score: constitutionScore, weight: FACTOR_WEIGHTS.constitution, details })
+      setCachedFactor("constitution", constitutionScore, details)
+    } else {
+      factors.push({ name: "constitution", score: 1, weight: FACTOR_WEIGHTS.constitution, details: "Skipped (cached)" })
+    }
+  }
+
+  // Coverage factor
+  if (shouldInclude("coverage")) {
+    const cached = getCachedFactor("coverage")
+    if (cached) {
+      factors.push(cached)
+    } else {
+      const { removed, deprecated } = getExclusionSets(graph)
+      const requirements = getNodesByType(graph, "requirement")
+        .filter((r) => !isNodeExcludedOrDeprecated(r.id, r.status, removed, deprecated))
+      const tests = getNodesByType(graph, "test")
+      const coverageScore = requirements.length === 0 ? 1 : Math.min(1, tests.length / requirements.length)
+      const details = `${tests.length} tests for ${requirements.length} requirements`
+      factors.push({ name: "coverage", score: coverageScore, weight: FACTOR_WEIGHTS.coverage, details })
+      setCachedFactor("coverage", coverageScore, details)
+    }
+  }
+
+  // Renormalize weights if some factors were skipped
+  const totalWeight = factors.reduce((sum, f) => sum + f.weight, 0)
+  const totalScore = factors.reduce((sum, f) => sum + f.score * (f.weight / totalWeight), 0)
+  const finalScore = Math.round(totalScore * 100) / 100
+
+  const history = loadHistory(projectDir)
+  const trend = calculateTrend(history, finalScore)
+
+  history.push({ timestamp: new Date().toISOString(), score: finalScore })
+  if (history.length > MAX_HISTORY) history.splice(0, history.length - MAX_HISTORY)
+  saveHistory(projectDir, history)
+
+  return {
+    score: finalScore,
+    trend,
+    factors,
+    history,
+  }
+}
+
+function loadHistory(projectDir: string): Array<{ timestamp: string; score: number }> {
+  const path = join(projectDir, HISTORY_FILE)
+  if (!existsSync(path)) return []
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"))
+  } catch {
+    return []
+  }
+}
+
+function saveHistory(projectDir: string, history: Array<{ timestamp: string; score: number }>): void {
+  const path = join(projectDir, HISTORY_FILE)
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(path, JSON.stringify(history, null, 2), "utf-8")
+}
+
+function calculateTrend(
+  history: Array<{ timestamp: string; score: number }>,
+  _currentScore: number,
+): "improving" | "stable" | "declining" {
+  if (history.length < 3) return "stable"
+
+  const recent = history.slice(-5)
+  const avgRecent = recent.reduce((s, h) => s + h.score, 0) / recent.length
+  const avgOlder = history.slice(0, -5).reduce((s, h) => s + h.score, 0) / Math.max(history.length - 5, 1)
+
+  const diff = avgRecent - avgOlder
+  if (diff > 0.02) return "improving"
+  if (diff < -0.02) return "declining"
+  return "stable"
+}
+
+export function formatQualityReport(report: QualityReport): string {
+  const trendEmoji = report.trend === "improving" ? "📈" : report.trend === "declining" ? "📉" : "➡️"
+  const scorePercent = (report.score * 100).toFixed(1)
+
+  const lines = [
+    `## Quality Score: ${scorePercent}% ${trendEmoji}`,
+    `**Trend:** ${report.trend}`,
+    "",
+    "### Factors",
+  ]
+
+  for (const f of report.factors) {
+    const bar = "█".repeat(Math.round(f.score * 10)) + "░".repeat(10 - Math.round(f.score * 10))
+    lines.push(`- **${f.name}** (${(f.weight * 100).toFixed(0)}%): ${bar} ${(f.score * 100).toFixed(0)}% — ${f.details}`)
+  }
+
+  if (report.history.length > 1) {
+    lines.push("\n### History (last 5)")
+    for (const h of report.history.slice(-5)) {
+      lines.push(`- ${h.timestamp.slice(0, 19)}: ${(h.score * 100).toFixed(1)}%`)
+    }
+  }
+
+  return lines.join("\n")
+}