@agentskit/doc-bridge 1.6.4 → 1.7.45

package/scripts/verification-harness.mjs

@@ -10,22 +10,43 @@ import {
   readdirSync,
   renameSync,
   rmSync,
-  statSync,
   writeFileSync,
 } from 'node:fs'
 import { dirname, join, relative, resolve, sep } from 'node:path'
 
-const VERSION = '1.1.0'
-const STATES = new Set(['PLANNED', 'VERIFYING', 'AWAITING_HUMAN_APPROVAL', 'AWAITING_AUTHORIZATION', 'COMPLETE', 'BLOCKED', 'FAILED'])
-const PROFILES = new Set(['strict', 'poc', 'custom'])
+const VERSION = '1.4.0'
+const STATES = new Set(['CLARIFYING', 'PLANNED', 'VERIFYING', 'AWAITING_HUMAN_APPROVAL', 'AWAITING_AUTHORIZATION', 'COMPLETE', 'BLOCKED', 'FAILED'])
+const PROFILES = new Set(['default', 'strict', 'poc', 'custom', 'enterprise'])
+const SURFACES = ['logic', 'endpoint', 'database', 'cli', 'mcp', 'ui', 'docs']
+const PROFILE_POLICIES = {
+  default: { requiresExplicitExemptions: false, requiresAllSurfaces: false, requiresMeasurement: false, requiresTracking: false },
+  strict: { requiresExplicitExemptions: false, requiresAllSurfaces: false, requiresMeasurement: false, requiresTracking: false },
+  poc: { requiresExplicitExemptions: true, requiresAllSurfaces: false, requiresMeasurement: false, requiresTracking: false },
+  custom: { requiresExplicitExemptions: true, requiresAllSurfaces: false, requiresMeasurement: false, requiresTracking: false },
+  enterprise: { requiresExplicitExemptions: false, requiresAllSurfaces: true, requiresMeasurement: true, requiresTracking: true },
+}
 const CATEGORIES = new Set(['build', 'test', 'lint', 'logic', 'endpoint', 'database', 'cli', 'mcp', 'ui', 'docs', 'custom'])
 const INTENTS = new Set(['ok', 'certo', 'certa', 'aprovado', 'aprovada', 'approve', 'approved', 'confirmo', 'confirmado', 'confirmed', 'yes'])
 const DEFAULT_CONFIG = '.codex/verification.json'
+const LEGAL_TRANSITIONS = {
+  null: ['PLANNED'],
+  CLARIFYING: ['PLANNED', 'BLOCKED', 'FAILED'],
+  PLANNED: ['CLARIFYING', 'VERIFYING', 'BLOCKED', 'FAILED'],
+  VERIFYING: ['AWAITING_HUMAN_APPROVAL', 'AWAITING_AUTHORIZATION', 'COMPLETE', 'BLOCKED', 'FAILED'],
+  AWAITING_HUMAN_APPROVAL: ['AWAITING_AUTHORIZATION', 'COMPLETE', 'BLOCKED', 'FAILED'],
+  AWAITING_AUTHORIZATION: ['COMPLETE', 'BLOCKED', 'FAILED'],
+  BLOCKED: [],
+  FAILED: [],
+  COMPLETE: [],
+}
 
 const fail = (message) => { throw new Error(message) }
 const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex')
 const now = () => new Date().toISOString()
 const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'))
+const assertKnownKeys = (value, allowed, label) => {
+  for (const key of Object.keys(value ?? {})) if (!allowed.has(key)) fail(`${label}.${key} is not supported.`)
+}
 const writeAtomic = (path, value) => {
   mkdirSync(dirname(path), { recursive: true })
   const temp = `${path}.tmp-${process.pid}`
@@ -58,6 +79,7 @@ const inside = (root, path) => {
 const surfaceRequired = (value, name) => {
   if (typeof value === 'boolean') return { required: value, reason: value ? undefined : `${name} is not part of this verification target.` }
   if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`surfaces.${name} must be a boolean or { required, reason }.`)
+  assertKnownKeys(value, new Set(['required', 'reason']), `surfaces.${name}`)
   if (typeof value.required !== 'boolean') fail(`surfaces.${name}.required must be boolean.`)
   if (!value.required && typeof value.reason !== 'string') fail(`surfaces.${name}.reason is required when the surface is not required.`)
   return { required: value.required, ...(value.reason ? { reason: value.reason } : {}) }
@@ -65,35 +87,91 @@ const surfaceRequired = (value, name) => {
 
 const validateConfig = (raw, configPath) => {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail(`Invalid verification config: ${configPath}`)
+  assertKnownKeys(raw, new Set(['schemaVersion', 'project', 'root', 'profile', 'contract', 'surfaces', 'checks', 'exemptions', 'measurement', 'tracking', 'cleanup', 'overrides']), 'verification config')
   if (raw.schemaVersion !== 1) fail('verification config schemaVersion must be 1.')
   if (typeof raw.project !== 'string' || !raw.project) fail('verification config project is required.')
   if (raw.root !== undefined && typeof raw.root !== 'string') fail('verification config root must be a string.')
-  if (!PROFILES.has(raw.profile)) fail(`verification config profile must be one of: ${[...PROFILES].join(', ')}.`)
+  const profile = raw.profile ?? 'default'
+  if (!PROFILES.has(profile)) fail(`verification config profile must be one of: ${[...PROFILES].join(', ')}.`)
+  const policy = PROFILE_POLICIES[profile]
+  if (raw.overrides !== undefined) {
+    if (!raw.overrides || typeof raw.overrides !== 'object' || Array.isArray(raw.overrides)) fail('overrides must be an object.')
+    assertKnownKeys(raw.overrides, new Set(['profile']), 'overrides')
+    if (raw.overrides.profile !== undefined) fail('overrides.profile is not supported; set profile explicitly.')
+  }
   if (!Array.isArray(raw.checks) || raw.checks.length === 0) fail('verification config requires at least one check.')
   const checks = raw.checks.map((check, index) => {
     if (!check || typeof check !== 'object' || Array.isArray(check)) fail(`checks[${index}] must be an object.`)
+    assertKnownKeys(check, new Set(['id', 'category', 'command', 'required', 'timeoutMs', 'execution', 'capabilities']), `checks[${index}]`)
     if (typeof check.id !== 'string' || !check.id) fail(`checks[${index}].id is required.`)
     if (typeof check.command !== 'string' || !check.command) fail(`checks[${index}].command is required.`)
     if (!CATEGORIES.has(check.category)) fail(`checks[${index}].category is invalid.`)
     if (check.required !== undefined && typeof check.required !== 'boolean') fail(`checks[${index}].required must be boolean.`)
     if (check.timeoutMs !== undefined && (!Number.isInteger(check.timeoutMs) || check.timeoutMs < 1)) fail(`checks[${index}].timeoutMs must be a positive integer.`)
     if (['endpoint', 'database', 'cli', 'mcp', 'ui'].includes(check.category) && check.execution !== 'real') fail(`checks[${index}] requires execution: "real".`)
+    if (check.capabilities !== undefined && (!Array.isArray(check.capabilities) || check.capabilities.some((item) => typeof item !== 'string' || !item.trim()))) fail(`checks[${index}].capabilities must contain non-empty strings.`)
+    if (check.category === 'ui') {
+      for (const capability of ['real-browser', 'screenshot']) if (!check.capabilities?.includes(capability)) fail(`checks[${index}] requires capability "${capability}".`)
+    }
     return { required: true, timeoutMs: 120_000, ...check }
   })
+  if (new Set(checks.map((check) => check.id)).size !== checks.length) fail('check ids must be unique.')
+  if (!raw.contract || typeof raw.contract !== 'object' || Array.isArray(raw.contract)) fail('verification contract is required.')
+  assertKnownKeys(raw.contract, new Set(['intent', 'outcomes']), 'contract')
+  if (typeof raw.contract.intent !== 'string' || !raw.contract.intent.trim()) fail('contract.intent is required.')
+  if (!Array.isArray(raw.contract.outcomes) || raw.contract.outcomes.length === 0) fail('contract.outcomes requires at least one outcome.')
+  const checkIds = new Set(checks.map((check) => check.id))
+  const outcomes = raw.contract.outcomes.map((outcome, index) => {
+    if (!outcome || typeof outcome !== 'object' || Array.isArray(outcome)) fail(`contract.outcomes[${index}] must be an object.`)
+    assertKnownKeys(outcome, new Set(['id', 'statement', 'checks']), `contract.outcomes[${index}]`)
+    if (typeof outcome.id !== 'string' || !outcome.id.trim()) fail(`contract.outcomes[${index}].id is required.`)
+    if (typeof outcome.statement !== 'string' || !outcome.statement.trim()) fail(`contract.outcomes[${index}].statement is required.`)
+    if (!Array.isArray(outcome.checks) || outcome.checks.length === 0) fail(`contract.outcomes[${index}].checks requires at least one check id.`)
+    if (outcome.checks.some((checkId) => typeof checkId !== 'string' || !checkIds.has(checkId))) fail(`contract.outcomes[${index}] references an unknown check.`)
+    if (outcome.checks.some((checkId) => !checks.find((check) => check.id === checkId)?.required)) fail(`contract.outcomes[${index}] references a non-required check.`)
+    return { id: outcome.id, statement: outcome.statement, checks: [...new Set(outcome.checks)] }
+  })
+  if (new Set(outcomes.map((outcome) => outcome.id)).size !== outcomes.length) fail('contract outcome ids must be unique.')
+  if (raw.surfaces !== undefined && (!raw.surfaces || typeof raw.surfaces !== 'object' || Array.isArray(raw.surfaces))) fail('surfaces must be an object.')
+  if (raw.surfaces) for (const name of Object.keys(raw.surfaces)) if (!SURFACES.includes(name)) fail(`surfaces.${name} is not supported.`)
   const surfaces = {}
-  for (const name of ['logic', 'endpoint', 'database', 'cli', 'mcp', 'ui', 'docs']) surfaces[name] = surfaceRequired(raw.surfaces?.[name] ?? (name === 'logic'), name)
+  for (const name of SURFACES) {
+    if (policy.requiresAllSurfaces && !Object.hasOwn(raw.surfaces ?? {}, name)) fail(`enterprise profile requires surfaces.${name} to be declared.`)
+    surfaces[name] = surfaceRequired(raw.surfaces?.[name] ?? (name === 'logic'), name)
+  }
   for (const [name, surface] of Object.entries(surfaces)) {
     const matching = checks.some((check) => check.category === name && check.required)
     if (surface.required && !matching) fail(`Required surface "${name}" has no required check.`)
   }
-  if (raw.profile !== 'strict' && (!Array.isArray(raw.exemptions) || raw.exemptions.length === 0)) fail('Non-strict profiles require explicit exemptions.')
+  if (policy.requiresExplicitExemptions && (!Array.isArray(raw.exemptions) || raw.exemptions.length === 0)) fail('This profile requires explicit exemptions.')
   if (raw.exemptions && (!Array.isArray(raw.exemptions) || raw.exemptions.some((item) => typeof item !== 'string' || !item.trim()))) fail('exemptions must be non-empty strings.')
-  const tracking = raw.tracking ?? { required: true, authorization: 'ask' }
+  const measurement = raw.measurement ?? { required: false }
+  if (!measurement || typeof measurement !== 'object' || Array.isArray(measurement)) fail('measurement must be an object.')
+  assertKnownKeys(measurement, new Set(['required', 'checkId', 'baseline']), 'measurement')
+  if (typeof measurement.required !== 'boolean') fail('measurement.required must be boolean.')
+  if (policy.requiresMeasurement && !measurement.required) fail('enterprise profile requires measurement.required to be true.')
+  if (measurement.required) {
+    if (typeof measurement.checkId !== 'string' || !measurement.checkId.trim()) fail('measurement.checkId is required when measurement is required.')
+    const measurementCheck = checks.find((check) => check.id === measurement.checkId)
+    if (!measurementCheck) fail(`measurement.checkId references an unknown check: ${measurement.checkId}.`)
+    if (!measurementCheck.required) fail('measurement.checkId must reference a required check.')
+    if (typeof measurement.baseline !== 'string' || !measurement.baseline.trim()) fail('measurement.baseline is required when measurement is required.')
+  }
+  const tracking = raw.tracking ?? (policy.requiresTracking
+    ? { required: true, authorization: 'ask' }
+    : { required: false, reason: 'tracking is not configured for this run.' })
+  assertKnownKeys(tracking, new Set(['required', 'authorization', 'target', 'reason']), 'tracking')
   if (typeof tracking.required !== 'boolean') fail('tracking.required must be boolean.')
+  if (policy.requiresTracking && !tracking.required) fail('enterprise profile requires tracking.required to be true.')
   if (tracking.required && tracking.authorization !== 'ask') fail('tracking.authorization must be "ask".')
   if (tracking.required && typeof tracking.target !== 'string') fail('tracking.target is required when tracking is required.')
   if (!tracking.required && typeof tracking.reason !== 'string') fail('tracking.reason is required when tracking is not required.')
-  return { ...raw, checks, surfaces, tracking, configPath }
+  if (raw.cleanup !== undefined) {
+    if (!raw.cleanup || typeof raw.cleanup !== 'object' || Array.isArray(raw.cleanup)) fail('cleanup must be an object.')
+    assertKnownKeys(raw.cleanup, new Set(['roots']), 'cleanup')
+    if (raw.cleanup.roots !== undefined && (!Array.isArray(raw.cleanup.roots) || raw.cleanup.roots.some((root) => typeof root !== 'string' || !root.trim()))) fail('cleanup.roots must contain non-empty strings.')
+  }
+  return { ...raw, profile, checks, contract: { intent: raw.contract.intent.trim(), outcomes }, surfaces, tracking, measurement, configPath, profilePolicy: policy }
 }
 
 const sourceRevision = (root) => {
@@ -143,6 +221,53 @@ const commandResult = (root, check) => new Promise((resolveResult) => {
   })
 })
 
+const validateUiEvidence = (root, run) => ({
+  ...run,
+  checks: run.checks.map((check) => {
+    if (check.category !== 'ui' || check.status === 'failed') return check
+    const evidence = check.verification
+    const failures = []
+    if (!evidence || evidence.capability !== 'real-browser') failures.push('UI evidence must declare capability "real-browser"')
+    if (!Array.isArray(evidence?.artifacts) || evidence.artifacts.length === 0) failures.push('UI evidence must include screenshot artifacts')
+    for (const artifact of evidence?.artifacts ?? []) {
+      if (artifact?.type !== 'screenshot' || typeof artifact.path !== 'string' || typeof artifact.sha256 !== 'string' || typeof artifact.viewport !== 'string') {
+        failures.push('Each UI artifact must include type=screenshot, path, sha256, and viewport')
+        continue
+      }
+      const path = resolve(root, artifact.path)
+      if (!inside(root, path) || !existsSync(path)) failures.push(`Screenshot artifact is missing or outside the project: ${artifact.path}`)
+      else if (createHash('sha256').update(readFileSync(path)).digest('hex') !== artifact.sha256) failures.push(`Screenshot hash mismatch: ${artifact.path}`)
+    }
+    const criterionIds = run.contract.outcomes.filter((outcome) => outcome.checks.includes(check.id)).map((outcome) => outcome.id)
+    if (!evidence?.criteria || typeof evidence.criteria !== 'object' || Array.isArray(evidence.criteria)) failures.push('UI evidence must include criterion-level results')
+    for (const id of criterionIds) if (evidence?.criteria?.[id]?.status !== 'passed') failures.push(`UI criterion did not pass: ${id}`)
+    if (!failures.length) return check
+    return { ...check, status: 'failed', verificationStatus: 'failed', verification: { ...(evidence ?? {}), status: 'failed', failures } }
+  }),
+})
+
+const validateMeasurementResult = (run, measurement) => {
+  if (!measurement.required) return run
+  const check = run.checks.find((item) => item.id === measurement.checkId)
+  const verification = check?.verification
+  const failures = []
+  if (check?.status !== 'passed') failures.push(`measurement check ${measurement.checkId} did not pass`)
+  if (!verification || typeof verification.metrics !== 'object' || Array.isArray(verification.metrics)) failures.push('measurement evidence must include an object named metrics')
+  if (typeof verification?.baselineHash !== 'string' || !verification.baselineHash) failures.push('measurement evidence must include baselineHash')
+  if (!Array.isArray(verification?.regressions)) failures.push('measurement evidence must include a regressions array')
+  else if (verification.regressions.length) failures.push(`measurement regressions detected: ${verification.regressions.join('; ')}`)
+  if (!failures.length) return run
+  return {
+    ...run,
+    checks: run.checks.map((item) => item.id === measurement.checkId ? {
+      ...item,
+      status: 'failed',
+      verificationStatus: 'failed',
+      verification: { status: 'failed', failures },
+    } : item),
+  }
+}
+
 const stateDirFor = (root) => join(root, '.codex', 'verification')
 const runDirFor = (root, runId) => join(stateDirFor(root), 'runs', runId)
 const latestPathFor = (root) => join(stateDirFor(root), 'latest.json')
@@ -152,7 +277,23 @@ const saveRun = (root, run) => {
   writeAtomic(join(dir, 'run.json'), run)
   writeAtomic(latestPathFor(root), { runId: run.runId, state: run.state, path: relative(root, join(dir, 'run.json')), updatedAt: now() })
 }
-const transition = (run, state, reason) => ({ ...run, state, transitions: [...run.transitions, { from: run.state, to: state, at: now(), ...(reason ? { reason } : {}) }] })
+const transition = (run, state, reason) => {
+  if (!STATES.has(state)) fail(`Unknown verification state: ${state}.`)
+  const allowed = LEGAL_TRANSITIONS[String(run.state)] ?? []
+  if (!allowed.includes(state)) fail(`Illegal verification transition ${run.state} -> ${state}.`)
+  return { ...run, state, transitions: [...run.transitions, { from: run.state, to: state, at: now(), ...(reason ? { reason } : {}) }] }
+}
+
+const attachEvidence = (run) => {
+  const evidenceReferences = run.checks.map((check) => ({
+    checkId: check.id,
+    status: check.status,
+    ...(check.verificationStatus ? { verificationStatus: check.verificationStatus } : {}),
+    evidenceHash: hash({ id: check.id, status: check.status, stdout: check.stdout, stderr: check.stderr, verification: check.verification }),
+  }))
+  const metrics = Object.fromEntries(run.checks.flatMap((check) => Object.entries(check.verification?.metrics ?? {})))
+  return { ...run, evidenceReferences, metrics, outputHash: hash({ checks: run.checks, outcomes: run.outcomes, evidenceReferences, metrics }) }
+}
 
 const runVerification = async (root, config, runId) => {
   const source = sourceRevision(root)
@@ -173,12 +314,16 @@ const runVerification = async (root, config, runId) => {
     runId: id,
     project: config.project,
     profile: config.profile,
+    profilePolicy: config.profilePolicy,
     sourceRevision: source,
+    contractHash: hash(config.contract),
     inputHash,
     state: 'PLANNED',
     configPath: relative(root, config.configPath),
-    checks: config.checks.map(({ id: checkId, category, command, required, timeoutMs }) => ({ id: checkId, category, command, required, timeoutMs, status: 'pending' })),
+    contract: config.contract,
+    checks: config.checks.map(({ id: checkId, category, command, required, timeoutMs, capabilities }) => ({ id: checkId, category, command, required, timeoutMs, ...(capabilities ? { capabilities } : {}), status: 'pending' })),
     surfaces: config.surfaces,
+    applicability: config.surfaces,
     tracking: config.tracking,
     exemptions: config.exemptions ?? [],
     transitions: [{ from: null, to: 'PLANNED', at: now() }],
@@ -191,8 +336,29 @@ const runVerification = async (root, config, runId) => {
     run = { ...run, checks: run.checks.map((item, itemIndex) => itemIndex === index ? { ...item, ...result } : item) }
     saveRun(root, run)
   }
+  run = validateUiEvidence(root, run)
+  run = {
+    ...run,
+    outcomes: run.contract.outcomes.map((outcome) => {
+      const checks = run.checks.filter((check) => outcome.checks.includes(check.id))
+      const status = checks.some((check) => check.status === 'failed') ? 'failed' : checks.some((check) => check.status === 'awaiting-human-approval') ? 'awaiting-human-approval' : 'passed'
+      return { ...outcome, status }
+    }),
+  }
+  run = validateMeasurementResult(run, config.measurement)
+  run = {
+    ...run,
+    outcomes: run.contract.outcomes.map((outcome) => {
+      const checks = run.checks.filter((check) => outcome.checks.includes(check.id))
+      const status = checks.some((check) => check.status === 'failed') ? 'failed' : checks.some((check) => check.status === 'awaiting-human-approval') ? 'awaiting-human-approval' : 'passed'
+      return { ...outcome, status }
+    }),
+  }
+  run = attachEvidence(run)
+  const failedOutcomes = run.outcomes.filter((outcome) => outcome.status === 'failed')
   const failed = run.checks.filter((check) => check.required && !['passed', 'awaiting-human-approval'].includes(check.status))
   if (failed.length) run = transition(run, 'BLOCKED', `Required checks failed: ${failed.map((check) => check.id).join(', ')}`)
+  else if (failedOutcomes.length) run = transition(run, 'BLOCKED', `Contract outcomes failed: ${failedOutcomes.map((outcome) => outcome.id).join(', ')}`)
   else if (config.surfaces.ui.required) run = transition(run, 'AWAITING_HUMAN_APPROVAL', 'Visual UI approval is required.')
   else if (config.tracking.required) run = transition(run, 'AWAITING_AUTHORIZATION', `Tracking authorization is required for ${config.tracking.target}.`)
   else run = transition(run, 'COMPLETE', 'All configured verification gates passed.')
@@ -211,13 +377,43 @@ const updateApproval = (root, run, type, rawIntent, by) => {
   if (run.state !== expectedState) fail(`Cannot record ${type} while run is ${run.state}.`)
   const approvedIntent = intent(rawIntent)
   const dir = runDirFor(root, run.runId)
-  writeAtomic(join(dir, `${type}.json`), { type, runId: run.runId, runInputHash: run.inputHash, intent: approvedIntent, by: by ?? 'human', at: now() })
+  writeAtomic(join(dir, `${type}.json`), {
+    type,
+    runId: run.runId,
+    runInputHash: run.inputHash,
+    runSourceRevision: run.sourceRevision,
+    runContractHash: run.contractHash,
+    runOutputHash: run.outputHash,
+    intent: approvedIntent,
+    by: by ?? 'human',
+    at: now(),
+  })
+  if (type === 'human-approval') run = { ...run, outcomes: run.outcomes.map((outcome) => outcome.status === 'awaiting-human-approval' ? { ...outcome, status: 'passed' } : outcome) }
   if (type === 'human-approval' && run.state === 'AWAITING_HUMAN_APPROVAL') run = run.tracking.required ? transition(run, 'AWAITING_AUTHORIZATION', `Human approval recorded for ${run.runId}.`) : transition(run, 'COMPLETE', 'Human approval recorded and all gates passed.')
   if (type === 'tracking-authorization' && run.state === 'AWAITING_AUTHORIZATION') run = transition(run, 'COMPLETE', `Tracking authorization recorded for ${run.tracking.target}.`)
   saveRun(root, run)
   return run
 }
 
+const replaceBaseline = (root, config, sourcePath, rawIntent, by) => {
+  if (!config.measurement.required) fail('Baseline replacement requires measurement.required to be true.')
+  if (!config.measurement.baseline) fail('Baseline replacement requires measurement.baseline.')
+  if (!by) fail('Baseline replacement requires --by.')
+  const approvedIntent = intent(rawIntent)
+  const target = resolve(root, config.measurement.baseline)
+  const source = resolve(root, sourcePath ?? '')
+  if (!inside(root, target) || !inside(root, source)) fail('Baseline source and target must be inside the project root.')
+  if (!existsSync(source)) fail(`Baseline source not found: ${sourcePath}`)
+  if (source === target) fail('Baseline source must differ from the configured baseline target.')
+  const value = readJson(source)
+  writeAtomic(target, value)
+  const auditPath = join(stateDirFor(root), 'baseline-audit.jsonl')
+  mkdirSync(dirname(auditPath), { recursive: true })
+  const entry = { action: 'replace-baseline', source: relative(root, source), target: relative(root, target), baselineHash: hash(value), intent: approvedIntent, by, at: now() }
+  appendFileSync(auditPath, `${JSON.stringify(entry)}\n`, 'utf8')
+  return { status: 'baseline-replaced', ...entry }
+}
+
 const clean = (root, config, periodic) => {
   const manifestPath = join(stateDirFor(root), 'owned-artifacts.json')
   if (!existsSync(manifestPath)) return { removed: [], skipped: [], periodic, message: 'No task-owned artifacts are registered.' }
@@ -240,13 +436,19 @@ const main = async (argv) => {
   const { flags, values, positional } = parseArgs(argv)
   const command = positional[0] ?? 'help'
   if (flags.has('help') || command === 'help') {
-    process.stdout.write('ak-verify run|status|approve <run-id> <intent>|authorize <run-id> <intent>|clean [--periodic] [--config <path>] [--json]\n')
+    process.stdout.write('ak-verify run|status|approve <run-id> <intent>|authorize <run-id> <intent>|baseline replace <source> <intent> [--by <actor>]|clean [--periodic] [--config <path>] [--json]\n')
     return 0
   }
   const configPath = resolve(values.get('config') ?? DEFAULT_CONFIG)
   if (!existsSync(configPath)) fail(`Verification contract not found: ${configPath}`)
   const root = projectRoot(configPath, readJson(configPath))
   const config = validateConfig(readJson(configPath), configPath)
+  if (command === 'baseline') {
+    if (positional[1] !== 'replace') fail('Use: baseline replace <source> <intent> --by <actor>.')
+    const result = replaceBaseline(root, config, positional[2], positional[3], values.get('by'))
+    output(result, flags.has('json'))
+    return 0
+  }
   if (command === 'run') {
     const run = await runVerification(root, config, values.get('run-id'))
     output(run, flags.has('json'))
@@ -277,4 +479,4 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   catch (error) { process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 2 }
 }
 
-export { INTENTS, main, validateConfig }
+export { INTENTS, LEGAL_TRANSITIONS, PROFILES, STATES, main, transition, validateConfig }

package/skills/doc-bridge-handoff/scripts/resolve-handoff.mjs

@@ -3,7 +3,7 @@
 import { spawnSync } from 'node:child_process'
 import { isAbsolute } from 'node:path'
 
-const VERSION = '1.6.4'
+const VERSION = '1.7.45'
 const kinds = new Set(['package', 'ownership'])
 const args = process.argv.slice(2)
 const id = args[0]

package/src/agents/registry-adapter.ts

@@ -5,7 +5,7 @@ import { z } from 'zod'
 
 import type { DocBridgeConfigV1 } from '../config/schema.js'
 import { AgentProposalV1Schema, type AgentProposalV1, type DiscoverySnapshotV1, type ReconciliationReportV1 } from '../schemas/knowledge.js'
-import { contentHashForArtifactV1 } from '../index-builder/content-hash.js'
+import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
 import { containedPath, redactValue } from '../safety/repository.js'
 
 export const DEFAULT_REGISTRY_AGENT_ID = 'ecosystem-doc-bridge-corpus-scanner'
@@ -27,6 +27,7 @@ export type RegistryAgentContext = {
   readonly capabilities: readonly ['snapshot.read', 'evidence.read', 'proposal.write']
   readonly network: false
   readonly shell: false
+  readonly deterministic: boolean
 }
 
 export type RegistryAgentRunner = (context: RegistryAgentContext) => Promise<unknown> | unknown
@@ -73,15 +74,38 @@ export const loadRegistryAgentMetadata = (root: string, config: DocBridgeConfigV
 export const createRegistryAgentAdapter = (root: string, config: DocBridgeConfigV1, runner: RegistryAgentRunner): RegistryAgentAdapter => {
   if (!registryConfig(config)?.enabled) throw new Error('Registry agents are disabled. Set intelligence.registry.enabled: true to run an assisted workflow.')
   const metadata = loadRegistryAgentMetadata(resolve(root), config)
+  const settings = registryConfig(config) ?? {}
+  const timeoutMs = settings.timeoutMs ?? 120_000
+  const maxResponseBytes = settings.maxResponseBytes ?? 256_000
+  const maxTokens = settings.maxTokens ?? Math.ceil(maxResponseBytes / 4)
+  const maxConcurrency = settings.maxConcurrency ?? 1
+  let active = 0
+  const deterministicCache = new Map<string, AgentProposalV1>()
   return {
     metadata,
     run: async (snapshot, report, evidence = report.diagnostics.flatMap((diagnostic) => diagnostic.evidence).slice(0, 64)) => {
-      const context = deepFreeze({ snapshot: redactValue(snapshot), report: redactValue(report), evidence: redactValue(evidence), capabilities: ['snapshot.read', 'evidence.read', 'proposal.write'] as const, network: false as const, shell: false as const }) as RegistryAgentContext
-      const proposal = AgentProposalV1Schema.parse(await runner(context))
-      if (proposal.contentHash !== contentHashForArtifactV1(proposal)) throw new Error('Registry agent proposal contentHash does not match its canonical contents.')
-      if (proposal.baseSnapshotHash !== snapshot.contentHash || proposal.baseReportHash !== report.contentHash) throw new Error('Registry agent proposal is not based on the supplied snapshot/report hashes.')
-      if (proposal.origin.kind !== 'registry-agent' || proposal.origin.id !== metadata.id) throw new Error(`Registry agent proposal origin must be ${metadata.id}.`)
-      return proposal
+      if (active >= maxConcurrency) throw new Error(`Registry agent concurrency limit ${maxConcurrency} exceeded.`)
+      const cacheKey = sha256NormalizedV1({ snapshotHash: snapshot.contentHash, reportHash: report.contentHash, agentId: metadata.id, agentVersion: metadata.version, evidence })
+      if (settings.deterministic && deterministicCache.has(cacheKey)) return deterministicCache.get(cacheKey) as AgentProposalV1
+      active += 1
+      let timer: ReturnType<typeof setTimeout> | undefined
+      try {
+        const context = deepFreeze({ snapshot: redactValue(snapshot), report: redactValue(report), evidence: redactValue(evidence), capabilities: ['snapshot.read', 'evidence.read', 'proposal.write'] as const, network: false as const, shell: false as const, deterministic: settings.deterministic ?? true }) as RegistryAgentContext
+        const timeout = new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error(`Registry agent timed out after ${timeoutMs}ms.`)), timeoutMs) })
+        const raw = await Promise.race([Promise.resolve(runner(context)), timeout])
+        const responseBytes = Buffer.byteLength(JSON.stringify(raw))
+        if (responseBytes > maxResponseBytes) throw new Error(`Registry agent response limit ${maxResponseBytes} bytes exceeded.`)
+        if (Math.ceil(responseBytes / 4) > maxTokens) throw new Error(`Registry agent token budget ${maxTokens} exceeded.`)
+        const proposal = AgentProposalV1Schema.parse(raw)
+        if (proposal.contentHash !== contentHashForArtifactV1(proposal)) throw new Error('Registry agent proposal contentHash does not match its canonical contents.')
+        if (proposal.baseSnapshotHash !== snapshot.contentHash || proposal.baseReportHash !== report.contentHash) throw new Error('Registry agent proposal is not based on the supplied snapshot/report hashes.')
+        if (proposal.origin.kind !== 'registry-agent' || proposal.origin.id !== metadata.id) throw new Error(`Registry agent proposal origin must be ${metadata.id}.`)
+        if (settings.deterministic) deterministicCache.set(cacheKey, proposal)
+        return proposal
+      } finally {
+        if (timer) clearTimeout(timer)
+        active -= 1
+      }
     },
   }
 }

package/src/cli/demo.ts

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -140,4 +140,4 @@ export const withDemoWorkspace = (
   } finally {
     rmSync(dir, { recursive: true, force: true })
   }
-}
+}

package/src/cli/program.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
@@ -25,7 +25,7 @@ import { ingestMemoryCandidates } from '../memory/ingest.js'
 import { classifyMemoryCandidates, draftMemoryPromotion } from '../memory/pipeline.js'
 import { promoteMemoryToGithubPr } from '../memory/github-pr.js'
 import { watchDocBridgeIndex } from '../index-builder/watch-index.js'
-import { loadWorkflowManifest, loadWorkflowStepOutput, runWorkflow, type WorkflowExecutionResult } from '../workflow/engine.js'
+import { loadWorkflowStepOutput, runWorkflow, type WorkflowExecutionResult } from '../workflow/engine.js'
 import {
   formatDoctorBadgeJson,
   formatDoctorBadgeMarkdown,
@@ -47,6 +47,7 @@ import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
 import { applyFixProposal, approveFixProposal, createArtifactNormalizationProposal, createMarkdownLinkFixProposal } from '../fixes/proposals.js'
 import { createRegistryAgentAdapter, loadRegistryAgentRunner, persistRegistryAgentProposal } from '../agents/registry-adapter.js'
 import { renderOfflineReportArtifact } from '../report/html.js'
+import { benchmarkFixture, formatBenchmarkText, measureBenchmark } from '../metrics/benchmark.js'
 import { PACKAGE_VERSION } from '../version.js'
 
 type Command =
@@ -60,6 +61,7 @@ type Command =
   | 'playbook'
   | 'registry'
   | 'discover'
+  | 'benchmark'
   | 'scan'
   | 'reconcile'
   | 'check'
@@ -89,6 +91,7 @@ Core (no API key):
   ak-docs doctor [--text] [--badge] [--write-badge]
   ak-docs index [--watch]
   ak-docs discover [--text|--json]
+  ak-docs benchmark <fixture.json> <observation.json> [--text|--json]
   ak-docs scan | reconcile | check | map [--text|--json] [--html] [--report-threshold <bytes>]
   ak-docs fix propose links|normalize <artifact> [--output <file>]
   ak-docs fix approve|apply <proposal.json> [--by <name>]
@@ -163,6 +166,7 @@ const parseArgs = (argv: readonly string[]) => {
   else if (positional[0] === 'playbook') command = 'playbook'
   else if (positional[0] === 'registry') command = 'registry'
   else if (positional[0] === 'discover') command = 'discover'
+  else if (positional[0] === 'benchmark') command = 'benchmark'
   else if (positional[0] === 'scan') command = 'scan'
   else if (positional[0] === 'reconcile') command = 'reconcile'
   else if (positional[0] === 'check') command = 'check'
@@ -463,20 +467,24 @@ const workflowOptions = (
   sourceRevision: string,
   stage: 'collect' | 'normalize' | 'reconcile' | 'evaluate' | 'report',
   handlers: Parameters<typeof runWorkflow>[0]['handlers'],
+  versions?: Pick<Parameters<typeof runWorkflow>[0], 'pipelineVersion' | 'analyzerVersions'>,
 ): Parameters<typeof runWorkflow>[0] => ({
   root,
   ...(config.workflow?.stateDir ? { stateDir: config.workflow.stateDir } : {}),
   sourceRevision,
   configurationHash: sha256NormalizedV1(config),
-  toolVersion: '1.0.1',
+  toolVersion: PACKAGE_VERSION,
+  ...(versions?.pipelineVersion ? { pipelineVersion: versions.pipelineVersion } : {}),
+  ...(versions?.analyzerVersions ? { analyzerVersions: versions.analyzerVersions } : {}),
   stage,
   handlers,
 })
 
 const scanWorkflow = (root: string, config: DocBridgeConfigV1): WorkflowExecutionResult => {
   const discovered = discoverRepository({ root, config })
-  runWorkflow(workflowOptions(root, config, discovered.sourceRevision, 'collect', { collect: () => discovered }))
-  return runWorkflow(workflowOptions(root, config, discovered.sourceRevision, 'normalize', { normalize: ({ input }) => input }))
+  const versions = { pipelineVersion: discovered.pipelineVersion, analyzerVersions: discovered.analyzerVersions }
+  runWorkflow(workflowOptions(root, config, discovered.sourceRevision, 'collect', { collect: () => discovered }, versions))
+  return runWorkflow(workflowOptions(root, config, discovered.sourceRevision, 'normalize', { normalize: ({ input }) => input }, versions))
 }
 
 const documentationInputs = (root: string, snapshot: DiscoverySnapshotV1) => snapshot.entities
@@ -486,18 +494,24 @@ const documentationInputs = (root: string, snapshot: DiscoverySnapshotV1) => sna
 const reconcileWorkflow = (root: string, config: DocBridgeConfigV1): WorkflowExecutionResult => {
   const scanned = scanWorkflow(root, config)
   const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(scanned.stateDir, 'normalize'))
-  const declared = applyDocumentationDeclarations(snapshot, documentationInputs(root, snapshot)).snapshot
-  const report = reconcileKnowledge(snapshot, declared, config.reconciliation?.requiredRelationKinds === undefined
-    ? {}
-    : { requiredRelationKinds: config.reconciliation.requiredRelationKinds })
-  return runWorkflow(workflowOptions(root, config, snapshot.sourceRevision, 'reconcile', { reconcile: () => report }))
+  const declared = applyDocumentationDeclarations(snapshot, documentationInputs(root, snapshot), {
+    agentRoot: config.corpus.agent.root,
+  }).snapshot
+  const report = reconcileKnowledge(snapshot, declared, {
+    ...(config.reconciliation?.scope === undefined ? {} : { scope: config.reconciliation.scope }),
+    ...(config.reconciliation?.requiredRelationKinds === undefined ? {} : { requiredRelationKinds: config.reconciliation.requiredRelationKinds }),
+    ...(config.reconciliation?.requiredRelationTargets === undefined ? {} : { requiredRelationTargets: config.reconciliation.requiredRelationTargets }),
+    ...(config.reconciliation?.includeOrphanedDocuments === undefined ? {} : { includeOrphanedDocuments: config.reconciliation.includeOrphanedDocuments }),
+  })
+  return runWorkflow(workflowOptions(root, config, snapshot.sourceRevision, 'reconcile', { reconcile: () => report }, { pipelineVersion: snapshot.pipelineVersion, analyzerVersions: snapshot.analyzerVersions }))
 }
 
 const checkWorkflow = (root: string, config: DocBridgeConfigV1): WorkflowExecutionResult => {
   const reconciled = reconcileWorkflow(root, config)
   const report = parseReconciliationReport(loadWorkflowStepOutput(reconciled.stateDir, 'reconcile'))
-  const evaluated = runWorkflow(workflowOptions(root, config, report.sourceRevision, 'evaluate', { evaluate: () => evaluateRules(report, { ...(config.rules ? { config: config.rules } : {}) }) }))
-  return runWorkflow(workflowOptions(root, config, report.sourceRevision, 'report', { report: ({ input }) => input }))
+  const versions = { pipelineVersion: report.pipelineVersion, analyzerVersions: report.analyzerVersions }
+  runWorkflow(workflowOptions(root, config, report.sourceRevision, 'evaluate', { evaluate: () => evaluateRules(report, { ...(config.rules ? { config: config.rules } : {}) }) }, versions))
+  return runWorkflow(workflowOptions(root, config, report.sourceRevision, 'report', { report: ({ input }) => input }, versions))
 }
 
 const workflowOutput = (result: WorkflowExecutionResult): Record<string, unknown> => {
@@ -593,7 +607,7 @@ const runWorkflowCommand = (
       const thresholdValue = optionValues(argv, '--report-threshold')[0]
       const thresholdBytes = thresholdValue === undefined ? undefined : Number(thresholdValue)
       if (thresholdBytes !== undefined && (!Number.isSafeInteger(thresholdBytes) || thresholdBytes < 1)) throw new Error('--report-threshold must be a positive integer.')
-      const artifact = renderOfflineReportArtifact({ snapshot, report }, { ...(thresholdBytes === undefined ? {} : { thresholdBytes }) })
+      const artifact = renderOfflineReportArtifact({ snapshot, report }, { ...(config.report?.privacy ? { privacy: config.report.privacy } : {}), ...(thresholdBytes === undefined ? {} : { thresholdBytes }) })
       output.htmlPath = writeReportArtifact(htmlPath, artifact)
       output.htmlMode = artifact.mode
     }
@@ -707,10 +721,19 @@ const runSuggestCommand = async (flags: ReadonlySet<string>, configPath: string
 }
 
 const writeIfMissing = (path: string, contents: string): boolean => {
-  if (existsSync(path)) return false
   mkdirSync(dirname(path), { recursive: true })
-  writeFileSync(path, contents, 'utf8')
-  return true
+  try {
+    const fd = openSync(path, 'wx')
+    try {
+      writeFileSync(fd, contents, 'utf8')
+      return true
+    } finally {
+      closeSync(fd)
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false
+    throw error
+  }
 }
 
 const demoOwnership = {
@@ -947,6 +970,26 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
   }
 
+  if (command === 'benchmark') {
+    const fixturePath = positional[1]
+    const observationPath = positional[2]
+    if (!fixturePath || !observationPath) {
+      process.stderr.write('Usage: ak-docs benchmark <fixture.json> <observation.json> [--text|--json]\n')
+      return 1
+    }
+    try {
+      const fixture = benchmarkFixture(JSON.parse(readFileSync(resolve(fixturePath), 'utf8')) as unknown)
+      const observation = JSON.parse(readFileSync(resolve(observationPath), 'utf8')) as Parameters<typeof measureBenchmark>[0]
+      const result = measureBenchmark(observation, fixture)
+      if (flags.has('--text')) writeLines([formatBenchmarkText(result)])
+      else writeJson(result)
+      return result.regressions.length ? 1 : 0
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+      return 2
+    }
+  }
+
   if (command === 'scan' || command === 'reconcile' || command === 'check' || command === 'map') {
     return runWorkflowCommand(command, flags, configPath, argv)
   }

package/src/config/index.ts

@@ -15,9 +15,11 @@ export {
   DocumentationStandardV1ConfigSchema,
   EcosystemContractEvidenceSchema,
   ConformanceConfigSchema,
+  ReportConfigSchema,
   type DocBridgeConfigV1,
   type AgentCorpusConfig,
   type DocumentationStandardRuleId,
   type DocumentationStandardV1Config,
   type ReconciliationConfig,
+  type ReportConfig,
 } from './schema.js'

package/src/config/load-config.ts

@@ -79,7 +79,13 @@ const parseConfig = (input: unknown): DocBridgeConfigV1 => {
   if (result.success) return result.data
   throw new Error(
     `Invalid doc-bridge config:\n${result.error.issues.map((issue) =>
-      `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`,
+      `  - ${issue.path.join('.') || '(root)'}: ${
+        issue.code === 'invalid_type' && issue.message.endsWith('received undefined')
+          ? 'Required'
+          : issue.code === 'invalid_value' && 'values' in issue
+            ? 'Invalid enum value'
+            : issue.message
+      }`,
     ).join('\n')}`,
   )
 }