@agentskit/doc-bridge 1.6.2 → 1.6.4

package/scripts/verification-harness.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+import { execFileSync, spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  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 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 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 writeAtomic = (path, value) => {
+  mkdirSync(dirname(path), { recursive: true })
+  const temp = `${path}.tmp-${process.pid}`
+  writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+  renameSync(temp, path)
+}
+
+const parseArgs = (argv) => {
+  const flags = new Set()
+  const values = new Map()
+  const positional = []
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--config' || arg === '--run-id' || arg === '--by') {
+      const value = argv[++i]
+      if (!value) fail(`${arg} requires a value.`)
+      values.set(arg.slice(2), value)
+    } else if (arg?.startsWith('--')) flags.add(arg.slice(2))
+    else if (arg) positional.push(arg)
+  }
+  return { flags, values, positional }
+}
+
+const projectRoot = (configPath, raw) => resolve(dirname(resolve(configPath)), raw.root ?? '.')
+const inside = (root, path) => {
+  const rel = relative(root, path)
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep))
+}
+
+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 }.`)
+  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 } : {}) }
+}
+
+const validateConfig = (raw, configPath) => {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail(`Invalid verification config: ${configPath}`)
+  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(', ')}.`)
+  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.`)
+    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".`)
+    return { required: true, timeoutMs: 120_000, ...check }
+  })
+  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, 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 (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' }
+  if (typeof tracking.required !== 'boolean') fail('tracking.required must be boolean.')
+  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 }
+}
+
+const sourceRevision = (root) => {
+  try {
+    const gitOptions = { cwd: root, encoding: 'utf8', maxBuffer: 20 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }
+    const head = execFileSync('git', ['rev-parse', 'HEAD'], gitOptions).trim()
+    const diff = execFileSync('git', ['diff', '--no-ext-diff', '--binary', 'HEAD'], gitOptions)
+    const status = execFileSync('git', ['status', '--porcelain=v1', '--untracked-files=all'], gitOptions)
+    const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], gitOptions)
+      .split('\0').filter(Boolean).map((path) => ({ path, contentHash: hash(readFileSync(resolve(root, path), 'utf8')) }))
+    return hash({ head, diff, status, untracked })
+  } catch {
+    return hash({ files: readdirSync(root).sort() })
+  }
+}
+
+const machineStatusFrom = (stdout) => {
+  const lines = String(stdout ?? '').trim().split('\n').reverse()
+  for (const line of lines) {
+    try {
+      const value = JSON.parse(line)
+      if (value && ['failed', 'passed', 'pending-human-review'].includes(value.status)) return value
+    } catch {}
+  }
+  return undefined
+}
+
+const commandResult = (root, check) => new Promise((resolveResult) => {
+  const started = Date.now()
+  const child = spawn(check.command, { cwd: root, shell: true, env: { ...process.env, CI: process.env.CI ?? '1' } })
+  let stdout = ''
+  let stderr = ''
+  const append = (current, chunk) => `${current}${chunk.toString()}`.slice(-12_000)
+  child.stdout.on('data', (chunk) => { stdout = append(stdout, chunk) })
+  child.stderr.on('data', (chunk) => { stderr = append(stderr, chunk) })
+  const timer = setTimeout(() => child.kill('SIGTERM'), check.timeoutMs)
+  child.on('error', (error) => resolveResult({ status: 'failed', exitCode: null, durationMs: Date.now() - started, stdout, stderr: `${stderr}${error.message}`.slice(-12_000) }))
+  child.on('close', (exitCode, signal) => {
+    clearTimeout(timer)
+    const machineResult = machineStatusFrom(stdout)
+    const status = exitCode !== 0 || machineResult?.status === 'failed'
+      ? 'failed'
+      : machineResult?.status === 'pending-human-review'
+        ? 'awaiting-human-approval'
+        : 'passed'
+    resolveResult({ status, exitCode, signal, durationMs: Date.now() - started, stdout, stderr, ...(machineResult ? { verificationStatus: machineResult.status, verification: machineResult } : {}) })
+  })
+})
+
+const stateDirFor = (root) => join(root, '.codex', 'verification')
+const runDirFor = (root, runId) => join(stateDirFor(root), 'runs', runId)
+const latestPathFor = (root) => join(stateDirFor(root), 'latest.json')
+const loadLatest = (root) => existsSync(latestPathFor(root)) ? readJson(latestPathFor(root)) : undefined
+const saveRun = (root, run) => {
+  const dir = runDirFor(root, run.runId)
+  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 runVerification = async (root, config, runId) => {
+  const source = sourceRevision(root)
+  const inputHash = hash({ source, config: hash(config), version: VERSION })
+  const previous = loadLatest(root)
+  if (previous?.runId) {
+    const previousRunPath = join(root, previous.path)
+    if (existsSync(previousRunPath)) {
+      const previousRun = readJson(previousRunPath)
+      if (previousRun.inputHash === inputHash && ['AWAITING_HUMAN_APPROVAL', 'AWAITING_AUTHORIZATION', 'COMPLETE'].includes(previousRun.state)) return previousRun
+    }
+  }
+  const id = runId ?? `${Date.now()}-${process.pid}`
+  let run = {
+    schemaVersion: 1,
+    type: 'verification-run',
+    harnessVersion: VERSION,
+    runId: id,
+    project: config.project,
+    profile: config.profile,
+    sourceRevision: source,
+    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' })),
+    surfaces: config.surfaces,
+    tracking: config.tracking,
+    exemptions: config.exemptions ?? [],
+    transitions: [{ from: null, to: 'PLANNED', at: now() }],
+  }
+  saveRun(root, run)
+  run = transition(run, 'VERIFYING')
+  saveRun(root, run)
+  for (const [index, check] of config.checks.entries()) {
+    const result = await commandResult(root, check)
+    run = { ...run, checks: run.checks.map((item, itemIndex) => itemIndex === index ? { ...item, ...result } : item) }
+    saveRun(root, run)
+  }
+  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 (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.')
+  saveRun(root, run)
+  return run
+}
+
+const intent = (value) => {
+  const normalized = String(value ?? '').trim().toLowerCase()
+  if (!INTENTS.has(normalized)) fail(`Invalid human intent "${value}". Use an explicit approval word: ok, aprovado, approved, confirmo.`)
+  return normalized
+}
+
+const updateApproval = (root, run, type, rawIntent, by) => {
+  const expectedState = type === 'human-approval' ? 'AWAITING_HUMAN_APPROVAL' : 'AWAITING_AUTHORIZATION'
+  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() })
+  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 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.' }
+  const manifest = readJson(manifestPath)
+  if (!Array.isArray(manifest)) fail('owned-artifacts.json must contain an array.')
+  const removed = []
+  const skipped = []
+  for (const entry of manifest) {
+    const path = resolve(root, entry.path)
+    const allowedRoots = (config.cleanup?.roots ?? ['.codex/verification/tmp']).map((item) => resolve(root, item))
+    if (!entry.taskOwned || !inside(root, path) || !allowedRoots.some((allowed) => inside(allowed, path))) { skipped.push({ path: entry.path, reason: 'not task-owned or outside cleanup roots' }); continue }
+    if (existsSync(path)) { rmSync(path, { recursive: true, force: true }); removed.push(entry.path) }
+  }
+  return { removed, skipped, periodic }
+}
+
+const output = (value, json) => process.stdout.write(json ? `${JSON.stringify(value, null, 2)}\n` : `Run: ${value.runId ?? '-'}\nState: ${value.state ?? value.status ?? '-'}\n${value.reason ? `Reason: ${value.reason}\n` : ''}`)
+
+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')
+    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 === 'run') {
+    const run = await runVerification(root, config, values.get('run-id'))
+    output(run, flags.has('json'))
+    return ['COMPLETE', 'AWAITING_HUMAN_APPROVAL', 'AWAITING_AUTHORIZATION'].includes(run.state) ? 0 : 1
+  }
+  if (command === 'status') {
+    const latest = loadLatest(root)
+    if (!latest) fail('No verification run exists.')
+    const run = readJson(join(root, latest.path))
+    output(run, flags.has('json'))
+    return run.state === 'COMPLETE' ? 0 : 1
+  }
+  if (command === 'clean') { output(clean(root, config, flags.has('periodic')), flags.has('json')); return 0 }
+  const latest = loadLatest(root)
+  if (!latest) fail('No verification run exists.')
+  let run = readJson(join(root, latest.path))
+  const targetRunId = positional[1]
+  if (targetRunId !== run.runId) fail(`Run id mismatch. Latest run is ${run.runId}.`)
+  if (command === 'approve') run = updateApproval(root, run, 'human-approval', positional[2], values.get('by'))
+  else if (command === 'authorize') run = updateApproval(root, run, 'tracking-authorization', positional[2], values.get('by'))
+  else fail(`Unknown command "${command}".`)
+  output(run, flags.has('json'))
+  return run.state === 'COMPLETE' ? 0 : 1
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try { process.exitCode = await main(process.argv.slice(2)) }
+  catch (error) { process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 2 }
+}
+
+export { INTENTS, main, 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.2'
+const VERSION = '1.6.4'
 const kinds = new Set(['package', 'ownership'])
 const args = process.argv.slice(2)
 const id = args[0]

package/src/cli/program.ts

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
 import { ConfigNotFoundError, loadConfig, projectRootFromConfigPath } from '../config/load-config.js'
@@ -46,7 +46,7 @@ import type { DiscoverySnapshotV1, ReconciliationReportV1 } from '../schemas/kno
 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 { renderOfflineReport } from '../report/html.js'
+import { renderOfflineReportArtifact } from '../report/html.js'
 import { PACKAGE_VERSION } from '../version.js'
 
 type Command =
@@ -89,7 +89,7 @@ Core (no API key):
   ak-docs doctor [--text] [--badge] [--write-badge]
   ak-docs index [--watch]
   ak-docs discover [--text|--json]
-  ak-docs scan | reconcile | check | map [--text|--json] [--html]
+  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>]
   ak-docs suggest [--json|--text]   run the configured local Registry agent
@@ -468,6 +468,7 @@ const workflowOptions = (
   ...(config.workflow?.stateDir ? { stateDir: config.workflow.stateDir } : {}),
   sourceRevision,
   configurationHash: sha256NormalizedV1(config),
+  toolVersion: '1.0.1',
   stage,
   handlers,
 })
@@ -486,7 +487,9 @@ const reconcileWorkflow = (root: string, config: DocBridgeConfigV1): WorkflowExe
   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)
+  const report = reconcileKnowledge(snapshot, declared, config.reconciliation?.requiredRelationKinds === undefined
+    ? {}
+    : { requiredRelationKinds: config.reconciliation.requiredRelationKinds })
   return runWorkflow(workflowOptions(root, config, snapshot.sourceRevision, 'reconcile', { reconcile: () => report }))
 }
 
@@ -520,6 +523,56 @@ const workflowOutput = (result: WorkflowExecutionResult): Record<string, unknown
   }
 }
 
+const writeAtomicFile = (path: string, content: string): void => {
+  const temporaryPath = `${path}.tmp-${process.pid}`
+  writeFileSync(temporaryPath, content, 'utf8')
+  renameSync(temporaryPath, path)
+}
+
+const writeReportArtifact = (htmlPath: string, artifact: ReturnType<typeof renderOfflineReportArtifact>): string => {
+  mkdirSync(dirname(htmlPath), { recursive: true })
+  if (artifact.mode === 'single-file') {
+    writeAtomicFile(htmlPath, artifact.indexHtml)
+    const artifactDir = htmlPath.replace(/\.html?$/i, '')
+    if (existsSync(artifactDir)) rmSync(artifactDir, { recursive: true, force: true })
+    return htmlPath
+  }
+
+  const artifactDir = htmlPath.replace(/\.html?$/i, '')
+  const temporaryDir = `${artifactDir}.tmp-${process.pid}`
+  const backupDir = `${artifactDir}.previous-${process.pid}`
+  const launcherTemp = `${htmlPath}.tmp-${process.pid}`
+  rmSync(temporaryDir, { recursive: true, force: true })
+  rmSync(backupDir, { recursive: true, force: true })
+  mkdirSync(temporaryDir, { recursive: true })
+  for (const [file, content] of Object.entries(artifact.files)) {
+    const filePath = resolve(temporaryDir, file)
+    mkdirSync(dirname(filePath), { recursive: true })
+    writeFileSync(filePath, content, 'utf8')
+  }
+  writeFileSync(resolve(temporaryDir, 'manifest.json'), artifact.manifest, 'utf8')
+  const frameSource = `${relative(dirname(htmlPath), artifactDir)}/index.html`
+  const launcher = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Doc Bridge report</title></head><body style="margin:0"><iframe title="Doc Bridge report" src="${frameSource}" style="border:0;width:100vw;height:100vh"></iframe></body></html>`
+  writeFileSync(launcherTemp, launcher, 'utf8')
+  try {
+    if (existsSync(artifactDir)) renameSync(artifactDir, backupDir)
+    renameSync(temporaryDir, artifactDir)
+    renameSync(launcherTemp, htmlPath)
+    if (existsSync(backupDir)) rmSync(backupDir, { recursive: true, force: true })
+  } catch (error) {
+    if (existsSync(backupDir)) {
+      const failedDir = `${artifactDir}.failed-${process.pid}`
+      if (existsSync(artifactDir)) renameSync(artifactDir, failedDir)
+      renameSync(backupDir, artifactDir)
+      if (existsSync(failedDir)) rmSync(failedDir, { recursive: true, force: true })
+    } else if (existsSync(artifactDir)) rmSync(artifactDir, { recursive: true, force: true })
+    if (existsSync(temporaryDir)) rmSync(temporaryDir, { recursive: true, force: true })
+    if (existsSync(launcherTemp)) rmSync(launcherTemp, { force: true })
+    throw error
+  }
+  return artifactDir
+}
+
 const runWorkflowCommand = (
   command: 'scan' | 'reconcile' | 'check' | 'map',
   flags: ReadonlySet<string>,
@@ -537,8 +590,12 @@ const runWorkflowCommand = (
       const outputPath = optionValues(argv, '--output')[0] ?? '.doc-bridge/report.html'
       const htmlPath = resolve(root, outputPath)
       mkdirSync(dirname(htmlPath), { recursive: true })
-      writeFileSync(htmlPath, renderOfflineReport({ snapshot, report }), 'utf8')
-      output.htmlPath = htmlPath
+      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 }) })
+      output.htmlPath = writeReportArtifact(htmlPath, artifact)
+      output.htmlMode = artifact.mode
     }
     if (wantsTextOutput(flags, config)) {
       writeLines([`Run: ${String(output.runId)}`, `State: ${String(output.state)}`, ...(output.snapshotHash ? [`Snapshot: ${String(output.snapshotHash)}`] : []), ...(output.reportHash ? [`Report: ${String(output.reportHash)}`] : []), `Artifacts: ${String((output.artifactRefs as unknown[]).length)}`])

package/src/config/index.ts

@@ -8,6 +8,7 @@ export {
 } from './load-config.js'
 export {
   DocBridgeConfigV1Schema,
+  ReconciliationConfigSchema,
   AgentCorpusConfigSchema,
   HumanCorpusConfigSchema,
   DocumentationStandardRuleIdSchema,
@@ -18,4 +19,5 @@ export {
   type AgentCorpusConfig,
   type DocumentationStandardRuleId,
   type DocumentationStandardV1Config,
+  type ReconciliationConfig,
 } from './schema.js'

package/src/config/schema.ts

@@ -179,6 +179,13 @@ export const RulesConfigSchema = z
   })
   .strict()
 
+export const ReconciliationConfigSchema = z
+  .object({
+    /** Relation kinds that must have documentation declarations. Omit to require all observed kinds; [] disables this signal. */
+    requiredRelationKinds: z.array(z.string().min(1).max(128)).max(128).optional(),
+  })
+  .strict()
+
 export const WorkflowConfigSchema = z
   .object({
     stateDir: z.string().min(1).max(512).optional(),
@@ -434,6 +441,7 @@ export const DocBridgeConfigV1Schema = z
     index: IndexConfigSchema.optional(),
     routing: RoutingConfigSchema.optional(),
     gates: GatesConfigSchema.optional(),
+    reconciliation: ReconciliationConfigSchema.optional(),
     rules: RulesConfigSchema.optional(),
     workflow: WorkflowConfigSchema.optional(),
     safety: RepositorySafetyConfigSchema.optional(),
@@ -449,6 +457,7 @@ export type AgentCorpusConfig = z.infer<typeof AgentCorpusConfigSchema>
 export type HumanCorpusConfig = z.infer<typeof HumanCorpusConfigSchema>
 export type DocumentationStandardV1Config = z.infer<typeof DocumentationStandardV1ConfigSchema>
 export type DocumentationStandardRuleId = z.infer<typeof DocumentationStandardRuleIdSchema>
+export type ReconciliationConfig = z.infer<typeof ReconciliationConfigSchema>
 export type RuleId = z.infer<typeof RuleIdSchema>
 export type RuleSeverity = z.infer<typeof RuleSeveritySchema>
 export type RulesConfig = z.infer<typeof RulesConfigSchema>

package/src/index.ts

@@ -93,7 +93,14 @@ export {
   type DocumentationDiagnostic,
 } from './discovery/documentation.js'
 export { reconcileKnowledge } from './reconciliation/reconcile.js'
-export { renderOfflineReport, type OfflineReportInput, type OfflineReportOptions } from './report/html.js'
+export {
+  DEFAULT_LARGE_REPORT_THRESHOLD_BYTES,
+  renderOfflineReport,
+  renderOfflineReportArtifact,
+  type OfflineReportArtifact,
+  type OfflineReportInput,
+  type OfflineReportOptions,
+} from './report/html.js'
 export {
   applyFixProposal,
   approveFixProposal,

package/src/lib/markdown.ts

@@ -82,6 +82,11 @@ export const firstParagraph = (markdown: string, maxLen = 400): string | undefin
       if (buf.length) break
       continue
     }
+    // Navigation-only links are useful in the document, but not as its summary.
+    if (/^(?:!?)\[[^\]]*\]\([^)]*\)$/.test(t)) {
+      if (buf.length) break
+      continue
+    }
     buf.push(t)
     if (buf.join(' ').length >= maxLen) break
   }

package/src/reconciliation/reconcile.ts

@@ -10,6 +10,11 @@ import {
 
 type EntityResolver = (reference: string) => string
 
+export type ReconciliationOptions = {
+  /** Omit for backwards-compatible all-relation checking; [] disables missing-declaration findings. */
+  readonly requiredRelationKinds?: readonly string[]
+}
+
 const ignoredDocumentationRelations = new Set(['covers'])
 
 const metadataDetection = (relation: KnowledgeRelation): string | undefined => {
@@ -97,11 +102,13 @@ const reportDiagnostic = (
 export const reconcileKnowledge = (
   observed: DiscoverySnapshotV1,
   declared: DiscoverySnapshotV1,
+  options: ReconciliationOptions = {},
 ): ReconciliationReportV1 => {
   const resolveEntity = entityResolver([observed, declared])
   const entities = entityById([observed, declared])
   const observedRelations = observed.relations.filter((relation) => relation.provenance === 'observed' && !ignoredDocumentationRelations.has(relation.kind))
   const declaredRelations = declared.relations.filter((relation) => relation.provenance === 'declared' && !ignoredDocumentationRelations.has(relation.kind))
+  const requiredRelationKinds = options.requiredRelationKinds === undefined ? undefined : new Set(options.requiredRelationKinds)
   const diagnostics: ReconciliationReportV1['diagnostics'][number][] = []
 
   for (const entity of declared.entities.filter((item) => isUnresolved(item.id, entities)).sort((a, b) => a.id.localeCompare(b.id))) {
@@ -156,7 +163,7 @@ export const reconcileKnowledge = (
         undefined,
         [relation.id, match.id],
       ))
-    } else if (coverageAvailable(observed, relation)) {
+    } else if (coverageAvailable(observed, relation) && (requiredRelationKinds === undefined || requiredRelationKinds.has(relation.kind))) {
       diagnostics.push(reportDiagnostic(
         'RELATION_UNDOCUMENTED',
         'undocumented',
@@ -221,6 +228,7 @@ export const reconcileKnowledge = (
       entityCount: observed.entities.length,
       relationCount: observedRelations.length,
       diagnosticCount: sortedDiagnostics.length,
+      ...(options.requiredRelationKinds === undefined ? {} : { requiredRelationKinds: [...new Set(options.requiredRelationKinds)].sort() }),
     },
   }
   return ReconciliationReportV1Schema.parse({ ...base, contentHash: contentHashForArtifactV1(base) })