@renzrollon/interlock 1.5.0 → 1.6.0

package/lib/receipt.mjs

@@ -87,6 +87,35 @@ export function tailFromManifest(manifest) {
   }
 }
 
+/**
+ * The merge-confidence block a receipt carries (design D11): the verdict and its
+ * shape, and no text. The close hands over a whole assessment whose reasons and
+ * evidence lines can quote a finding's title and the file it names, so this
+ * reduces it to the verdict, the score, the worst band, the counts, the ids of
+ * the signals that drove it and the flag names. `undefined` when the run did not
+ * assess — never a zero score and never a default verdict.
+ *
+ * Import-free like the rest of this module; `lib/run-log.mjs`'s whitelist bounds
+ * and validates the same fields again on the way to disk.
+ */
+function mergeConfidenceBlock(assessment) {
+  if (!assessment || typeof assessment !== 'object' || Array.isArray(assessment)) return undefined
+  const ids = list =>
+    (Array.isArray(list) ? list : [])
+      .map(entry => (entry && typeof entry === 'object' ? entry.id : entry))
+      .filter(id => typeof id === 'string' && id.length > 0)
+  return {
+    verdict: assessment.verdict,
+    score: assessment.score,
+    worstBand: assessment.worstBand,
+    counts: assessment.counts && typeof assessment.counts === 'object' ? { ...assessment.counts } : undefined,
+    driving: ids(assessment.driving),
+    flags: (Array.isArray(assessment.flags) ? assessment.flags : [])
+      .filter(f => f && typeof f === 'object' && typeof f.id === 'string' && typeof f.flag === 'string')
+      .map(f => ({ id: f.id, flag: f.flag }))
+  }
+}
+
 /**
  * The run's receipt payload: what this run observed about itself, in the field
  * names `lib/run-log.mjs`'s `run-receipt` whitelist copies by name.
@@ -108,7 +137,7 @@ export function tailFromManifest(manifest) {
  *   lanesStoppedByHost?: number, schemaResultsMissing?: number,
  *   toolsDeniedInLanes?: number, modelSubstitutions?: number,
  *   permissionPrompts?: number, autoModeDenials?: number,
- *   surface?: string, stateHome?: string
+ *   surface?: string, stateHome?: string, mergeConfidence?: object
  * }} input the six counts are passed only when the run observed agents at all
  *   (a host record or a sidecar); leaving one out records it as unobserved
  */
@@ -225,6 +254,7 @@ export function buildReceipt(input) {
     capExhaustedVerifications: closing ? closing.capExhaustedVerifications : undefined,
     unresolvedErrors: closing ? closing.unresolvedErrors : undefined,
     leftoverTaskIds: source.leftoverTaskIds,
+    mergeConfidence: mergeConfidenceBlock(source.mergeConfidence),
     halted: Boolean(summary.halted),
     haltReason: summary.halted || undefined,
     // Tri-state, and the reason the field is not just the sha: a run told not to
@@ -373,7 +403,8 @@ export function formatRunSummary({
   stateHome = undefined,
   push = null,
   unarchived = null,
-  resumeCard = null
+  resumeCard = null,
+  mergeConfidence = null
 } = {}) {
   const leftover = Array.isArray(leftoverTaskIds) ? leftoverTaskIds : []
   const lines = []
@@ -439,6 +470,19 @@ export function formatRunSummary({
           (unconfirmed ? ` — ${unconfirmed} unconfirmed, see conformance.md` : '')
       )
     }
+    // The living requirements, counted on their own terms beside the scenarios
+    // (design D5). Absent when the count is: a run that was not asked about
+    // them, or whose handoff did not report, prints nothing rather than 0/0.
+    const requirementsChecked = summary.handoff.requirementsChecked
+    if (Number.isFinite(requirementsChecked) && requirementsChecked > 0) {
+      const unconfirmedReqs = Number.isFinite(summary.handoff.requirementsUnconfirmed)
+        ? summary.handoff.requirementsUnconfirmed
+        : 0
+      lines.push(
+        `  living requirements: ${requirementsChecked - unconfirmedReqs}/${requirementsChecked} confirmed` +
+          (unconfirmedReqs ? ` — ${unconfirmedReqs} unconfirmed, see conformance.md` : '')
+      )
+    }
   }
   if (summary.commit && summary.commit.ok) lines.push(`  commit: ${summary.commit.sha || 'created'}`)
   for (const note of summary.notes || []) lines.push(`  ${note}`)
@@ -462,6 +506,32 @@ export function formatRunSummary({
     lines.push(`  state home: ${stateHome}`)
   }
 
+  // The merge-confidence block (design D10), on a completed run only: a halt
+  // never assessed, and a line here would read as if it had. The close hands
+  // over the headline already rendered and the ids already grouped, so this
+  // module derives neither. A group prints only when it has an entry; reasons
+  // and evidence stay in the assessment file.
+  if (!summary.halted && mergeConfidence && typeof mergeConfidence === 'object') {
+    const mc = mergeConfidence
+    if (typeof mc.headline === 'string' && mc.headline.length > 0) {
+      lines.push(mc.headline)
+      const groups = mc.groups && typeof mc.groups === 'object' ? mc.groups : {}
+      const rows = [
+        ['needs a fix', groups.fix],
+        ['needs a person', groups.person],
+        ['needs more evidence', groups.evidence]
+      ]
+      for (const [label, ids] of rows) {
+        if (Array.isArray(ids) && ids.length) lines.push(`  ${label}: ${ids.join(', ')}`)
+      }
+      const flagged = (Array.isArray(mc.flags) ? mc.flags : []).filter(f => f && f.id && f.flag)
+      if (flagged.length) lines.push(`  flags: ${flagged.map(f => `${f.id} ${f.flag}`).join(', ')}`)
+      if (typeof mc.assessmentPath === 'string' && mc.assessmentPath.length > 0) {
+        lines.push(`  assessment: ${mc.assessmentPath}`)
+      }
+    }
+  }
+
   // The push outcome (design D5): a row only when a push was actually
   // attempted — an unconfigured relay is an optional feature left off, not a
   // degraded run, so it prints nothing here.

package/lib/review-core.mjs

@@ -32,12 +32,15 @@ import { existsSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { LIMITS } from './limits.mjs'
-import { SEVERITIES, TOLERANCE_BAND, applyToleranceBand } from './findings.mjs'
+import { SEVERITIES, TOLERANCE_BAND, applyToleranceBand, normalizeSeverity } from './findings.mjs'
 // The locator vocabulary lives in one module because a second surface now
 // audits citations the same way (`auditHandoffEvidence` in lib/waves.mjs). Two
 // definitions of "what a locator looks like" drift silently, each still passing
 // its own tests. See lib/locators.mjs for what is shared and what is not.
 import { CITATION_TOKEN, canonicalizePath, citesLineIn, diffIndex } from './locators.mjs'
+// The one canonical requirement-heading form (design D1): a citation and the
+// spec text it names are compared on `requirementKey`, never on raw spelling.
+import { requirementKey } from './spec-text.mjs'
 
 // Accept the same three input shapes `evaluateGate` accepts (bare array, one
 // `{dimension, findings}` object, or an array of those). `applyToleranceBand`
@@ -205,11 +208,16 @@ function numericScore(value) {
  *   `REVIEW.md`); a finding whose canonical file lies at or under one is dropped
  *   BEFORE the band is applied, so exclusions shrink the input but never alter
  *   the arithmetic on what remains (add-interlock-review-policy spec §5).
+ *   `requirementHeadings` maps each cited spec path (canonical) to that file's
+ *   requirement keys, or to `{ unreadable: reason }`; with it, a finding's
+ *   `requirement` citation is shape-checked (see `checkRequirementCitation`).
+ *   A failed check is reported under `anomalies.requirementCitations` and
+ *   changes nothing about how the finding is adjudicated.
  * @returns {{
  *   surviving: Array, dismissed: Array, droppedByQuality: Array, droppedByPolicy: Array,
  *   counts: {raised: number, dismissed: number, droppedByQuality: number, droppedByPolicy: number, surviving: number},
  *   dimensionStats: Object<string, {raised: number, surviving: number}>,
- *   anomalies: {orphanVerdicts: Array, malformedVerdicts: Array}
+ *   anomalies: {orphanVerdicts: Array, malformedVerdicts: Array, requirementCitations: Array}
  * }}
  */
 export function resolveReview(findings, verdicts, opts = {}) {
@@ -233,6 +241,24 @@ export function resolveReview(findings, verdicts, opts = {}) {
     else all.push(finding)
   }
 
+  // Requirement citations are checked on every finding that reaches
+  // adjudication, before survival is decided and without feeding into it: the
+  // check is a SHAPE check, a broken citation must never delete a real defect,
+  // and whether the cited requirement forbids the diff is the skeptics' question.
+  const requirementCitations = []
+  for (const finding of all) {
+    const problem = checkRequirementCitation(finding, opts.requirementHeadings)
+    if (problem) {
+      requirementCitations.push({
+        dimension: finding.dimension || 'unknown',
+        file: typeof finding.file === 'string' ? finding.file : null,
+        title: titleOf(finding),
+        requirement: typeof finding.requirement === 'string' ? finding.requirement : null,
+        problem
+      })
+    }
+  }
+
   // Index verdicts by what they claim to adjudicate: title, plus file when the
   // skeptic named one.
   const byKey = new Map()
@@ -354,7 +380,7 @@ export function resolveReview(findings, verdicts, opts = {}) {
     droppedByPolicy,
     counts,
     dimensionStats,
-    anomalies: { orphanVerdicts, malformedVerdicts }
+    anomalies: { orphanVerdicts, malformedVerdicts, requirementCitations }
   }
 }
 
@@ -375,12 +401,82 @@ export function resolveReview(findings, verdicts, opts = {}) {
  * root) is not excluded: an exclusion is an affirmative scope decision, and a
  * path we cannot place cannot be affirmatively matched.
  */
-function pathExcludedBy(file, canonicalPrefix) {
+export function pathExcludedBy(file, canonicalPrefix) {
   const canonicalFile = canonicalizePath(file)
   if (!canonicalFile) return false
   return canonicalFile === canonicalPrefix || canonicalFile.startsWith(canonicalPrefix + '/')
 }
 
+const SPEC_CITATION_PATH = /^openspec\/specs\/.+\/spec\.md$/
+
+// A cited file's entry in `requirementHeadings`: a Map or a plain object.
+function headingsEntry(headings, path) {
+  if (headings instanceof Map) return headings.get(path)
+  if (headings && typeof headings === 'object') {
+    return Object.prototype.hasOwnProperty.call(headings, path) ? headings[path] : undefined
+  }
+  return undefined
+}
+
+/**
+ * The shape check on one finding's requirement citation, or null when it passes
+ * (or there is nothing to check).
+ *
+ * A citation is `openspec/specs/<capability>/spec.md#<heading>`. Three checks,
+ * in order: the path is canonical, under `openspec/specs/` and names a
+ * `spec.md`; the file was read at the base (`requirementHeadings` has it, and it
+ * is not `{ unreadable }`); the heading, on `requirementKey`, names a
+ * requirement in it. Case is part of the heading: a different case is a
+ * different requirement, as OpenSpec itself reads it.
+ *
+ * A `domain` blocker with no citation is also a problem, because contradicting a
+ * requirement in force is the only blocker that dimension raises. A `domain`
+ * warning without one is not: behaviour no requirement describes has nothing to
+ * cite.
+ */
+function checkRequirementCitation(finding, headings) {
+  const cited = finding.requirement
+  const present = typeof cited === 'string' ? cited.trim() !== '' : cited !== undefined && cited !== null
+  if (!present) {
+    // On the canonical severity, as the gate and the merge verdict read it:
+    // "BLOCKER" blocks there, so it is a blocker here.
+    return finding.dimension === 'domain' && normalizeSeverity(finding.severity) === 'blocker'
+      ? 'domain blocker cites no requirement'
+      : null
+  }
+  if (typeof cited !== 'string') return 'requirement citation is not a string'
+
+  const hash = cited.indexOf('#')
+  if (hash === -1) {
+    return `requirement citation "${cited}" has no #heading naming a requirement`
+  }
+  const path = canonicalizePath(cited.slice(0, hash).trim())
+  if (!path || !SPEC_CITATION_PATH.test(path)) {
+    return (
+      `requirement citation "${cited.slice(0, hash).trim()}" is not a canonical ` +
+      `openspec/specs/<capability>/spec.md path`
+    )
+  }
+
+  const entry = headingsEntry(headings, path)
+  if (headings === undefined || headings === null) {
+    return `unchecked: ${path} was not read, so the cited requirement could not be checked`
+  }
+  if (entry === undefined || entry === null) {
+    return `unchecked: ${path} was not among the spec files read at the base`
+  }
+  if (!Array.isArray(entry) && !(entry instanceof Set)) {
+    const reason = typeof entry.unreadable === 'string' && entry.unreadable ? entry.unreadable : 'unreadable'
+    return `unchecked: ${path} could not be read at the base: ${reason}`
+  }
+  const wanted = requirementKey(cited.slice(hash + 1))
+  const keys = [...entry].map(requirementKey)
+  if (!wanted || !keys.includes(wanted)) {
+    return `names no requirement in ${path}: "${cited.slice(hash + 1).trim()}"`
+  }
+  return null
+}
+
 /** Human-readable review summary. */
 export function formatReview(result) {
   const { raised, dismissed, droppedByQuality, droppedByPolicy, surviving, dismissalsRejected } =
@@ -416,6 +512,11 @@ export function formatReview(result) {
   }
 
   const { orphanVerdicts, malformedVerdicts } = result.anomalies
+  for (const c of result.anomalies.requirementCitations || []) {
+    const where = c.file ? `${c.file} — ` : ''
+    const cite = c.requirement ? ` [${c.requirement}]` : ''
+    lines.push(`  ANOMALY: requirement citation on ${where}${c.title || '(untitled)'}: ${c.problem}${cite}`)
+  }
   if (orphanVerdicts.length) {
     const titles = [...new Set(orphanVerdicts.map(v => v.findingTitle))]
     lines.push(`  ANOMALY: ${orphanVerdicts.length} verdict(s) matched no finding: ${titles.join(', ')}`)
@@ -439,7 +540,7 @@ export function formatReview(result) {
 /** The one location that is read as policy: the repository root. */
 export const REVIEW_POLICY_FILE = 'REVIEW.md'
 
-const EMPTY_POLICY = () => ({ prose: '', excludePaths: [], owner: null, problems: [] })
+const EMPTY_POLICY = () => ({ prose: '', excludePaths: [], humanPaths: [], owner: null, problems: [] })
 
 // The only recognized front-matter key. The band and nit cap deliberately are
 // NOT here — they live in the CLI so they are not re-argued (spec §5). Any other
@@ -465,6 +566,28 @@ function normalizeHeading(text) {
 
 const PROSE_HEADINGS = new Set(['owner', 'what important means', 'exclusions rationale'])
 const EXCLUSIONS_HEADING = 'do not report'
+const HUMAN_REVIEW_HEADING = 'always human review'
+
+// The two path-list sections share one grammar, one canonical form and one set
+// of problem wordings; only the nouns differ. `humanPaths` is scope, read by the
+// merge verdict alone — it never reaches `resolveReview` (design D3).
+const EXCLUSIONS_SECTION = {
+  label: 'Do Not Report',
+  noPaths: 'no exclusions applied',
+  entry: 'exclusion',
+  nothing: 'excludes nothing'
+}
+const HUMAN_REVIEW_SECTION = {
+  label: 'Always Human Review',
+  noPaths: 'no paths declared',
+  entry: 'entry',
+  nothing: 'declares nothing'
+}
+
+// What marks a list item as a pattern rather than a path (design D11 of
+// label-and-harden-the-merge-verdict). Only these two: brackets and braces
+// occur in real paths, such as a route directory.
+const PATTERN_ITEM = /[*?]/
 
 /**
  * Read the repo-root `REVIEW.md` and parse it into a policy object.
@@ -475,7 +598,7 @@ const EXCLUSIONS_HEADING = 'do not report'
  * run proceeds under default policy rather than parsing unbounded input.
  *
  * @param {string} repoRoot repository root to look under (defaults to cwd)
- * @returns {{prose: string, excludePaths: string[], owner: string|null, problems: string[]}}
+ * @returns {{prose: string, excludePaths: string[], humanPaths: string[], owner: string|null, problems: string[]}}
  */
 export function readReviewPolicy(repoRoot) {
   const root = typeof repoRoot === 'string' && repoRoot.trim() ? repoRoot : '.'
@@ -509,7 +632,7 @@ export function readReviewPolicy(repoRoot) {
 }
 
 /**
- * Parse `REVIEW.md` text into `{ prose, excludePaths, owner, problems }`.
+ * Parse `REVIEW.md` text into `{ prose, excludePaths, humanPaths, owner, problems }`.
  *
  * Each half is validated independently (design.md D3): a broken exclusions block
  * does not stop valid prose from being returned, and a broken prose section does
@@ -561,11 +684,17 @@ export function parseReviewPolicy(text) {
   for (const section of sections) {
     const norm = normalizeHeading(section.heading)
     if (norm === EXCLUSIONS_HEADING) {
-      const { paths, problems } = parseExclusions(section.content)
+      const { paths, problems } = parsePathList(section.content, EXCLUSIONS_SECTION)
       policy.excludePaths.push(...paths)
       policy.problems.push(...problems)
       continue
     }
+    if (norm === HUMAN_REVIEW_HEADING) {
+      const { paths, problems } = parsePathList(section.content, HUMAN_REVIEW_SECTION)
+      policy.humanPaths.push(...paths)
+      policy.problems.push(...problems)
+      continue
+    }
     if (PROSE_HEADINGS.has(norm)) {
       const content = section.content.trim()
       if (norm === 'owner') {
@@ -589,6 +718,7 @@ export function parseReviewPolicy(text) {
   policy.owner = owner
   // `./dist` and `dist/` canonicalize to one prefix; keep it once.
   policy.excludePaths = [...new Set(policy.excludePaths)]
+  policy.humanPaths = [...new Set(policy.humanPaths)]
   return policy
 }
 
@@ -644,22 +774,32 @@ function splitSections(body) {
 }
 
 /**
- * Parse a `## Do Not Report` block into canonical excluded prefixes.
+ * Parse a path-list section (`## Do Not Report`, `## Always Human Review`) into
+ * canonical path prefixes.
  *
  * Entries are markdown list items (`- path` / `* path`). Each is canonicalized
  * with the same `canonicalizePath` findings go through, so a finding cannot slip
- * an exclusion on an alternate spelling; an entry that cannot be canonicalized
- * (absolute, escaping the root) excludes nothing and is reported (spec §3, task
- * 1.3). A structurally broken block — a fenced code block, or content with no
- * list entries at all — is reported unusable as a whole and yields no
- * exclusions, rather than being half-guessed (spec §4, the partially-valid file).
+ * past a listed prefix on an alternate spelling; an entry that cannot be
+ * canonicalized (absolute, escaping the root) declares nothing and is reported
+ * (spec §3, task 1.3). An entry shaped like a survival threshold (`- nitCap: 0`)
+ * is reported and never read as a path, in either section. So is an entry that
+ * holds `*` or `?`: the lists hold prefixes, not patterns, and a pattern read as
+ * a literal path matches no file, so `- src/**` would list nothing and say
+ * nothing. Square brackets and braces are characters a path may hold
+ * (`app/[id]/`) and are read as part of it. A structurally broken
+ * block — a fenced code block, or content with no list entries at all — is
+ * reported unusable as a whole and yields no paths, rather than being
+ * half-guessed (spec §4, the partially-valid file).
+ *
+ * @param {string} content the section body
+ * @param {{label: string, noPaths: string, entry: string, nothing: string}} section
  */
-function parseExclusions(content) {
+function parsePathList(content, section) {
   const problems = []
   if (/^\s*```/m.test(content)) {
     problems.push(
-      `the "Do Not Report" block contains a code fence and could not be parsed as a path list; ` +
-        `no exclusions applied`
+      `the "${section.label}" block contains a code fence and could not be parsed as a path list; ` +
+        `${section.noPaths}`
     )
     return { paths: [], problems }
   }
@@ -681,32 +821,95 @@ function parseExclusions(content) {
   // Non-blank content but not a single list item: the block is not a path list.
   if (!entries.length) {
     problems.push(
-      `the "Do Not Report" block has content but no path list items (\`- path\`); ` +
-        `no exclusions applied`
+      `the "${section.label}" block has content but no path list items (\`- path\`); ` +
+        `${section.noPaths}`
     )
     return { paths: [], problems }
   }
   if (sawNonEntry) {
     problems.push(
-      `the "Do Not Report" block mixes list items with non-list text; only the \`- path\` items ` +
+      `the "${section.label}" block mixes list items with non-list text; only the \`- path\` items ` +
         `were read`
     )
   }
 
   const paths = []
   for (const entry of entries) {
+    if (BAND_KEY_LINE.test(entry)) {
+      problems.push(
+        `"${section.label}" item "${entry}" looks like a survival threshold — the band and nit cap ` +
+          `live in the CLI, not REVIEW.md; ignored, not read as a path`
+      )
+      continue
+    }
+    if (PATTERN_ITEM.test(entry)) {
+      // The problem names its section in the form the threshold-shaped one
+      // does: the merge verdict tells the two sections' problems apart by it.
+      problems.push(
+        `"${section.label}" item "${entry}" is a pattern, and only a path or a directory prefix is read ` +
+          `here; ignored, not read as a path (list the directory instead, such as \`src/\`)`
+      )
+      continue
+    }
     const canonical = canonicalizePath(stripQuotes(entry.replace(/\/+$/, '')))
     if (canonical) paths.push(canonical)
-    else problems.push(`exclusion "${entry}" is not a repo-relative path and excludes nothing`)
+    else problems.push(`${section.entry} "${entry}" is not a repo-relative path and ${section.nothing}`)
   }
   return { paths, problems }
 }
 
+// Line endings and trailing newlines are not a policy difference.
+function normalizePolicyText(text) {
+  if (typeof text !== 'string') return ''
+  const lf = text.replace(/\r\n?/g, '\n')
+  return lf.trim() ? lf.replace(/\s+$/, '') + '\n' : ''
+}
+
+/**
+ * Compose the policy a review is judged by from two copies of `REVIEW.md`.
+ *
+ * The trust split `docs/12` draws decides where each part comes from. The two
+ * path lists are enforced, so a change must not edit the copy applied to it:
+ * they come from `base`. The prose is advice that cannot relax the gate, so it
+ * (and the owner it names) comes from `working` — an uncommitted edit still
+ * reaches the reviewer. `differsFromBase` says the two copies differ, so a
+ * caller can speak it; it is the only thing that makes an edited policy visible.
+ *
+ * Pure: each copy is `{ text, policy }` (`policy` as `parseReviewPolicy`
+ * returns it, `text` carried so line endings can be compared) or `null` for an
+ * absent file, which is the empty policy with no problem — absence is the off
+ * switch. Reading a file at a ref is I/O and lives with the caller.
+ *
+ * @param {{working: ?{text: string, policy: object}, base: ?{text: string, policy: object}, ref: ?string}} input
+ * @returns {{prose: string, owner: ?string, excludePaths: string[], humanPaths: string[],
+ *   problems: string[], listsFrom: ?string, differsFromBase: boolean}}
+ */
+export function composePolicy({ working = null, base = null, ref = null } = {}) {
+  const workingPolicy = working?.policy ?? EMPTY_POLICY()
+  const basePolicy = base?.policy ?? EMPTY_POLICY()
+  const baseLabel = ref ? `(${ref})` : '(base)'
+  const problems = [
+    ...(workingPolicy.problems || []).map(p => `${p} (working tree)`),
+    ...(basePolicy.problems || []).map(p => `${p} ${baseLabel}`)
+  ]
+  return {
+    prose: workingPolicy.prose || '',
+    owner: workingPolicy.owner ?? null,
+    excludePaths: [...(basePolicy.excludePaths || [])],
+    humanPaths: [...(basePolicy.humanPaths || [])],
+    problems,
+    listsFrom: ref ?? null,
+    differsFromBase: normalizePolicyText(working?.text) !== normalizePolicyText(base?.text)
+  }
+}
+
 /** Human-readable dump of a parsed policy, for `interlock review-policy`. */
 export function formatReviewPolicy(policy) {
   const lines = []
   lines.push(`REVIEW POLICY — ${policy.owner ? `owner: ${policy.owner}` : 'no owner declared'}`)
   lines.push(`  exclusions: ${policy.excludePaths.length ? policy.excludePaths.join(', ') : '(none)'}`)
+  const humanPaths = policy.humanPaths || []
+  lines.push(`  human-review: ${humanPaths.length ? humanPaths.join(', ') : '(none)'}`)
   lines.push(`  prose: ${policy.prose ? `${policy.prose.length} char(s)` : '(none)'}`)
   for (const problem of policy.problems) lines.push(`  PROBLEM: ${problem}`)
   return lines.join('\n') + '\n'

package/lib/risk.mjs

@@ -45,6 +45,14 @@ const RANK = { low: 0, medium: 1, high: 2, critical: 3 }
 // to strict (['low']) or loose (['low','medium','high']) is this one edit.
 export const CONTINUITY_ALLOWED_CLASSES = Object.freeze(['low', 'medium'])
 
+// The classes the merge verdict (`lib/merge-confidence.mjs`, signal
+// `risk.class`) reads green; anything above them is amber, marked as needing a
+// person, and never red. The same two classes as continuity today, but a
+// separate constant on purpose: skipping the spec checkpoint and merging a pull
+// request are different decisions, and re-tuning one must not silently move the
+// other. The two policies may diverge.
+export const MERGE_ALLOWED_CLASSES = Object.freeze(['low', 'medium'])
+
 // Where an input with no usable signal at all lands. Deliberately outside
 // CONTINUITY_ALLOWED_CLASSES: "we could not tell" must stop the machine.
 export const UNCLASSIFIABLE_CLASS = 'high'

package/lib/run-log.mjs

@@ -92,6 +92,13 @@ export const MODEL_SCOPES = Object.freeze(['turns', 'session'])
  */
 export const RUN_SURFACES = Object.freeze(['main', 'linked-worktree', 'lane-worktree', 'unknown'])
 
+/**
+ * The three words a merge verdict may be recorded as on a receipt (design D11).
+ * Mirrors `lib/merge-confidence.mjs`'s published verdicts; restated here because
+ * this module's whitelist is the place a stray word is refused.
+ */
+export const MERGE_VERDICTS = Object.freeze(['MERGE', 'HUMAN', 'BLOCK'])
+
 /** The two modes a run starts in — mirrors `lib/outcomes.mjs`'s `MODES`. */
 export const RUN_MODES = Object.freeze(['checkpoint', 'continue'])
 
@@ -390,6 +397,39 @@ function agentKind(value) {
   return enumOf(AGENT_KINDS, value, 'other')
 }
 
+// The merge-confidence block (design D11), built field by field. The source at
+// the close is a whole assessment whose reasons and evidence lines can quote a
+// finding's title and the file it names, so nothing is spread and the only
+// strings kept are the verdict (against the three published words), the band,
+// signal ids and flag names, each bounded. `null` when the receipt carries no
+// block: a run that never assessed is not a run with a zero score.
+const MERGE_COUNT_KEYS = Object.freeze(['gating', 'clean', 'green', 'amber', 'red', 'unobserved', 'flagged'])
+
+function mergeCounts(value) {
+  const source = isObject(value) ? value : {}
+  const out = {}
+  for (const key of MERGE_COUNT_KEYS) out[key] = nullableCount(source[key])
+  return out
+}
+
+function mergeConfidenceBlock(value) {
+  if (!isObject(value)) return null
+  return {
+    verdict: enumOf(MERGE_VERDICTS, value.verdict, null),
+    score: nullableCount(value.score),
+    worstBand: nullableText(value.worstBand, MAX_NAME),
+    counts: mergeCounts(value.counts),
+    driving: Array.isArray(value.driving)
+      ? value.driving.filter(v => typeof v === 'string' && v.trim()).map(v => text(v, MAX_NAME))
+      : [],
+    flags: Array.isArray(value.flags)
+      ? value.flags
+          .filter(f => isObject(f) && typeof f.id === 'string' && f.id.trim() && typeof f.flag === 'string' && f.flag.trim())
+          .map(f => ({ id: text(f.id, MAX_NAME), flag: text(f.flag, MAX_NAME) }))
+      : []
+  }
+}
+
 function stringArray(value, max = MAX_TEXT) {
   if (!Array.isArray(value)) return []
   return value.filter(v => typeof v === 'string').map(v => text(v, max))
@@ -587,6 +627,10 @@ const TYPE_FIELDS = {
     capExhaustedVerifications: source => nullableCount(source.capExhaustedVerifications),
     unresolvedErrors: source => nullableCount(source.unresolvedErrors),
     leftoverTaskIds: source => stringArray(source.leftoverTaskIds, MAX_NAME),
+    // The merge verdict and its shape, no text (design D11): ids, counts and
+    // flag names only. The receipt module hands over a block already reduced;
+    // this whitelist is what holds if a caller hands a whole assessment.
+    mergeConfidence: source => mergeConfidenceBlock(source.mergeConfidence),
     // Output-token spend, per wave and for the run. The figure is a cumulative
     // process-wide delta over the wave's span, so it includes the
     // orchestrator's own turns as well as the implementers' — it is the wave's