@agentskit/doc-bridge 1.4.1 → 1.5.0

package/src/cli/program.ts

@@ -2,18 +2,21 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { createInterface } from 'node:readline/promises'
 
-import { loadConfig, projectRootFromConfigPath } from '../config/load-config.js'
-import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { ConfigNotFoundError, loadConfig, projectRootFromConfigPath } from '../config/load-config.js'
+import type { DocBridgeConfigV1, RuleId, RuleSeverity } from '../config/schema.js'
 import {
   DOCUMENTATION_STANDARD_V1_ID,
   formatDocumentationStandardText,
   runDocumentationStandardV1,
 } from '../conformance/documentation-standard-v1.js'
 import { buildDocBridgeIndex } from '../index-builder/build-index.js'
+import { applyDocumentationDeclarations } from '../discovery/documentation.js'
+import { discoverRepository } from '../discovery/repository.js'
 import { discoverPnpmPackages } from '../index-builder/plugins/pnpm-monorepo.js'
 import { scanHumanDocRecords } from '../index-builder/human-adapters/index.js'
 import { retrieveHybridChunks } from '../federation/llms.js'
 import { runGates, type GateId } from '../gates/run-gates.js'
+import { evaluateRules, parseRuleId, parseRuleSeverity, type RuleMode } from '../rules/engine.js'
 import { runChatOnce, startInkChat } from '../intelligence/chat.js'
 import { PeerMissingError, layer1InstallHint } from '../intelligence/peers.js'
 import { createDocBridgeRag } from '../intelligence/rag.js'
@@ -22,6 +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 {
   formatDoctorBadgeJson,
   formatDoctorBadgeMarkdown,
@@ -35,7 +39,14 @@ import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
 import { runQuery, type QueryKind } from '../query/query.js'
 import { searchIndex } from '../query/search.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
-import { parseAgentHandoff, parseDocBridgeConfig } from '../validate.js'
+import { parseAgentHandoff, parseDocBridgeConfig, parseReconciliationReport } from '../validate.js'
+import { parseDiscoverySnapshot } from '../validate.js'
+import { reconcileKnowledge } from '../reconciliation/reconcile.js'
+import type { DiscoverySnapshotV1, ReconciliationReportV1 } from '../schemas/knowledge.js'
+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 { PACKAGE_VERSION } from '../version.js'
 
 type Command =
@@ -48,8 +59,16 @@ type Command =
   | 'memory'
   | 'playbook'
   | 'registry'
+  | 'discover'
+  | 'scan'
+  | 'reconcile'
+  | 'check'
+  | 'map'
+  | 'fix'
+  | 'suggest'
   | 'index'
   | 'gate'
+  | 'rules'
   | 'mcp'
   | 'doctor'
   | 'demo'
@@ -69,11 +88,17 @@ Core (no API key):
   ak-docs demo [--fixture example|monorepo] [--text] [--in-project]
   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 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
   ak-docs query [package|ownership|intent|change] <id> [--agent] [--text]
   ak-docs search <term> [--agent] [--text]
   ak-docs list <packages|intents|changes|knowledge> [--text]
   ak-docs ask [question]          local consult (no LLM)
   ak-docs gate run [gate-id]
+  ak-docs rules run <report.json> [--preset default|recommended|strict] [--severity rule=level] [--ignore rule]
   ak-docs conformance run documentation-standard-v1 [--text|--json]
   ak-docs mcp
   ak-docs mcp install --cursor | --claude
@@ -137,8 +162,16 @@ const parseArgs = (argv: readonly string[]) => {
   else if (positional[0] === 'memory') command = 'memory'
   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] === 'scan') command = 'scan'
+  else if (positional[0] === 'reconcile') command = 'reconcile'
+  else if (positional[0] === 'check') command = 'check'
+  else if (positional[0] === 'map') command = 'map'
+  else if (positional[0] === 'fix') command = 'fix'
+  else if (positional[0] === 'suggest') command = 'suggest'
   else if (positional[0] === 'index') command = 'index'
   else if (positional[0] === 'gate') command = 'gate'
+  else if (positional[0] === 'rules') command = 'rules'
   else if (positional[0] === 'mcp') command = 'mcp'
   else if (positional[0] === 'doctor') command = 'doctor'
   else if (positional[0] === 'demo') command = 'demo'
@@ -154,6 +187,30 @@ const parseArgs = (argv: readonly string[]) => {
   return { command, flags, configPath, positional }
 }
 
+const optionValues = (argv: readonly string[], name: string): string[] => {
+  const values: string[] = []
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg?.startsWith(`${name}=`)) values.push(arg.slice(name.length + 1))
+    else if (arg === name && argv[index + 1] && !argv[index + 1]?.startsWith('-')) {
+      values.push(argv[index + 1] as string)
+      index += 1
+    }
+  }
+  return values
+}
+
+const parseRuleAssignments = <T>(values: readonly string[], parseValue: (value: string) => T): Record<string, T> => {
+  const result: Record<string, T> = {}
+  for (const value of values) {
+    const separator = value.indexOf('=')
+    if (separator <= 0 || separator === value.length - 1) throw new Error(`Invalid rule assignment "${value}". Use rule=value.`)
+    const key = value.slice(0, separator)
+    result[key] = parseValue(value.slice(separator + 1))
+  }
+  return result
+}
+
 const writeJson = (payload: unknown): void => {
   process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`)
 }
@@ -400,6 +457,198 @@ const diagnosticNextCommands = (
   ]
 }
 
+const workflowOptions = (
+  root: string,
+  config: DocBridgeConfigV1,
+  sourceRevision: string,
+  stage: 'collect' | 'normalize' | 'reconcile' | 'evaluate' | 'report',
+  handlers: Parameters<typeof runWorkflow>[0]['handlers'],
+): Parameters<typeof runWorkflow>[0] => ({
+  root,
+  ...(config.workflow?.stateDir ? { stateDir: config.workflow.stateDir } : {}),
+  sourceRevision,
+  configurationHash: sha256NormalizedV1(config),
+  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 documentationInputs = (root: string, snapshot: DiscoverySnapshotV1) => snapshot.entities
+  .filter((entity) => entity.kind === 'document' && entity.path)
+  .map((entity) => ({ path: entity.path as string, content: readFileSync(resolve(root, entity.path as string), 'utf8') }))
+
+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)
+  return runWorkflow(workflowOptions(root, config, snapshot.sourceRevision, 'reconcile', { reconcile: () => report }))
+}
+
+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 workflowOutput = (result: WorkflowExecutionResult): Record<string, unknown> => {
+  const snapshot = (() => { try { return parseDiscoverySnapshot(loadWorkflowStepOutput(result.stateDir, 'normalize')) } catch { return undefined } })()
+  const report = (() => { try { return parseReconciliationReport(loadWorkflowStepOutput(result.stateDir, 'reconcile')) } catch { return undefined } })()
+  const rules = (() => {
+    try {
+      const value = loadWorkflowStepOutput(result.stateDir, 'evaluate')
+      return value && typeof value === 'object' ? value : undefined
+    } catch { return undefined }
+  })()
+  return {
+    ok: result.run.state !== 'failed' && result.run.state !== 'stale',
+    runId: result.run.runId,
+    state: result.run.state,
+    stateDir: result.stateDir,
+    artifactRefs: result.run.artifactRefs,
+    steps: result.run.steps,
+    reusedStages: result.reusedStages,
+    ...(snapshot ? { snapshotHash: snapshot.contentHash, sourceRevision: snapshot.sourceRevision, configurationHash: snapshot.configurationHash, coverage: snapshot.coverage } : {}),
+    ...(report ? { reportHash: report.contentHash, diagnostics: report.diagnostics } : {}),
+    ...(rules ? { rules } : {}),
+  }
+}
+
+const runWorkflowCommand = (
+  command: 'scan' | 'reconcile' | 'check' | 'map',
+  flags: ReadonlySet<string>,
+  configPath: string | undefined,
+  argv: readonly string[],
+): number => {
+  try {
+    const { config, root } = loadProject(configPath)
+    const result = command === 'scan' ? scanWorkflow(root, config) : command === 'reconcile' ? reconcileWorkflow(root, config) : checkWorkflow(root, config)
+    const output = workflowOutput(result)
+    if (command === 'map') output.kind = 'architecture-map'
+    if (command === 'map' && flags.has('--html')) {
+      const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(result.stateDir, 'normalize'))
+      const report = parseReconciliationReport(loadWorkflowStepOutput(result.stateDir, 'reconcile'))
+      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
+    }
+    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)}`])
+    } else writeJson(output)
+    const ruleExitCode = output.rules && typeof output.rules === 'object' && 'exitCode' in output.rules && (output.rules as { exitCode?: unknown }).exitCode === 1 ? 1 : 0
+    return result.run.state === 'failed' ? 1 : ruleExitCode
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
+const runRulesCommand = (
+  argv: readonly string[],
+  flags: ReadonlySet<string>,
+  positional: readonly string[],
+  configPath: string | undefined,
+): number => {
+  const action = positional[1]
+  const reportPath = positional[2]
+  if (action !== 'run' || !reportPath) {
+    process.stderr.write('Usage: ak-docs rules run <report.json> [--preset default|recommended|strict] [--severity rule=level] [--ignore rule]\n')
+    return 2
+  }
+
+  try {
+    const { config } = loadProject(configPath)
+    const report = parseReconciliationReport(JSON.parse(readFileSync(resolve(reportPath), 'utf8')) as unknown)
+    const presetValue = optionValues(argv, '--preset')[0]
+    const preset = presetValue === undefined
+      ? undefined
+      : (['default', 'recommended', 'strict'].includes(presetValue) ? presetValue as RuleMode : (() => { throw new Error(`Invalid rules preset "${presetValue}".`) })())
+    const severity: Partial<Record<RuleId, RuleSeverity>> = {}
+    for (const [rule, level] of Object.entries(parseRuleAssignments(optionValues(argv, '--severity'), parseRuleSeverity))) {
+      severity[parseRuleId(rule)] = level
+    }
+    const ignore = optionValues(argv, '--ignore').map(parseRuleId)
+    const result = evaluateRules(report, {
+      ...(config.rules ? { config: config.rules } : {}),
+      ...(preset ? { preset } : {}),
+      ...(Object.keys(severity).length ? { severity } : {}),
+      ...(ignore.length ? { ignore } : {}),
+      ...(optionValues(argv, '--critical-entity').length ? { criticalEntities: optionValues(argv, '--critical-entity') } : {}),
+      ...(optionValues(argv, '--critical-path').length ? { criticalPaths: optionValues(argv, '--critical-path') } : {}),
+    })
+    if (wantsTextOutput(flags, config)) {
+      writeLines([
+        `Rules: ${result.mode}`,
+        `Findings: ${result.findings.length}`,
+        ...(result.findings.length ? result.findings.map((finding) => `  [${finding.severity}] ${finding.code}: ${finding.message}`) : ['  (none)']),
+        `Exit code: ${result.exitCode}`,
+      ])
+    } else {
+      writeJson({ ok: result.exitCode === 0, reportHash: report.contentHash, ...result })
+    }
+    return result.exitCode
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
+const runFixCommand = (argv: readonly string[], positional: readonly string[], configPath: string | undefined): number => {
+  try {
+    const { config, root } = loadProject(configPath)
+    const action = positional[1]
+    const proposalPath = positional[2]
+    const sourceRevision = discoverRepository({ root, config }).sourceRevision
+    const fixOptions = { baseRevision: sourceRevision, configurationHash: sha256NormalizedV1(config), ...(config.project?.name ? { projectName: config.project.name } : {}) }
+    if (action === 'propose') {
+      const proposal = positional[2] === 'links'
+        ? createMarkdownLinkFixProposal(root, fixOptions)
+        : positional[2] === 'normalize' && positional[3] ? createArtifactNormalizationProposal(root, positional[3], fixOptions) : undefined
+      if (!proposal) { writeJson({ ok: true, proposal: null }); return 0 }
+      const outputPath = optionValues(argv, '--output')[0]
+      if (outputPath) { mkdirSync(dirname(resolve(root, outputPath)), { recursive: true }); writeFileSync(resolve(root, outputPath), `${JSON.stringify(proposal, null, 2)}\n`, 'utf8') }
+      writeJson({ ok: true, proposal, ...(outputPath ? { proposalPath: resolve(root, outputPath) } : {}) })
+      return 0
+    }
+    if (!proposalPath || !['approve', 'apply'].includes(action ?? '')) throw new Error('Usage: ak-docs fix propose links|normalize <artifact> [--output <file>] | fix approve|apply <proposal.json> [--by <name>]')
+    const file = resolve(root, proposalPath)
+    const proposal = JSON.parse(readFileSync(file, 'utf8')) as unknown
+    const result = action === 'approve' ? approveFixProposal(proposal, optionValues(argv, '--by')[0] ?? 'human') : applyFixProposal(root, proposal, { currentRevision: sourceRevision })
+    writeFileSync(file, `${JSON.stringify(result, null, 2)}\n`, 'utf8')
+    writeJson({ ok: true, proposal: result, proposalPath: file })
+    return 0
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
+const runSuggestCommand = async (flags: ReadonlySet<string>, configPath: string | undefined): Promise<number> => {
+  try {
+    const { config, root } = loadProject(configPath)
+    const stateDir = resolve(root, config.workflow?.stateDir ?? '.doc-bridge/workflow')
+    const snapshot = parseDiscoverySnapshot(loadWorkflowStepOutput(stateDir, 'normalize'))
+    const report = parseReconciliationReport(loadWorkflowStepOutput(stateDir, 'reconcile'))
+    const adapter = createRegistryAgentAdapter(root, config, await loadRegistryAgentRunner(root, config))
+    const proposal = await adapter.run(snapshot, report)
+    const proposalPath = persistRegistryAgentProposal(stateDir, proposal)
+    if (flags.has('--text')) writeLines([`Agent: ${adapter.metadata.id}`, `Proposal: ${proposal.proposalId}`, `Hash: ${proposal.contentHash}`, `Saved: ${proposalPath}`])
+    else writeJson({ ok: true, proposal, proposalPath })
+    return 0
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 2
+  }
+}
+
 const writeIfMissing = (path: string, contents: string): boolean => {
   if (existsSync(path)) return false
   mkdirSync(dirname(path), { recursive: true })
@@ -617,6 +866,37 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
   }
 
+  if (command === 'discover') {
+    try {
+      let config: DocBridgeConfigV1 | undefined
+      let root = process.cwd()
+      try {
+        const loaded = loadProject(configPath)
+        config = loaded.config
+        root = loaded.root
+      } catch (error) {
+        if (!(error instanceof ConfigNotFoundError) || configPath) throw error
+      }
+      const snapshot = discoverRepository({ root, ...(config ? { config } : {}) })
+      if (wantsTextOutput(flags, config ?? { surfaces: { cli: { defaultFormat: 'json' } } } as DocBridgeConfigV1)) {
+        writeLines([`Project: ${snapshot.project.name}`, `Entities: ${snapshot.entities.length}`, `Relations: ${snapshot.relations.length}`, `Source revision: ${snapshot.sourceRevision}`, ...(config ? [] : ['No configuration found; discovery used safe defaults.'])])
+      } else {
+        writeJson({ ok: true, snapshot, ...(config ? {} : { proposedConfig: { schemaVersion: 1, corpus: { agent: { root: 'docs/for-agents' } } } }) })
+      }
+      return 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)
+  }
+
+  if (command === 'fix') return runFixCommand(argv, positional, configPath)
+  if (command === 'suggest') return runSuggestCommand(flags, configPath)
+
   if (command === 'init') {
     const root = process.cwd()
     const withDemo = flags.has('--demo') || !flags.has('--no-demo')
@@ -816,6 +1096,8 @@ export const runCli = (argv: readonly string[]): number | undefined | Promise<nu
     }
   }
 
+  if (command === 'rules') return runRulesCommand(argv, flags, positional, configPath)
+
   if (command === 'conformance') {
     const action = positional[1]
     const profile = positional[2]

package/src/config/defaults.ts

@@ -36,6 +36,14 @@ export const applyConfigDefaults = (config: DocBridgeConfigV1): DocBridgeConfigV
       preset: 'minimal',
       ...config.gates,
     },
+    rules: {
+      mode: 'default',
+      ...config.rules,
+    },
+    safety: {
+      redactSecrets: true,
+      ...config.safety,
+    },
     surfaces: {
       cli: {
         bin: 'ak-docs',
@@ -44,7 +52,12 @@ export const applyConfigDefaults = (config: DocBridgeConfigV1): DocBridgeConfigV
       },
       mcp: {
         enabled: true,
-        tools: ['handoff.resolve', 'doc.search', 'doc.get', 'gate.status'],
+        tools: [
+          'handoff.resolve', 'doc.search', 'doc.get', 'gate.status', 'retriever.query',
+          'memory.classify', 'memory.promoteDraft', 'registry.topology',
+          'docbridge.snapshot', 'docbridge.report', 'docbridge.diagnostics',
+          'docbridge.relations', 'docbridge.run', 'docbridge.proposals',
+        ],
         transport: 'stdio',
         ...config.surfaces?.mcp,
       },

package/src/config/schema.ts

@@ -44,6 +44,8 @@ export const IndexConfigSchema = z
         enabled: z.boolean().optional(),
         outFile: z.string().min(1).max(512).optional(),
         preamble: z.string().max(4_000).optional(),
+        urlPrefix: z.string().url().optional(),
+        pathPrefix: z.string().min(1).max(512).optional(),
       })
       .strict()
       .optional(),
@@ -150,6 +152,50 @@ export const GatesConfigSchema = z
   })
   .strict()
 
+export const RuleIdSchema = z.enum([
+  'documentation-quality',
+  'graph-undocumented-relation',
+  'declared-unobserved-relation',
+  'unresolved-reference',
+  'conflicting-declaration',
+  'not-analyzed-coverage',
+  'stale-documentation',
+  'centrality-risk',
+  'critical-path-risk',
+  'freshness',
+  'ownership',
+])
+
+export const RuleSeveritySchema = z.enum(['off', 'info', 'warn', 'error'])
+
+export const RulesConfigSchema = z
+  .object({
+    mode: z.enum(['default', 'recommended', 'strict']).optional(),
+    severity: z.record(RuleIdSchema, RuleSeveritySchema).optional(),
+    ignore: z.array(RuleIdSchema).max(128).optional(),
+    criticalEntities: z.array(z.string().min(1).max(256)).max(128).optional(),
+    criticalPaths: z.array(z.string().min(1).max(512)).max(128).optional(),
+    warningThresholds: z.record(RuleIdSchema, z.number().int().min(1).max(100_000)).optional(),
+  })
+  .strict()
+
+export const WorkflowConfigSchema = z
+  .object({
+    stateDir: z.string().min(1).max(512).optional(),
+  })
+  .strict()
+
+export const RepositorySafetyConfigSchema = z
+  .object({
+    exclude: z.array(z.string().min(1).max(512)).max(128).optional(),
+    maxFiles: z.number().int().positive().max(1_000_000).optional(),
+    maxBytes: z.number().int().positive().max(10_000_000_000).optional(),
+    maxTimeMs: z.number().int().positive().max(86_400_000).optional(),
+    maxMemoryMb: z.number().int().positive().max(1_048_576).optional(),
+    redactSecrets: z.boolean().optional(),
+  })
+  .strict()
+
 export const SurfacesConfigSchema = z
   .object({
     cli: z
@@ -174,6 +220,12 @@ export const SurfacesConfigSchema = z
               'memory.classify',
               'memory.promoteDraft',
               'registry.topology',
+              'docbridge.snapshot',
+              'docbridge.report',
+              'docbridge.diagnostics',
+              'docbridge.relations',
+              'docbridge.run',
+              'docbridge.proposals',
             ]),
           )
           .max(16)
@@ -245,6 +297,15 @@ export const IntelligenceConfigSchema = z
       .optional(),
     runtime: z.enum(['agentskit', 'custom']).optional(),
     runtimeModule: z.string().min(1).max(512).optional(),
+    registry: z
+      .object({
+        enabled: z.boolean().optional(),
+        agentId: z.string().min(1).max(256).optional(),
+        agentRoot: z.string().min(1).max(512).optional(),
+        runnerModule: z.string().min(1).max(512).optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict()
 
@@ -373,6 +434,9 @@ export const DocBridgeConfigV1Schema = z
     index: IndexConfigSchema.optional(),
     routing: RoutingConfigSchema.optional(),
     gates: GatesConfigSchema.optional(),
+    rules: RulesConfigSchema.optional(),
+    workflow: WorkflowConfigSchema.optional(),
+    safety: RepositorySafetyConfigSchema.optional(),
     surfaces: SurfacesConfigSchema.optional(),
     intelligence: IntelligenceConfigSchema.optional(),
     federation: FederationConfigSchema.optional(),
@@ -385,3 +449,8 @@ 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 RuleId = z.infer<typeof RuleIdSchema>
+export type RuleSeverity = z.infer<typeof RuleSeveritySchema>
+export type RulesConfig = z.infer<typeof RulesConfigSchema>
+export type WorkflowConfig = z.infer<typeof WorkflowConfigSchema>
+export type RepositorySafetyConfig = z.infer<typeof RepositorySafetyConfigSchema>

package/src/conformance/ecosystem-contract.ts

@@ -22,7 +22,7 @@ const ProductSchema = z.object({
   role: NonEmptyStringSchema,
   promise: NonEmptyStringSchema,
   maturity: z.enum(['planning', 'alpha', 'beta', 'stable', 'deprecated']),
-  repo: RepoSchema,
+  repo: RepoSchema.nullable(),
   accent: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
   surfaces: SurfaceSchema,
   navigation: z.object({
@@ -38,7 +38,7 @@ const LegacyPropertySchema = z.object({
   barLabel: NonEmptyStringSchema,
   domain: NonEmptyStringSchema,
   url: HttpsUrlSchema,
-  repo: RepoSchema,
+  repo: RepoSchema.nullable(),
   tagline: NonEmptyStringSchema,
   kind: NonEmptyStringSchema,
   accent: z.string().regex(/^#[0-9A-Fa-f]{6}$/),
@@ -82,6 +82,7 @@ const ClaimProductSchema = z.object({
   source: z.discriminatedUnion('type', [
     z.object({ type: z.literal('endpoint'), url: HttpsUrlSchema }).passthrough(),
     z.object({ type: z.literal('repository'), repo: RepoSchema }).passthrough(),
+    z.object({ type: z.literal('declaration'), summary: NonEmptyStringSchema }).passthrough(),
   ]),
   verification: z.enum(['verified', 'declared']),
   claims: z.array(ClaimSchema),
@@ -171,8 +172,10 @@ export const parseCanonicalEcosystemContract = (
     if (!claimProduct) throw new Error(`Claims are missing product ${productId}.`)
     if (claimProduct.source.type === 'endpoint') {
       if (claimProduct.source.url !== product.surfaces.stats) throw new Error(`Claims source for ${productId} must match stats.`)
-    } else if (claimProduct.source.repo !== product.repo) {
+    } else if (claimProduct.source.type === 'repository' && claimProduct.source.repo !== product.repo) {
       throw new Error(`Claims source for ${productId} must match repo.`)
+    } else if (claimProduct.source.type === 'declaration' && product.repo !== null) {
+      throw new Error(`Declaration source for ${productId} requires a null repo.`)
     }
     if (claimProduct.verification === 'declared' && claimProduct.claims.length > 0) {
       throw new Error(`Declared product ${productId} cannot publish claims.`)