@redpanda-data/docs-extensions-and-macros 5.48.0 → 5.49.0

package/bin/doc-tools.js

@@ -2755,6 +2755,7 @@ programCli
   .option('--format <format>', 'Output format: human or json', 'human')
   .option('--skip-rules <list>', 'Comma-separated rule ids to skip')
   .option('--only-rules <list>', 'Comma-separated rule ids to run exclusively')
+  .option('--reviewed <file>', 'Diff mode: skip declarations whose fingerprint is listed in <file> (already reviewed on an earlier push)')
   .option('--strict', 'Exit 1 when any error-severity finding exists (default: always exit 0 - suggest, never block)')
   .action((options) => {
     const { runCli } = require('../tools/lint-strings')
@@ -2908,6 +2909,92 @@ overridesGroup
     }
   })
 
+/**
+ * @description Build the plain-text prompt an external LLM triage call
+ * should send for one UPSTREAMABLE or SPLIT KEEP_UNTIL_UPSTREAMED audit row.
+ * Reads a single candidate object (not an array) from --candidate. See
+ * tools/overrides-audit/triage.js for the prompt contract.
+ *
+ * @why Separated from the actual LLM call so the workflow that runs it can
+ * use whatever action/model it wants; this command only builds the prompt.
+ *
+ * @example
+ * npx doc-tools overrides triage-prompt --candidate candidate.json
+ */
+overridesGroup
+  .command('triage-prompt')
+  .description('Build the triage prompt for one UPSTREAMABLE/SPLIT candidate')
+  .requiredOption('--candidate <path>', 'Path to a single candidate row JSON file (one object, not an array)')
+  .action((options) => {
+    const { buildTriagePrompt } = require('../tools/overrides-audit/triage')
+    try {
+      const candidate = JSON.parse(fs.readFileSync(path.resolve(options.candidate), 'utf8'))
+      console.log(buildTriagePrompt(candidate))
+    } catch (err) {
+      fail(err.message)
+    }
+  })
+
+/**
+ * @description Parse the raw text an LLM triage call returned for one
+ * candidate and merge it into that candidate's manifest row, adding
+ * agent_verdict / agent_reason / triage_failed. Any malformed, empty, or
+ * unexpected response degrades to a safe AMBIGUOUS verdict rather than
+ * throwing — a triage call failing is not a reason to fail the pipeline,
+ * it's a reason to ask a human. See tools/overrides-audit/triage.js.
+ *
+ * @example
+ * npx doc-tools overrides triage-parse --candidate candidate.json --response response.txt
+ */
+overridesGroup
+  .command('triage-parse')
+  .description('Merge an LLM triage response into a candidate row')
+  .requiredOption('--candidate <path>', 'Path to the candidate row JSON file this response answers')
+  .requiredOption('--response <path>', 'Path to the raw text file the LLM triage call returned')
+  .action((options) => {
+    const { triageCandidate } = require('../tools/overrides-audit/triage')
+    try {
+      const candidate = JSON.parse(fs.readFileSync(path.resolve(options.candidate), 'utf8'))
+      // A triage call that failed before writing its output leaves no
+      // response file. Treat that as an empty response so it reaches the
+      // AMBIGUOUS fallback instead of failing the command.
+      let rawResponse = ''
+      try {
+        rawResponse = fs.readFileSync(path.resolve(options.response), 'utf8')
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err
+      }
+      console.log(JSON.stringify(triageCandidate(candidate, rawResponse), null, 2))
+    } catch (err) {
+      fail(err.message)
+    }
+  })
+
+/**
+ * @description Render one plain-English markdown report section from a
+ * batch of triaged candidate rows (rows already carrying agent_verdict from
+ * triage-parse). See tools/overrides-audit/report.js for what each section
+ * contains and what happens to rows outside the requested verdict.
+ *
+ * @example
+ * npx doc-tools overrides report --candidates triaged.json --section upstream
+ */
+overridesGroup
+  .command('report')
+  .description('Build a plain-English markdown report section from triaged candidates')
+  .requiredOption('--candidates <path>', 'Path to a JSON array of triaged candidate rows')
+  .addOption(new Option('--section <section>', 'Which report section to build').choices(['upstream', 'retirement', 'ambiguous']).makeOptionMandatory())
+  .action((options) => {
+    const { buildUpstreamSection, buildRetirementSection, buildAmbiguousDigest } = require('../tools/overrides-audit/report')
+    const BUILDERS = { upstream: buildUpstreamSection, retirement: buildRetirementSection, ambiguous: buildAmbiguousDigest }
+    try {
+      const candidates = JSON.parse(fs.readFileSync(path.resolve(options.candidates), 'utf8'))
+      console.log(BUILDERS[options.section](candidates))
+    } catch (err) {
+      fail(err.message)
+    }
+  })
+
 programCli.addCommand(automation)
 /**
  * validate kapa-source-groups

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.48.0",
+  "version": "5.49.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/lint-strings/diff.js

@@ -20,7 +20,14 @@ const { spawnSync } = require('child_process')
  */
 const SURFACE_ROUTES = [
   { surface: 'properties', pattern: /^src\/v\/config\// },
-  { surface: 'metrics', pattern: /(^|\/)[^/]*probe\.cc$|^src\/v\/metrics\// },
+  // Metrics are registered wherever a component exposes them, not in files
+  // with a predictable name: raft/consensus.cc, cluster/rm_stm.cc and
+  // headers such as kafka/server/kafka_probe.h all call sm::description. So
+  // route every non-test C++ source under src/v (config/ has already matched
+  // properties above) and let the scanner, which skips any file with no
+  // description() call, decide what is a declaration. Test directories are
+  // excluded the same way the whole-repo scan excludes them.
+  { surface: 'metrics', pattern: /^src\/v\/(?!(?:.*\/)?tests?\/).*\.(?:cc|h)$/ },
   { surface: 'rpk', pattern: /^src\/go\/rpk\/pkg\/cli\// },
   // Both chart layouts ship: charts/<name>/chart/values.yaml (redpanda,
   // console) and charts/<name>/values.yaml (connectors).

package/tools/lint-strings/index.js

@@ -1,7 +1,10 @@
 'use strict'
 
+const crypto = require('crypto')
 const fs = require('fs')
+const os = require('os')
 const path = require('path')
+const { spawnSync } = require('child_process')
 
 const { runRules, mergeResults } = require('./engine')
 const { getDiffLines, classifyDiff, spanIntersects, SURFACE_ROUTES } = require('./diff')
@@ -54,6 +57,9 @@ function rulesFor (surface) {
  *   only declarations whose span intersects lines changed since this ref
  * @param {string[]} [options.skipRules]
  * @param {string[]} [options.onlyRules]
+ * @param {Set<string>} [options.reviewedFingerprints] - Diff mode: skip
+ *   declarations (and removals) whose fingerprint is in this set, so a PR
+ *   review sees each string once across pushes
  * @param {Function} [options.log] - Progress logger (stderr by default)
  * @returns {Object} { findings, summary, unsupported_surfaces }
  */
@@ -64,6 +70,7 @@ function lintStrings (options) {
     diffBase = null,
     skipRules = [],
     onlyRules = null,
+    reviewedFingerprints = null,
     log = (msg) => process.stderr.write(`${msg}\n`)
   } = options
 
@@ -83,12 +90,16 @@ function lintStrings (options) {
 
   const results = []
   const unsupportedSurfaces = []
-  let removedSurfaceFiles = []
+  const reviewed = reviewedFingerprints || new Set()
+  const pending = []
+  let alreadyReviewed = 0
+  let removal = { rawFiles: [], declarations: [] }
 
   if (diffBase) {
     const { changed, removed } = getDiffLines(repoPath, diffBase)
     const classified = classifyDiff(changed)
-    removedSurfaceFiles = collectRemovals(removed, surfaces)
+    const removedBySurface = classifyDiff(removed)
+    const headBySurface = {}
 
     for (const [surfaceName, files] of Object.entries(classified)) {
       if (!SURFACES[surfaceName]) {
@@ -101,13 +112,31 @@ function lintStrings (options) {
 
       const surface = SURFACES[surfaceName]
       log(`[${surfaceName}] ${files.size} changed file(s) in diff; extracting declarations at HEAD...`)
-      const fileSet = new Set(files.keys())
-      const declarations = surface
-        .extract({ repo: repoPath, files: fileSet, log })
-        .filter((decl) => spanIntersects(decl.line_start, decl.line_end, files.get(decl.file)))
-      for (const decl of declarations) decl.in_pr_diff = true
+      // Files that only lost lines are extracted too: a declaration that
+      // still exists at HEAD, in any touched file, was edited or moved, not
+      // removed.
+      const removedFiles = removedBySurface[surfaceName] ? [...removedBySurface[surfaceName].keys()] : []
+      const head = surface.extract({ repo: repoPath, files: new Set([...files.keys(), ...removedFiles]), log })
+      headBySurface[surfaceName] = head
+      const declarations = []
+      for (const decl of head) {
+        if (!touches(decl, files.get(decl.file))) continue
+        decl.in_pr_diff = true
+        decl.fingerprint = fingerprint(decl)
+        if (reviewed.has(decl.fingerprint)) {
+          alreadyReviewed++
+          continue
+        }
+        declarations.push(decl)
+        pending.push(pendingEntry(decl))
+      }
       results.push(runRules(declarations, rulesFor(surface), { skipRules, onlyRules }))
     }
+
+    removal = collectRemovals({ repoPath, diffBase, removed: removedBySurface, surfaces, requested, headBySurface, log })
+    const kept = removal.declarations.filter((decl) => !reviewed.has(decl.fingerprint))
+    alreadyReviewed += removal.declarations.length - kept.length
+    removal.declarations = kept
   } else {
     for (const surfaceName of requested) {
       const surface = SURFACES[surfaceName]
@@ -119,34 +148,213 @@ function lintStrings (options) {
   }
 
   const merged = mergeResults(results)
+  for (const finding of merged.findings) {
+    if (finding.in_pr_diff) finding.fingerprint = fingerprint(finding)
+  }
   merged.findings.sort((a, b) =>
     a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file) || (a.line_start || 0) - (b.line_start || 0))
   merged.unsupported_surfaces = unsupportedSurfaces
+  if (diffBase) {
+    merged.declarations = pending
+    merged.summary.alreadyReviewed = alreadyReviewed
+  }
+  merged.summary.removedDeclarations = removal.declarations.map(pendingEntry)
+  const removedSurfaceFiles = [...removal.rawFiles, ...removedFilesFor(removal.declarations)]
+    .sort((a, b) => a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file))
   merged.summary.removedSurfaceFiles = removedSurfaceFiles
   merged.summary.removedSurfaceLines = removedSurfaceFiles.reduce((sum, entry) => sum + entry.lines, 0)
   return merged
 }
 
 /**
- * Deletions in files that route to a doc-string surface, so a deletion-only PR
- * still registers as touching a surface. Reported separately from
- * totalDeclarations because a removed declaration is absent from HEAD and
- * therefore cannot be extracted or linted.
+ * A declaration's anchor lines: its span, plus any lines a surface records
+ * separately because the declared name lives outside it (metrics names sit
+ * in the enclosing make_*() call).
+ */
+function spansOf (decl) {
+  const spans = [[decl.line_start, decl.line_end]]
+  const extra = decl.meta && decl.meta.name_lines
+  if (extra) spans.push(extra)
+  return spans
+}
+
+function inSpans (decl, line) {
+  return spansOf(decl).some(([start, end]) => start != null && line >= start && line <= end)
+}
+
+function touches (decl, lineSet) {
+  return spansOf(decl).some(([start, end]) => spanIntersects(start, end, lineSet))
+}
+
+/**
+ * Stable identity for one version of one doc string. A PR review records the
+ * fingerprints it has seen, and a later push skips any declaration whose
+ * surface, name and text are unchanged, so rebases, moves and unrelated edits
+ * never re-review a string. Editing the string changes the fingerprint.
+ */
+function fingerprint (decl) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify([decl.surface, decl.name, decl.string == null ? null : decl.string]))
+    .digest('hex')
+    .slice(0, 16)
+}
+
+function removalFingerprint (surfaceName, identity) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify(['removed', surfaceName, identity]))
+    .digest('hex')
+    .slice(0, 16)
+}
+
+/**
+ * Where a declaration lives, for matching the merge-base side against HEAD.
+ * Bare names repeat on most surfaces (a `name` field in many proto messages,
+ * `enabled` in many CRD structs, the same flag on many rpk commands), so each
+ * surface supplies a contextual identity; without one, the name is used.
+ */
+function identityOf (surface, decl) {
+  return surface.identity ? surface.identity(decl) : decl.name
+}
+
+function pendingEntry (decl) {
+  return {
+    surface: decl.surface,
+    name: decl.name,
+    file: decl.file,
+    line_start: decl.line_start,
+    line_end: decl.line_end,
+    fingerprint: decl.fingerprint
+  }
+}
+
+function removedFilesFor (declarations) {
+  const byFile = new Map()
+  for (const decl of declarations) {
+    const key = `${decl.surface}\0${decl.file}`
+    const lines = (decl.removed_lines || 0)
+    byFile.set(key, { surface: decl.surface, file: decl.file, lines: (byFile.has(key) ? byFile.get(key).lines : 0) + lines })
+  }
+  return [...byFile.values()].sort((a, b) => a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file))
+}
+
+/**
+ * Materialize the merge-base version of `files` into a scratch tree, so a
+ * surface extractor can read the pre-image. A surface that declares
+ * baseScope 'directory' gets the whole directories instead: the properties
+ * extractor pairs each .cc with its .h.
+ */
+function materializeBase (repoPath, diffBase, files, scope = 'file') {
+  const mb = spawnSync('git', ['merge-base', diffBase, 'HEAD'], { cwd: repoPath, encoding: 'utf8' })
+  if (mb.status !== 0) throw new Error(`git merge-base ${diffBase} HEAD failed: ${mb.stderr}`)
+  const base = mb.stdout.trim()
+  const paths = scope === 'directory' ? [...new Set(files.map((f) => path.dirname(f)))] : files
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'lint-strings-base-'))
+  const archive = spawnSync('git', ['archive', '--format=tar', base, '--', ...paths], { cwd: repoPath, maxBuffer: 1024 * 1024 * 1024 })
+  if (archive.status !== 0) {
+    fs.rmSync(scratch, { recursive: true, force: true })
+    throw new Error(`git archive ${base} failed: ${archive.stderr}`)
+  }
+  const untar = spawnSync('tar', ['-x', '-C', scratch], { input: archive.stdout })
+  if (untar.status !== 0) {
+    fs.rmSync(scratch, { recursive: true, force: true })
+    throw new Error(`tar failed: ${untar.stderr}`)
+  }
+  return scratch
+}
+
+/**
+ * Doc-string declarations the diff removed or renamed.
+ *
+ * A deleted line only matters when it belonged to a declaration: removing an
+ * include, a struct field or a checksum from a surface file is not a removed
+ * surface. So the old side of each affected file is extracted at the merge
+ * base, and a declaration counts as removed when its span there lost lines
+ * and HEAD, across every file the diff touched, holds fewer declarations with
+ * its identity (see identityOf) than the merge base did. Still present means
+ * it was edited or moved, and HEAD-side review covers it. Counting, rather
+ * than asking whether the identity appears at all, keeps a deletion visible
+ * when another declaration shares the identity and survives.
  *
- * Surfaces routed without a registered extractor are included: the gate cares
- * that documented content went away, not whether we can lint what replaced it.
+ * Declarations are absent from HEAD by construction, so they cannot be linted;
+ * they are reported for the published-content check instead.
  *
- * @param {Map<string, Set<number>>} removed - From getDiffLines().removed
- * @param {string[]|null} surfaces - Explicit --surface narrowing, if any
+ * Surfaces routed without a registered extractor, and any base extraction
+ * that fails, fall back to counting raw deleted lines: without an extractor
+ * there is no way to tell, and the gate should err toward reviewing.
+ *
+ * @returns {{ rawFiles: Array, declarations: Array }}
  */
-function collectRemovals (removed, surfaces) {
+function collectRemovals ({ repoPath, diffBase, removed, surfaces, requested, headBySurface, log }) {
   const only = surfaces && surfaces.length > 0 ? new Set(surfaces) : null
-  const entries = []
-  for (const [surface, files] of Object.entries(classifyDiff(removed))) {
-    if (only && !only.has(surface)) continue
-    for (const [file, lines] of files) entries.push({ surface, file, lines: lines.size })
+  const rawFiles = []
+  const declarations = []
+
+  for (const [surfaceName, files] of Object.entries(removed)) {
+    if (only && !only.has(surfaceName)) continue
+    const surface = SURFACES[surfaceName]
+    const raw = () => {
+      for (const [file, lines] of files) rawFiles.push({ surface: surfaceName, file, lines: lines.size })
+    }
+    if (!surface || !requested.includes(surfaceName)) {
+      raw()
+      continue
+    }
+
+    let scratch = null
+    try {
+      scratch = materializeBase(repoPath, diffBase, [...files.keys()], surface.baseScope)
+      log(`[${surfaceName}] ${files.size} file(s) lost lines; extracting declarations at the merge base...`)
+      const baseDecls = surface.extract({ repo: scratch, files: new Set(files.keys()), log })
+      const head = headBySurface[surfaceName] ||
+        surface.extract({ repo: repoPath, files: new Set(files.keys()), log })
+      const keyOf = (decl) => JSON.stringify(identityOf(surface, decl))
+      const headCount = new Map()
+      for (const decl of head) headCount.set(keyOf(decl), (headCount.get(keyOf(decl)) || 0) + 1)
+      const baseCount = new Map()
+      const touched = new Map()
+      for (const decl of baseDecls) {
+        const key = keyOf(decl)
+        baseCount.set(key, (baseCount.get(key) || 0) + 1)
+        const lost = files.get(decl.file)
+        if (!touches(decl, lost)) continue
+        let count = 0
+        for (const line of lost) if (inSpans(decl, line)) count++
+        if (!touched.has(key)) touched.set(key, [])
+        touched.get(key).push({ decl, count })
+      }
+      // HEAD lost `deficit` declarations with this identity. When more
+      // touched ones share it than went missing, report the ones that lost
+      // the most lines: a deleted declaration loses its whole span.
+      const gone = new Map()
+      for (const [key, list] of touched) {
+        const deficit = baseCount.get(key) - (headCount.get(key) || 0)
+        if (deficit <= 0) continue
+        const picked = [...list].sort((a, b) => b.count - a.count || a.decl.line_start - b.decl.line_start).slice(0, deficit)
+        for (const entry of picked) gone.set(entry.decl, entry.count)
+      }
+      for (const decl of baseDecls) {
+        if (!gone.has(decl)) continue
+        const count = gone.get(decl)
+        declarations.push({
+          surface: surfaceName,
+          name: decl.name,
+          file: decl.file,
+          line_start: decl.line_start,
+          line_end: decl.line_end,
+          string: decl.string,
+          removed_lines: count,
+          fingerprint: removalFingerprint(surfaceName, identityOf(surface, decl))
+        })
+      }
+    } catch (err) {
+      log(`[${surfaceName}] could not extract the merge-base side (${err.message}); counting raw deleted lines instead`)
+      raw()
+    } finally {
+      if (scratch) fs.rmSync(scratch, { recursive: true, force: true })
+    }
   }
-  return entries.sort((a, b) => a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file))
+
+  return { rawFiles, declarations }
 }
 
 /**
@@ -175,9 +383,15 @@ function formatHuman (result) {
   lines.push('='.repeat(60))
   lines.push(`Declarations checked: ${summary.totalDeclarations}`)
   lines.push(`Declarations flagged: ${summary.flaggedDeclarations}`)
-  if (summary.removedSurfaceLines) {
+  if (summary.alreadyReviewed) {
+    lines.push(`Already reviewed on an earlier push (skipped): ${summary.alreadyReviewed}`)
+  }
+  for (const decl of summary.removedDeclarations || []) {
+    lines.push(`Removed or renamed: ${decl.name} (${decl.surface}, ${decl.file})`)
+  }
+  if (summary.removedSurfaceLines && !(summary.removedDeclarations || []).length) {
     lines.push(`Lines deleted from doc-string surfaces: ${summary.removedSurfaceLines} ` +
-      `(${summary.removedSurfaceFiles.length} file(s); removed declarations cannot be extracted from HEAD)`)
+      `(${summary.removedSurfaceFiles.length} file(s) with no extractor, so every deleted line counts)`)
   }
   lines.push(`Errors: ${summary.errors}  Warnings: ${summary.warnings}  Info: ${summary.info}`)
   if (Object.keys(summary.byRule).length > 0) {
@@ -202,6 +416,22 @@ function formatHuman (result) {
   return lines.join('\n')
 }
 
+/**
+ * Read a --reviewed file: fingerprints separated by whitespace or commas.
+ * Anything that is not a 16-hex-digit fingerprint is ignored, and a missing
+ * file is an empty set, so a first run and a corrupted cache both mean
+ * "review everything" rather than an error.
+ */
+function readFingerprints (file) {
+  let text = ''
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch {
+    return new Set()
+  }
+  return new Set(text.split(/[\s,]+/).filter((token) => /^[0-9a-f]{16}$/.test(token)))
+}
+
 /**
  * CLI entry point shared by bin/doc-tools.js and direct invocation
  * (node tools/lint-strings --repo <path> ...).
@@ -217,7 +447,8 @@ function runCli (options) {
       surfaces: options.surface ? String(options.surface).split(',').map((s) => s.trim()).filter(Boolean) : null,
       diffBase: options.diff || null,
       skipRules: options.skipRules ? String(options.skipRules).split(',').map((s) => s.trim()).filter(Boolean) : [],
-      onlyRules: options.onlyRules ? String(options.onlyRules).split(',').map((s) => s.trim()).filter(Boolean) : null
+      onlyRules: options.onlyRules ? String(options.onlyRules).split(',').map((s) => s.trim()).filter(Boolean) : null,
+      reviewedFingerprints: options.reviewed ? readFingerprints(options.reviewed) : null
     })
   } catch (err) {
     console.error(`Error: ${err.message}`)
@@ -230,11 +461,13 @@ function runCli (options) {
     console.log(formatHuman(result))
   }
 
-  if (options.strict && result.summary.errors > 0) process.exit(1)
-  process.exit(0)
+  // exitCode, not process.exit(): exiting immediately drops whatever part of
+  // a large report is still buffered when stdout is a pipe, so a caller
+  // piping --format json into another process got truncated JSON.
+  process.exitCode = options.strict && result.summary.errors > 0 ? 1 : 0
 }
 
-module.exports = { lintStrings, formatHuman, runCli, SURFACES, rulesFor }
+module.exports = { lintStrings, formatHuman, runCli, SURFACES, rulesFor, fingerprint, readFingerprints }
 
 // Direct usage: node tools/lint-strings --repo <path> [--surface a,b]
 //   [--diff <base>] [--format json|human] [--strict]
@@ -249,10 +482,11 @@ if (require.main === module) {
     else if (arg === '--format') options.format = args[++i]
     else if (arg === '--skip-rules') options.skipRules = args[++i]
     else if (arg === '--only-rules') options.onlyRules = args[++i]
+    else if (arg === '--reviewed') options.reviewed = args[++i]
     else if (arg === '--strict') options.strict = true
     else {
       console.error(`Unknown argument: ${arg}`)
-      console.error('Usage: node tools/lint-strings --repo <path> [--surface a,b] [--diff <base>] [--format json|human] [--skip-rules a,b] [--only-rules a,b] [--strict]')
+      console.error('Usage: node tools/lint-strings --repo <path> [--surface a,b] [--diff <base>] [--format json|human] [--skip-rules a,b] [--only-rules a,b] [--reviewed <file>] [--strict]')
       process.exit(2)
     }
   }

package/tools/lint-strings/surfaces/api.js

@@ -761,11 +761,29 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. Field and message names
+ * repeat across messages (`name`, `enabled`), and rpc names across services,
+ * so the key is the proto package directory, the kind, and the dotted path
+ * inside the file. Proto names are unique per package, and buf keeps a
+ * package in one directory; a move to another package counts as a removal,
+ * which errs toward reviewing.
+ */
+function identity (decl) {
+  const meta = decl.meta || {}
+  let where = decl.name
+  if (meta.kind === 'field') where = meta.path || decl.name
+  else if (meta.kind === 'message' || meta.kind === 'enum') where = meta.block ? `${meta.block}.${decl.name}` : decl.name
+  else if (meta.kind === 'rpc-summary' || meta.kind === 'rpc-description') where = meta.service ? `${meta.service}.${decl.name}` : decl.name
+  return [path.dirname(decl.file), meta.kind || null, where]
+}
+
 module.exports = {
   name: 'api',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   rules: RULES,
   API_ROOTS,
   SUMMARY_KINDS,

package/tools/lint-strings/surfaces/connect.js

@@ -218,11 +218,23 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. Field names (`url`,
+ * `topic`, `enabled`) repeat across components, and a component name repeats
+ * across its input and output, so the key is the file, the kind and the name.
+ * Same-file repeats (nested object fields) are handled by counting in the
+ * caller.
+ */
+function identity (decl) {
+  return [decl.file, (decl.meta && decl.meta.kind) || null, decl.name]
+}
+
 module.exports = {
   name: 'connect',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   rules: RULES,
   // A connect description is the AsciiDoc page body, not a table cell:
   // bare | is legitimate table syntax there, and missing prose is handled

package/tools/lint-strings/surfaces/crd.js

@@ -421,11 +421,22 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. json names repeat across
+ * structs (`enabled`, `name`), so the key is the Go package directory, the
+ * struct and the json name. Go type names are unique per package, and a
+ * package is one directory.
+ */
+function identity (decl) {
+  return [path.dirname(decl.file), (decl.meta && decl.meta.struct) || null, decl.name]
+}
+
 module.exports = {
   name: 'crd',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   loadConfig,
   collectInlinedTypes,
   UNDESCRIBED_EXTERNAL_TYPES,

package/tools/lint-strings/surfaces/helm.js

@@ -472,6 +472,15 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. The name is the full
+ * values path, unique inside one values.yaml but repeated across charts, so
+ * the key is the file, the kind and the path.
+ */
+function identity (decl) {
+  return [decl.file, (decl.meta && decl.meta.kind) || null, decl.name]
+}
+
 module.exports = {
   name: 'helm',
   convention: CONVENTION,
@@ -480,6 +489,7 @@ module.exports = {
   publishableBlankKeys,
   scanKeyLines,
   misattachedMarkers,
+  identity,
   HELM_DOCS_MARKER_RE,
   rules: RULES
 }

package/tools/lint-strings/surfaces/metrics.js

@@ -197,7 +197,7 @@ function unescapeCpp (text) {
  * preceding make_* call that still encloses it, then read its first argument
  * if that argument is a string literal (adjacent literals concatenated).
  */
-function resolveMetricName (content, descIndex) {
+function resolveMetricName (content, descIndex, where = null) {
   const candidates = []
   MAKE_CALL.lastIndex = 0
   let match
@@ -213,6 +213,8 @@ function resolveMetricName (content, descIndex) {
     let i = openIndex + 1
     let name = ''
     let sawLiteral = false
+    let firstLiteral = -1
+    let lastLiteralEnd = -1
     while (i < content.length) {
       const ch = content[i]
       if (/\s/.test(ch)) {
@@ -228,11 +230,17 @@ function resolveMetricName (content, descIndex) {
         const end = skipLiteral(content, i)
         name += unescapeCpp(content.slice(i + 1, end - 1))
         sawLiteral = true
+        if (firstLiteral === -1) firstLiteral = i
+        lastLiteralEnd = end - 1
         i = end
         continue
       }
       break
     }
+    if (sawLiteral && where) {
+      where.start = firstLiteral
+      where.end = lastLiteralEnd
+    }
     return sawLiteral ? name : null
   }
   return null
@@ -268,16 +276,24 @@ function scanFile (content, file) {
     if (closeIndex === -1) continue
 
     const { verifiable, value } = parseArgument(masked.slice(openIndex + 1, closeIndex))
+    // The name literal sits in the enclosing make_*() call, outside the
+    // description span. Its lines are recorded so a rename counts as touching
+    // the declaration without widening the span a suggestion replaces.
+    const where = {}
+    const name = resolveMetricName(masked, match.index, where)
     declarations.push({
       surface: 'metrics',
-      name: resolveMetricName(masked, match.index),
+      name,
       file,
       line_start: lineOf(masked, match.index),
       line_end: lineOf(masked, closeIndex),
       string: value,
       declaration_text: null,
       convention: CONVENTION,
-      meta: { unverifiable: !verifiable }
+      meta: {
+        unverifiable: !verifiable,
+        name_lines: where.start != null ? [lineOf(masked, where.start), lineOf(masked, where.end)] : null
+      }
     })
     DESCRIPTION_CALL.lastIndex = closeIndex + 1
   }
@@ -359,10 +375,21 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. The extracted name is the
+ * make_*() argument without its add_group() prefix, so the same name repeats
+ * across groups; the file narrows it. Same-file repeats are handled by
+ * counting in the caller.
+ */
+function identity (decl) {
+  return [decl.file, decl.name]
+}
+
 module.exports = {
   name: 'metrics',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   rules: RULES
 }

package/tools/lint-strings/surfaces/properties.js

@@ -242,6 +242,9 @@ const RULES = [
 
 module.exports = {
   name: 'properties',
+  // The extractor pairs each .cc with its .h, so a merge-base extraction needs
+  // the whole directory, not only the files that lost lines.
+  baseScope: 'directory',
   convention: CONVENTION,
   extract,
   mapExtractorJson,

package/tools/lint-strings/surfaces/rpk.js

@@ -365,11 +365,22 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. Flag names (`format`,
+ * `brokers`) and command names (`list`, `create`) repeat across the command
+ * tree, which the extractor does not resolve, so the key is the file, the
+ * kind and the name. Same-file repeats are handled by counting in the caller.
+ */
+function identity (decl) {
+  return [decl.file, (decl.meta && decl.meta.kind) || null, decl.name]
+}
+
 module.exports = {
   name: 'rpk',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   rules: RULES,
   // Shorts and flag usages are one-liners by convention; the generic
   // too-short prose rule would flag nearly every conforming declaration.

package/tools/overrides-audit/classify.js

@@ -326,7 +326,7 @@ function deepEqual (a, b) {
  */
 function row (fields) {
   const base = { name: fields.name, field: fields.field, class: fields.class }
-  for (const key of ['upstream_candidate_text', 'audience_scoped_text', 'upstream_ref', 'content_hash', 'source_file', 'source_line', 'note']) {
+  for (const key of ['upstream_candidate_text', 'audience_scoped_text', 'upstream_ref', 'content_hash', 'source_file', 'source_line', 'source_text', 'note']) {
     if (fields[key] !== undefined) base[key] = fields[key]
   }
   return base
@@ -357,7 +357,11 @@ function classifyDescription (name, override, sourceProp, opts = {}) {
     field: 'description',
     content_hash: contentHash(name, overrideText),
     source_file: sourceProp ? sourceProp.defined_in : undefined,
-    source_line: sourceProp && sourceProp.line_start !== undefined ? sourceProp.line_start : undefined
+    source_line: sourceProp && sourceProp.line_start !== undefined ? sourceProp.line_start : undefined,
+    // Raw source description text, carried through so the agent triage layer
+    // (tools/overrides-audit/triage.js) can compare it against the override
+    // candidate text without re-reading the extracted-properties JSON itself.
+    source_text: sourceProp ? normalizeText(sourceProp.description) : undefined
   }
   if (override.upstream_ref !== undefined) common.upstream_ref = override.upstream_ref
   // Shown, never upstreamed. A scoped paragraph exists precisely so the other

package/tools/overrides-audit/report.js

@@ -0,0 +1,169 @@
+/**
+ * Overrides Audit - Triage Report Sections
+ *
+ * Formats triaged candidates (classify.js rows extended with agent_verdict /
+ * agent_reason / triage_failed by triage.js's triageCandidate) into the
+ * plain-English markdown sections a downstream workflow glues into PR and
+ * issue bodies. This module never calls `gh` itself; it only builds strings.
+ *
+ * Every builder here returns a non-empty string even for an empty input
+ * array, so a caller can always embed the return value directly into a
+ * larger PR/issue body without checking for emptiness first.
+ */
+
+'use strict'
+
+/**
+ * Render one candidate's property name as a markdown subsection heading.
+ *
+ * @param {string} name - Property (or command) name.
+ * @returns {string} Markdown heading line.
+ */
+function heading (name) {
+  return `## ${name}`
+}
+
+/**
+ * Render a labeled block of text as an indented markdown blockquote, so long
+ * override/source text cannot be confused with the surrounding prose.
+ *
+ * @param {string} label - Label line, e.g. "Override text:".
+ * @param {string} text - The text to quote.
+ * @returns {string} Markdown block.
+ */
+function quotedBlock (label, text) {
+  const quoted = String(text)
+    .split('\n')
+    .map((line) => `> ${line}`)
+    .join('\n')
+  return `${label}\n\n${quoted}`
+}
+
+/**
+ * Build the "nothing happened this run" placeholder for an empty section.
+ * Never an empty string: this is meant to be embedded directly into a larger
+ * PR/issue body, and an empty string there reads as a rendering bug rather
+ * than "there was nothing to report."
+ *
+ * @param {string} noun - What there was none of, e.g. "properties to upstream".
+ * @returns {string} A one-line markdown message.
+ */
+function nothingThisRun (noun) {
+  return `Nothing to report: no ${noun} this run.`
+}
+
+/**
+ * Whether a row carries an explicitly successful triage state.
+ *
+ * triageCandidate always emits a boolean triage_failed, so anything other
+ * than exactly false (missing, null, a string, a number) is a row this code
+ * cannot trust. Such a row stays out of the actionable sections and lands in
+ * the ambiguous digest instead.
+ *
+ * @param {Object} row - A triaged candidate row.
+ * @returns {boolean} True only when triage_failed is exactly false.
+ */
+function triageSucceeded (row) {
+  return row.triage_failed === false
+}
+
+/**
+ * Build the markdown section listing candidates the agent triage layer
+ * decided are genuinely better in the override and should be ported
+ * upstream into engineering source (verdict UPSTREAM_OVERRIDE).
+ *
+ * @param {Object[]} candidates - Triaged rows (from triage.js's triageCandidate).
+ * @returns {string} Markdown section, always non-empty.
+ */
+function buildUpstreamSection (candidates) {
+  const rows = (candidates || []).filter((c) => c.agent_verdict === 'UPSTREAM_OVERRIDE' && triageSucceeded(c))
+  if (rows.length === 0) return nothingThisRun('property descriptions to upstream')
+
+  const parts = [
+    `Found ${rows.length} property description${rows.length === 1 ? '' : 's'} worth porting upstream into engineering source.`
+  ]
+  for (const row of rows) {
+    parts.push([
+      heading(row.name),
+      row.agent_reason,
+      // A SPLIT row's override also carries audience-scoped paragraphs or
+      // docs-only markup that the candidate text leaves out, so porting the
+      // prose alone does not make the override redundant.
+      row.class === 'KEEP_UNTIL_UPSTREAMED'
+        ? 'This PR ports that into the source description. The docs override stays after it ships, because it also carries audience-scoped paragraphs or docs-only markup that source does not; that content needs handling separately before the override can retire.'
+        : 'This PR ports that into the source description; once merged and released, the docs override becomes redundant and retires itself automatically.'
+    ].join('\n\n'))
+  }
+  return parts.join('\n\n')
+}
+
+/**
+ * Build the markdown section listing candidates the agent triage layer
+ * decided source has caught up to or surpassed, so the docs-side override
+ * should simply be deleted (verdict RETIRE_OVERRIDE). Engineering source is
+ * never touched for these.
+ *
+ * @param {Object[]} candidates - Triaged rows (from triage.js's triageCandidate).
+ * @returns {string} Markdown section, always non-empty.
+ */
+function buildRetirementSection (candidates) {
+  const rows = (candidates || []).filter((c) => c.agent_verdict === 'RETIRE_OVERRIDE' && triageSucceeded(c))
+  if (rows.length === 0) return nothingThisRun('overrides to retire')
+
+  const parts = [
+    `Found ${rows.length} docs override${rows.length === 1 ? '' : 's'} that source has caught up to; retiring them rather than touching engineering source.`
+  ]
+  for (const row of rows) {
+    parts.push([
+      heading(row.name),
+      row.agent_reason,
+      quotedBlock('Override text (current docs override):', row.upstream_candidate_text),
+      quotedBlock('Source text (what docs will render instead):', row.source_text),
+      '**Retiring this override; docs will now render source\'s description.**'
+    ].join('\n\n'))
+  }
+  return parts.join('\n\n')
+}
+
+/**
+ * Build one combined markdown digest of every candidate the agent triage
+ * layer could not confidently resolve either way: a real AMBIGUOUS verdict,
+ * a failed/malformed triage response (triage_failed: true), and a row with
+ * no explicit triage state (triage_failed missing or not a boolean) get exactly
+ * the same treatment here, because all three are equally unresolved from a
+ * human's point of view - a parse failure is not quietly dropped just
+ * because it never produced a real verdict.
+ *
+ * This is one digest, not one artifact per property, matching this
+ * codebase's "one rolling artifact, idempotently rebuilt every run" pattern
+ * (see tools/rpk-docs/generate-plugin-stubs.js for that idiom elsewhere):
+ * it is meant to become the body of a single rolling tracking issue that
+ * gets replaced wholesale each run, not appended to.
+ *
+ * @param {Object[]} candidates - Triaged rows (from triage.js's triageCandidate).
+ * @returns {string} Markdown digest, always non-empty.
+ */
+function buildAmbiguousDigest (candidates) {
+  const rows = (candidates || []).filter((c) => c.agent_verdict === 'AMBIGUOUS' || !triageSucceeded(c))
+  if (rows.length === 0) return nothingThisRun('ambiguous property descriptions')
+
+  const parts = [
+    `${rows.length} property description${rows.length === 1 ? '' : 's'} could not be confidently triaged and need a human call.`
+  ]
+  for (const row of rows) {
+    parts.push([
+      heading(row.name),
+      quotedBlock('Override text:', row.upstream_candidate_text),
+      quotedBlock('Source text:', row.source_text),
+      row.agent_reason,
+      'Needs a human call.'
+    ].join('\n\n'))
+  }
+  return parts.join('\n\n')
+}
+
+module.exports = {
+  buildUpstreamSection,
+  buildRetirementSection,
+  buildAmbiguousDigest
+}

package/tools/overrides-audit/triage.js

@@ -0,0 +1,225 @@
+/**
+ * Overrides Audit - Agent Triage Layer
+ *
+ * classify.js is deterministic: any UPSTREAMABLE or SPLIT KEEP_UNTIL_UPSTREAMED
+ * candidate whose override text differs from source is treated as "our text
+ * is better, push it upstream." That is not always true. Source can be
+ * independently improved between audit runs to something as good as or
+ * better than the override, and classify.js has no way to notice: it only
+ * compares normalized text for equality, never for which one reads better.
+ *
+ * This module is the missing judgment step. It does not call an LLM itself -
+ * a GitHub Actions workflow in the docs repo owns that call. This module only
+ * (a) builds the prompt that call should send, and (b) parses whatever text
+ * comes back into one of three verdicts, defaulting to the safest one
+ * (AMBIGUOUS, meaning "leave the override alone, ask a human") on any
+ * uncertainty at all. Silently guessing UPSTREAM_OVERRIDE or RETIRE_OVERRIDE
+ * on a malformed response would either write bad prose into engineering
+ * source or delete an override that source has not actually caught up to -
+ * both worse than asking a human.
+ */
+
+'use strict'
+
+const VERDICTS = Object.freeze({
+  UPSTREAM_OVERRIDE: 'UPSTREAM_OVERRIDE',
+  RETIRE_OVERRIDE: 'RETIRE_OVERRIDE',
+  AMBIGUOUS: 'AMBIGUOUS'
+})
+
+const VALID_VERDICTS = new Set(Object.values(VERDICTS))
+const ALLOWED_RESPONSE_KEYS = new Set(['verdict', 'reason'])
+
+/**
+ * Build the plain-text prompt an external LLM call should send for one
+ * triage candidate.
+ *
+ * The prompt is written for a reader who has never seen this codebase: it
+ * explains the two texts being compared, the three possible verdicts in
+ * plain terms, and when to refuse to choose. It requires strict JSON back
+ * with no markdown fences and no surrounding prose, because parseTriageResponse
+ * has to be able to trust the shape of a well-behaved response and only fall
+ * back defensively for a badly-behaved one.
+ *
+ * @param {Object} candidate - A classify.js manifest row for a `description`
+ *   field classified UPSTREAMABLE or KEEP_UNTIL_UPSTREAMED (SPLIT), extended
+ *   with `source_text` (see classify.js's `common.source_text`).
+ * @param {string} candidate.name - Property (or command) name.
+ * @param {string} candidate.upstream_candidate_text - The override's candidate text.
+ * @param {string} candidate.source_text - The current source description text.
+ * @param {string} [candidate.source_file] - File the source description lives in.
+ * @param {number} [candidate.source_line] - Line the source description starts at.
+ * @returns {string} The prompt text.
+ * @throws {Error} When `candidate` is missing `upstream_candidate_text` or `source_text`.
+ *   This is a programming-error guard, not the agent-response fallback below:
+ *   a caller that hands this function a REDUNDANT row, or any row that never
+ *   got a source_text, has a bug that should fail loudly, not produce a
+ *   prompt that quietly asks an LLM to compare a real string to `undefined`.
+ */
+function buildTriagePrompt (candidate) {
+  if (!candidate || typeof candidate.upstream_candidate_text !== 'string') {
+    throw new Error(`buildTriagePrompt: candidate for "${candidate && candidate.name}" is missing upstream_candidate_text`)
+  }
+  if (typeof candidate.source_text !== 'string') {
+    throw new Error(`buildTriagePrompt: candidate for "${candidate.name}" is missing source_text`)
+  }
+
+  const location = candidate.source_file
+    ? `${candidate.source_file}${candidate.source_line !== undefined ? `:${candidate.source_line}` : ''}`
+    : 'unknown location'
+
+  return `You are triaging one property description for a documentation team.
+
+A documentation site publishes reference docs for a configuration property named "${candidate.name}". Its description currently comes from a manually written "override" that the docs team keeps because, at some point in the past, the engineering source code's own description of this property was missing, wrong, or worse than what the docs team wrote. Engineering source now defines its own description for the same property, at ${location}.
+
+Your job is to compare the two descriptions below and decide what should happen next.
+
+OVERRIDE TEXT (currently shown to docs readers, and a candidate to copy into engineering source):
+"""
+${candidate.upstream_candidate_text}
+"""
+
+CURRENT SOURCE TEXT (what engineering's own code says today):
+"""
+${candidate.source_text}
+"""
+
+Choose exactly one of these three verdicts:
+
+1. UPSTREAM_OVERRIDE - The override text is genuinely better or more complete than the source text. The right move is to copy the override's wording into the engineering source code, so that source eventually says what the override already says.
+
+2. RETIRE_OVERRIDE - The source text has caught up to, or become as good as or better than, the override in substance. There is no longer a good reason to keep the override. The right move is to delete the docs-side override entirely and let the docs site render the source text as-is, without ever touching engineering source.
+
+3. AMBIGUOUS - You cannot confidently choose between the two options above. Choose this if you are genuinely uncertain, if the two texts each contain distinct real information and neither one is a strict subset of the other (so picking one would lose real content), or if judging the two texts correctly requires technical knowledge of this system that cannot be confirmed from the text alone. When in doubt, choose AMBIGUOUS rather than guessing. Guessing wrong here either writes bad text into engineering source code or throws away a description a docs reader currently relies on, so it is always safer to flag this for a human than to guess.
+
+Respond with strict JSON only. Do not use markdown code fences. Do not include any words, explanation, or punctuation outside the JSON object. The response must be exactly one JSON object shaped like this:
+
+{"verdict": "UPSTREAM_OVERRIDE" | "RETIRE_OVERRIDE" | "AMBIGUOUS", "reason": "one or two plain-English sentences a non-engineer documentation reviewer can understand, explaining the comparison you made and why this verdict follows from it"}
+`
+}
+
+/**
+ * Extract a JSON value from raw agent response text. Accepts only a whole
+ * JSON response or one wrapped in a single pair of markdown code fences, the
+ * one common way a model fails to follow "strict JSON only" without changing
+ * what it said. Prose around the JSON is rejected rather than stripped: that
+ * prose can contradict the embedded verdict (for example "I cannot decide"
+ * followed by a RETIRE_OVERRIDE object), so it is not safe to trust the object.
+ *
+ * @param {string} text - Raw response text.
+ * @returns {*} The parsed value.
+ * @throws {Error} When the (unfenced) response is not valid JSON.
+ */
+function extractJson (text) {
+  let candidate = text.trim()
+
+  // Strip a single pair of markdown code fences, ```json ... ``` or ``` ... ```.
+  const fenceMatch = candidate.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)
+  if (fenceMatch) candidate = fenceMatch[1].trim()
+
+  return JSON.parse(candidate)
+}
+
+/**
+ * The safe, conservative fallback result for any response the parser cannot
+ * fully trust.
+ *
+ * @param {string} reason - Specific, human-readable explanation of what went wrong.
+ * @returns {{verdict: string, reason: string, triageFailed: boolean}}
+ */
+function ambiguousFallback (reason) {
+  return { verdict: VERDICTS.AMBIGUOUS, reason, triageFailed: true }
+}
+
+/**
+ * Defensively parse whatever text an LLM triage call returned.
+ *
+ * Clean JSON and JSON wrapped in markdown fences are accepted. JSON
+ * surrounded by stray prose, an empty or truncated response, or JSON that
+ * parses but carries an invalid or missing verdict or reason, or any field
+ * other than verdict and reason, is treated as
+ * a triage failure and mapped to the same safe AMBIGUOUS
+ * fallback: this function's job is to never let a malformed response be
+ * mistaken for a real UPSTREAM_OVERRIDE or RETIRE_OVERRIDE call.
+ *
+ * @param {string} rawText - Raw text returned by the LLM call.
+ * @returns {{verdict: string, reason: string, triageFailed: boolean}}
+ */
+function parseTriageResponse (rawText) {
+  if (typeof rawText !== 'string' || rawText.trim().length === 0) {
+    return ambiguousFallback('The triage call returned no response.')
+  }
+
+  let parsed
+  try {
+    parsed = extractJson(rawText)
+  } catch {
+    return ambiguousFallback('The triage response was not valid JSON.')
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return ambiguousFallback('The triage response was valid JSON but not a JSON object.')
+  }
+
+  // The prompt asks for exactly { verdict, reason }. An extra field such as
+  // needs_human_review or confidence can contradict the verdict, and nothing
+  // downstream reads it, so treat any extra key as a failed triage rather
+  // than silently dropping it.
+  const extraKeys = Object.keys(parsed).filter((key) => !ALLOWED_RESPONSE_KEYS.has(key))
+  if (extraKeys.length > 0) {
+    return ambiguousFallback(`The triage response included unexpected fields: ${extraKeys.join(', ')}.`)
+  }
+
+  // Case-sensitive on purpose: a case variant (e.g. "upstream_override") is a
+  // real deviation from the required response shape, worth surfacing as a
+  // failure rather than silently normalizing away.
+  if (typeof parsed.verdict !== 'string' || !VALID_VERDICTS.has(parsed.verdict)) {
+    return ambiguousFallback('The triage response used an unrecognized verdict value.')
+  }
+
+  if (typeof parsed.reason !== 'string' || parsed.reason.trim().length === 0) {
+    return ambiguousFallback('The triage response was missing a reason.')
+  }
+
+  return { verdict: parsed.verdict, reason: parsed.reason, triageFailed: false }
+}
+
+/**
+ * Combine a classify.js candidate row with the parsed result of a triage
+ * call, producing a manifest row extended with the agent's verdict.
+ *
+ * Field names follow classify.js's snake_case manifest-row convention rather
+ * than parseTriageResponse's camelCase return shape.
+ *
+ * @param {Object} candidate - A classify.js manifest row.
+ * @param {string} rawAgentResponse - Raw text returned by the LLM triage call.
+ * A RETIRE_OVERRIDE verdict on a SPLIT (KEEP_UNTIL_UPSTREAMED) candidate is
+ * downgraded to AMBIGUOUS, because retiring that override would also delete
+ * its audience-scoped or docs-only content.
+ *
+ * @returns {Object} `candidate` merged with `agent_verdict`, `agent_reason`, `triage_failed`.
+ */
+function triageCandidate (candidate, rawAgentResponse) {
+  let { verdict, reason, triageFailed } = parseTriageResponse(rawAgentResponse)
+  // A SPLIT (KEEP_UNTIL_UPSTREAMED) override also carries audience-scoped
+  // paragraphs or docs-only markup that the candidate text leaves out.
+  // Retiring the whole override would delete that content, so even when
+  // source prose has caught up, route the row to a human instead.
+  if (verdict === VERDICTS.RETIRE_OVERRIDE && candidate && candidate.class === 'KEEP_UNTIL_UPSTREAMED') {
+    verdict = VERDICTS.AMBIGUOUS
+    reason = `${reason} This override also carries audience-scoped paragraphs or docs-only markup that source does not, so it cannot be retired whole. Decide what to do with that content.`
+  }
+  return {
+    ...candidate,
+    agent_verdict: verdict,
+    agent_reason: reason,
+    triage_failed: triageFailed
+  }
+}
+
+module.exports = {
+  VERDICTS,
+  buildTriagePrompt,
+  parseTriageResponse,
+  triageCandidate
+}

package/tools/property-extractor/helpers/applyPropertyLinks.js

@@ -424,11 +424,17 @@ function normalizeIncludes(propName, raw, warnings) {
  *
  * Two separate reasons, and only the first was obvious. `cloud_supported: false`
  * says the control plane does not expose the property to customers. But
- * cloud-docs also publishes no broker properties page and no topic properties
- * page at all, so a link to any broker- or topic-scope property dangles there
- * however the install pack feels about it. That case cannot be read off
- * `cloud_supported`: cloud_config.py annotates cluster scope only and leaves the
- * field absent elsewhere, because "absent" means no opinion rather than false.
+ * cloud-docs also publishes no broker properties page at all, so a link to any
+ * broker-scope property dangles there however the install pack feels about it.
+ * That case cannot be read off `cloud_supported`: cloud_config.py annotates
+ * cluster scope only and leaves the field absent elsewhere, because "absent"
+ * means no opinion rather than false.
+ *
+ * Topic scope is not in that case. cloud-docs publishes a topic properties page
+ * that includes the docs topic-properties partial with the same tags as the docs
+ * page (every category, minus deprecated and exclude-from-docs), so a topic
+ * property missing from Cloud is missing from self-managed too, and
+ * `self-managed-only:` would only strip a working link.
  *
  * @param {Object} target - The property being linked to.
  * @returns {string|null} A short reason, or null when the target is reachable.
@@ -436,7 +442,6 @@ function normalizeIncludes(propName, raw, warnings) {
 function cloudUnreachable(target) {
   if (target.cloud_supported === false) return 'cloud_supported: false';
   if (target.config_scope === 'broker') return 'Cloud publishes no broker properties page';
-  if (target.config_scope === 'topic') return 'Cloud publishes no topic properties page';
   return null;
 }
 

package/tools/property-extractor/transformers.py

@@ -2124,6 +2124,32 @@ class EnterpriseTransformer:
             restricted_vals = self._extract_list_items(params[0]["value"])
             info["params"] = params[1:]
 
+        # --- restricted scalar ahead of the name, with a trailing vector ---
+        # Pattern: (restricted, name, description, meta, default, ..., vector)
+        # enterprise<enum_set_property<T>> takes this shape: http_authentication
+        # is ("OIDC", "http_authentication", ...) ending in its allowed values.
+        # Without this branch the trailing vector wins as sanctioned_only and
+        # the restricted value is left where the name belongs. Anchored on the
+        # member name, so a scalar is only taken as a restriction when the
+        # argument after it is the property's own name.
+        elif (
+            len(params) >= 5
+            and "std::vector" in str(params[-1]["value"])
+            and params[0]["type"] in ("true", "false", "integer_literal", "string_literal", "qualified_identifier")
+            and self._clean_value(params[1]["value"]) == info.get("name_in_file")
+            and self._clean_value(params[0]["value"]) != info.get("name_in_file")
+        ):
+            restricted_vals = [self._clean_value(params[0]["value"])]
+            if "enum" in str(info.get("type") or ""):
+                # The trailing vector is the enum's allowed values; keep it for
+                # TypeTransformer.
+                enterprise_constructor = "restricted_only"
+                info["params"] = params[1:]
+            else:
+                enterprise_constructor = "restricted_with_sanctioned"
+                sanctioned_vals = self._extract_list_items(params[-1]["value"])
+                info["params"] = params[1:-1]
+
         # --- sanctioned_only (vector form) ---
         elif len(params) >= 5 and "std::vector" in str(params[-1]["value"]):
             enterprise_constructor = "sanctioned_only"