@renzrollon/interlock 1.5.0 → 1.6.0

package/lib/spec-audit.mjs

@@ -0,0 +1,232 @@
+// The spec audit: what a reviewer can rely on a living spec to say.
+//
+// Pure over gathered inputs — no fs, no git, no clock. The CLI walks
+// `openspec/specs/**/spec.md`, reads the graph, and hands this module the texts,
+// the reliable spec-to-file edges, the broken links and the graph's coverable
+// files. Every measure is defined once here, by a rule the `spec/spec-audit`
+// spec states, so a figure can be repeated and a second reader gets the same
+// number. The audit judges nothing and blocks nothing: a measure it could not
+// take is absent with its reason, never zero. design D5 of
+// judge-against-base-and-living-specs.
+
+import { parseSpec, capabilityOf } from './spec-text.mjs'
+
+/** Whole-word bound or prohibition terms, case-insensitive. `nevertheless` is not `never`. */
+const BOUND = /\b(?:shall not|must not|never|at most|at least|exactly once)\b/i
+const NORMATIVE = /\b(?:SHALL|MUST)\b/
+const INLINE_CODE = /`[^`\n]*`/g
+// A standalone number: not welded to a word (`utf8`), not part of a dotted
+// version or a decimal tail (`1.5.0`).
+const NUMBER = /(?<![\w.])\d+(?:\.\d+)?(?![\w]|\.\d)/g
+const LIST_MARKER = /^\s*\d+[.)]\s+/
+const FENCE = /^\s*(```|~~~)/
+
+const FLAG_ORDER = ['no-bound', 'no-failure-scenario', 'no-edge-case']
+
+const startsWith = (title, word) => new RegExp(`^${word}`, 'i').test(String(title ?? '').trim())
+
+/** The measures of one parsed spec. */
+function measure(path, parsed) {
+  const c = {
+    capability: capabilityOf(path) ?? path,
+    path,
+    purpose: parsed.purpose !== null,
+    requirements: parsed.requirements.length,
+    nonNormative: [],
+    scenarios: 0,
+    missingGiven: 0,
+    missingWhen: 0,
+    missingThen: 0,
+    failure: 0,
+    edgeCase: 0,
+    unclassified: 0,
+    boundLines: 0,
+    numericLiterals: [],
+    flags: [],
+    links: null
+  }
+
+  for (const req of parsed.requirements) {
+    if (!NORMATIVE.test(`${req.heading}\n${req.prose}`)) c.nonNormative.push(req.heading)
+
+    for (const s of req.scenarios) {
+      c.scenarios++
+      if (!s.given) c.missingGiven++
+      if (!s.when) c.missingWhen++
+      if (!s.then) c.missingThen++
+      if (startsWith(s.title, 'failure')) c.failure++
+      else if (startsWith(s.title, 'edge case')) c.edgeCase++
+      else if (!startsWith(s.title, 'happy path')) c.unclassified++
+    }
+
+    // `text` opens on the heading line, so index i is line `req.line + i`.
+    // Prose is everything before the first scenario heading.
+    const lines = req.text.split('\n')
+    const proseEnd = req.scenarios.length ? req.scenarios[0].line - req.line : lines.length
+    let inFence = false
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      if (BOUND.test(line)) c.boundLines++
+      if (FENCE.test(line)) {
+        inFence = !inFence
+        continue
+      }
+      if (i === 0 || i >= proseEnd || inFence) continue
+      const bare = line.replace(INLINE_CODE, ' ').replace(LIST_MARKER, '')
+      for (const m of bare.matchAll(NUMBER)) {
+        c.numericLiterals.push({ spec: path, line: req.line + i, value: Number(m[0]) })
+      }
+    }
+  }
+
+  if (c.boundLines === 0) c.flags.push('no-bound')
+  if (c.failure === 0) c.flags.push('no-failure-scenario')
+  if (c.edgeCase === 0) c.flags.push('no-edge-case')
+  c.flags.sort((a, b) => FLAG_ORDER.indexOf(a) - FLAG_ORDER.indexOf(b))
+  return c
+}
+
+/**
+ * @param {{
+ *   specs: Array<{ path: string, text?: string, error?: string }>,
+ *   edges?: Array<{ source_file?: string, target?: string }>|null,
+ *   graphReason?: string|null,
+ *   broken?: Array<{ spec: string, file: string }>,
+ *   graphFiles?: string[]
+ * }} input
+ */
+export function auditSpecs(input = {}) {
+  const specs = Array.isArray(input.specs) ? input.specs : []
+  const edges = Array.isArray(input.edges) ? input.edges : null
+  const broken = Array.isArray(input.broken) ? input.broken : []
+  const graphFiles = Array.isArray(input.graphFiles) ? input.graphFiles : []
+
+  const graph = { available: edges !== null, reason: null, unspecified: null }
+  if (!graph.available) {
+    graph.reason = input.graphReason || 'no graph is available'
+  }
+
+  const unreadable = []
+  const capabilities = []
+  for (const s of specs) {
+    if (!s || typeof s.path !== 'string') continue
+    if (typeof s.text !== 'string') {
+      unreadable.push({ path: s.path, reason: s.error ? String(s.error) : 'the file could not be read' })
+      continue
+    }
+    capabilities.push(measure(s.path, parseSpec(s.text)))
+  }
+  capabilities.sort((a, b) => a.capability.localeCompare(b.capability))
+
+  const coverage = { specs: capabilities.length, corpus: specs.length }
+
+  if (specs.length === 0) {
+    return {
+      absent: true,
+      reason: 'no living spec exists — openspec/specs/ is missing or holds no spec.md',
+      coverage,
+      unreadable,
+      capabilities: [],
+      totals: null,
+      graph
+    }
+  }
+
+  if (edges) {
+    const bySpec = new Map()
+    const named = new Set()
+    for (const e of edges) {
+      const spec = e && typeof e.source_file === 'string' ? e.source_file : null
+      const target = e && typeof e.target === 'string' ? e.target : ''
+      if (!spec || !target.startsWith('file:')) continue
+      const file = target.slice('file:'.length)
+      if (!bySpec.has(spec)) bySpec.set(spec, new Set())
+      bySpec.get(spec).add(file)
+      named.add(file)
+    }
+    for (const c of capabilities) {
+      const missing = [...new Set(broken.filter(b => b && b.spec === c.path).map(b => b.file))].sort()
+      c.links = { files: (bySpec.get(c.path) ?? new Set()).size, missing }
+    }
+    const files = [...new Set(graphFiles)].filter(f => !named.has(f)).sort()
+    const total = new Set(graphFiles).size
+    graph.unspecified = {
+      count: files.length,
+      total,
+      percent: total ? Math.round((files.length / total) * 100) : 0,
+      files
+    }
+  }
+
+  const sum = key => capabilities.reduce((n, c) => n + c[key], 0)
+  const totals = {
+    specs: capabilities.length,
+    requirements: sum('requirements'),
+    nonNormative: capabilities.reduce((n, c) => n + c.nonNormative.length, 0),
+    scenarios: sum('scenarios'),
+    missingGiven: sum('missingGiven'),
+    missingWhen: sum('missingWhen'),
+    missingThen: sum('missingThen'),
+    failure: sum('failure'),
+    edgeCase: sum('edgeCase'),
+    unclassified: sum('unclassified'),
+    boundLines: sum('boundLines'),
+    numericLiterals: capabilities.reduce((n, c) => n + c.numericLiterals.length, 0),
+    flagged: capabilities.filter(c => c.flags.length > 0).length
+  }
+
+  return { absent: false, reason: null, coverage, unreadable, capabilities, totals, graph }
+}
+
+/** The human report. Every measure not taken is named with its reason. */
+export function formatSpecAudit(report) {
+  const out = ['SPEC AUDIT']
+  if (report.absent) {
+    out.push(`  not measured: ${report.reason}`)
+    for (const u of report.unreadable) out.push(`  unreadable: ${u.path} (${u.reason})`)
+    return out.join('\n')
+  }
+
+  const { coverage, totals, graph } = report
+  out.push(`  covers ${coverage.specs} of ${coverage.corpus} spec${coverage.corpus === 1 ? '' : 's'}`)
+  for (const u of report.unreadable) out.push(`  unreadable, left out of the totals: ${u.path} (${u.reason})`)
+
+  out.push(
+    `  requirements ${totals.requirements} (${totals.nonNormative} without SHALL or MUST)` +
+      `, scenarios ${totals.scenarios}` +
+      ` (no GIVEN ${totals.missingGiven}, no WHEN ${totals.missingWhen}, no THEN ${totals.missingThen})`
+  )
+  out.push(
+    `  failure ${totals.failure}, edge case ${totals.edgeCase}, untitled by kind ${totals.unclassified}` +
+      `, bound lines ${totals.boundLines}, numeric literals ${totals.numericLiterals}`
+  )
+
+  const flagged = report.capabilities.filter(c => c.flags.length > 0)
+  out.push('', `FLAGS — ${flagged.length} of ${report.capabilities.length} capabilities`)
+  if (!flagged.length) out.push('  none')
+  for (const c of flagged) out.push(`  ${c.capability}  ${c.flags.join(' ')}`)
+
+  const nonNormative = report.capabilities.filter(c => c.nonNormative.length > 0)
+  if (nonNormative.length) {
+    out.push('', 'REQUIREMENTS WITH NEITHER SHALL NOR MUST')
+    for (const c of nonNormative) for (const h of c.nonNormative) out.push(`  ${c.path}  ${h}`)
+  }
+
+  const literals = report.capabilities.flatMap(c => c.numericLiterals)
+  out.push('', `NUMERIC LITERALS IN REQUIREMENT PROSE — ${literals.length}, for a person to classify`)
+  for (const n of literals) out.push(`  ${n.spec}:${n.line}  ${n.value}`)
+
+  out.push('')
+  if (!graph.available) {
+    out.push(`FILE LINKS — not measured: ${graph.reason}`)
+    out.push(`UNSPECIFIED SOURCE — not measured: ${graph.reason}`)
+  } else {
+    const gone = report.capabilities.filter(c => c.links && c.links.missing.length > 0)
+    out.push(`FILE LINKS — ${gone.length} capabilit${gone.length === 1 ? 'y' : 'ies'} name a file that no longer exists`)
+    for (const c of gone) for (const f of c.links.missing) out.push(`  ${c.path}  →  ${f}  (missing)`)
+    const u = graph.unspecified
+    out.push(`UNSPECIFIED SOURCE — ${u.count} of ${u.total} coverable files (${u.percent}%) are named by no living spec`)
+    for (const f of u.files) out.push(`  ${f}`)
+  }
+  return out.join('\n')
+}

package/lib/spec-coverage.mjs

@@ -0,0 +1,105 @@
+// The facts behind the `spec.coverage` signal: which source files a diff adds,
+// edits and keeps, and whether a living spec or one of the change's own delta
+// specs names them.
+//
+// Pure. Spec text and path lists in, a plain structure out: no graph (it is
+// gitignored and absent in CI), no git and no disk. A file is named when a spec
+// mentions its repository-relative path by the one rule the graph's extractor
+// shares (`specMentionedPaths`), compared on the canonical path form, and only
+// coverable source is judged — a test, a configuration file or a document having
+// no spec is not a gap. The gather (`lib/merge-evidence.mjs`) reads the texts;
+// `readSpecCoverage` in `lib/merge-confidence.mjs` judges the facts.
+// design D7 and D8 of complete-and-record-the-merge-verdict.
+
+import { isCoverableSource } from './artifacts.mjs'
+import { canonicalizePath } from './risk.mjs'
+import { specMentionedPaths } from './spec-text.mjs'
+
+/** The canonical paths a list of `{ path, text }` specs mention. */
+function mentionsOf(specs) {
+  const out = new Set()
+  for (const spec of Array.isArray(specs) ? specs : []) {
+    for (const mentioned of specMentionedPaths(spec?.text)) {
+      const canonical = canonicalizePath(mentioned)
+      if (canonical) out.add(canonical)
+    }
+  }
+  return out
+}
+
+/** The canonical, coverable paths of a list, first-seen order, each once. */
+function coverable(paths) {
+  const out = []
+  const seen = new Set()
+  for (const entry of Array.isArray(paths) ? paths : []) {
+    const canonical = canonicalizePath(entry)
+    if (!canonical || seen.has(canonical) || !isCoverableSource(canonical)) continue
+    seen.add(canonical)
+    out.push(canonical)
+  }
+  return out
+}
+
+/**
+ * @param {object} input
+ * @param {string[]} input.added            paths the diff adds (a rename's new path included)
+ * @param {string[]} input.modified         paths the diff edits
+ * @param {string[]} input.sourceFiles      every tracked file at the head
+ * @param {{path:string,text:string}[]} input.livingAtHead        every living spec, as the head has it
+ * @param {{path:string,text:string}[]} input.changedSpecsAtBase  each living spec the diff changed or deleted, as the base had it
+ * @param {{path:string,text:string}[]} input.deltaSpecs          the change's own delta specs
+ * @returns {{
+ *   added: { path: string, namedBy: 'living'|'delta'|null }[],
+ *   lost: { path: string, spec: string }[],
+ *   legacy: string[],
+ *   repo: { named: number, total: number }
+ * }}
+ */
+export function specCoverageFacts({
+  added = [],
+  modified = [],
+  sourceFiles = [],
+  livingAtHead = [],
+  changedSpecsAtBase = [],
+  deltaSpecs = []
+} = {}) {
+  const living = mentionsOf(livingAtHead)
+  const delta = mentionsOf(deltaSpecs)
+  const named = path => living.has(path) || delta.has(path)
+
+  const addedFiles = coverable(added)
+  const addedSet = new Set(addedFiles)
+
+  const addedFacts = addedFiles.map(path => ({
+    path,
+    namedBy: living.has(path) ? 'living' : delta.has(path) ? 'delta' : null
+  }))
+
+  // Lost: a kept coverable file (tracked at the head, not added by this diff)
+  // that a spec the diff changed named at the base and that nothing names now.
+  const tracked = coverable(sourceFiles)
+  const lost = []
+  const lostSet = new Set()
+  for (const spec of Array.isArray(changedSpecsAtBase) ? changedSpecsAtBase : []) {
+    const before = mentionsOf([spec])
+    for (const path of tracked) {
+      if (addedSet.has(path) || lostSet.has(path)) continue
+      if (!before.has(path) || named(path)) continue
+      lostSet.add(path)
+      lost.push({ path, spec: spec.path })
+    }
+  }
+
+  // Legacy: an edited coverable file nothing names that this change did not
+  // cause to lose its name.
+  const legacy = coverable(modified).filter(
+    path => !addedSet.has(path) && !lostSet.has(path) && !named(path)
+  )
+
+  return {
+    added: addedFacts,
+    lost,
+    legacy,
+    repo: { named: tracked.filter(named).length, total: tracked.length }
+  }
+}

package/lib/spec-text.mjs

@@ -0,0 +1,257 @@
+// The one parser of living-spec text.
+//
+// Three readers need a spec's `### Requirement:` blocks: the subtraction of a
+// requirement a change supersedes, the check that a finding's citation names a
+// requirement that exists, and the spec audit. Left to themselves each would
+// write its own parser, and they would disagree about what a heading is, where
+// a block ends and what a scenario has — the epic's own hand audits already did.
+// So this module is the only place that knows the shape, and it is pure: text
+// in, a plain structure out. No fs, no clock, no git.
+//
+// `extractScenarios` in lib/ready.mjs keeps its own job (conformance) and is not
+// replaced by this. design D1 of judge-against-base-and-living-specs.
+
+/** The delta sections OpenSpec splits a change's spec into. */
+const DELTA_SECTIONS = new Set(['ADDED', 'MODIFIED', 'REMOVED', 'RENAMED'])
+
+const REQUIREMENT_HEADING = /^###\s+Requirement:\s*(.*?)\s*$/
+const SCENARIO_HEADING = /^####\s+Scenario:\s*(.*?)\s*$/
+const H2 = /^##\s+(.*?)\s*$/
+const ANY_HEADING = /^#{1,6}\s/
+const FENCE = /^\s*(```|~~~)/
+// Only the bulleted bold keyword line counts. The word in running prose does
+// not, and neither does AND, which continues a line rather than starting one.
+const KEYWORD_LINE = /^\s*[-*]\s+\*\*(GIVEN|WHEN|THEN)\*\*/
+const RENAME_LINE = /^\s*[-*]\s+(FROM|TO):\s*`?\s*(?:###\s+Requirement:\s*)?(.*?)\s*`?\s*$/
+
+// Any repo-relative path with an extension. Deliberately NOT restricted to a
+// directory allowlist or an extension allowlist: a caller gates every match on
+// the files it knows, so the repository decides what is real. An allowlist here
+// can only produce false negatives — it used to drop Go/Rust/Java layouts
+// (cmd/, internal/, pkg/, apps/, services/) and indexed config files entirely.
+// The leading boundary class excludes URL path segments, which are always
+// preceded by `/`.
+const PATH_RE = /(?:^|[\s`"'(\[])((?:[\w.@-]+\/)+[\w.@-]+\.[A-Za-z0-9]{1,6})\b/gm
+
+/**
+ * The paths a piece of spec text mentions, each once, in first-seen order, with
+ * the character index of its first mention. The one rule for "a spec mentions
+ * this file": the graph's openspec extractor reads it for its spec-to-file
+ * edges (which need the line) and `specMentionedPaths` reads it for the
+ * spec-coverage signal, so a fresh graph and the signal cannot disagree.
+ *
+ * A leading `./` is stripped; a path that climbs out of the repository (`..`)
+ * cannot name a repository file and is not returned.
+ *
+ * @param {unknown} text
+ * @returns {{ path: string, index: number }[]}
+ */
+export function specPathMentions(text) {
+  if (typeof text !== 'string' || !text) return []
+  const seen = new Set()
+  const out = []
+  const re = new RegExp(PATH_RE.source, PATH_RE.flags)
+  let m
+  while ((m = re.exec(text))) {
+    const path = m[1].replace(/^(\.\/)+/, '')
+    if (path.split('/').includes('..')) continue
+    if (seen.has(path)) continue
+    seen.add(path)
+    out.push({ path, index: m.index })
+  }
+  return out
+}
+
+/**
+ * The repository-relative paths a piece of spec text mentions: deduplicated,
+ * first-seen order, a leading `./` stripped. See `specPathMentions`.
+ *
+ * @param {unknown} text
+ * @returns {string[]}
+ */
+export function specMentionedPaths(text) {
+  return specPathMentions(text).map(mention => mention.path)
+}
+
+/**
+ * The canonical form of a requirement heading: strip a leading `Requirement:`,
+ * trim, collapse internal whitespace, keep case. OpenSpec itself matches
+ * requirements whitespace-insensitively and case-sensitively, so a case
+ * difference is a different requirement.
+ *
+ * @param {string} heading
+ * @returns {string}
+ */
+export function requirementKey(heading) {
+  return String(heading ?? '')
+    .replace(/^\s*Requirement:\s*/, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/**
+ * The capability a spec file belongs to, or null when the path is not a spec.
+ * Reads the three spellings callers hold: a living spec
+ * (`openspec/specs/<cap>/spec.md`), a change's delta spec
+ * (`openspec/changes/<name>/specs/<cap>/spec.md`, or `specs/<cap>/spec.md`) and
+ * the form relative to a change's specs directory (`<cap>/spec.md`, which is how
+ * `inspectChange(...).specFiles` lists them). Windows separators are read too.
+ *
+ * @param {string} path
+ * @returns {string|null}
+ */
+export function capabilityOf(path) {
+  if (typeof path !== 'string' || !path) return null
+  const normal = path.replace(/\\/g, '/').replace(/^(\.\/)+/, '')
+  if (normal !== 'spec.md' && !normal.endsWith('/spec.md')) return null
+  const dir = normal.slice(0, -'spec.md'.length).replace(/\/+$/, '')
+  // A spec.md sitting directly in a specs root names no capability.
+  if (/(?:^|\/)(?:openspec\/specs|openspec\/changes\/[^/]+\/specs)$/.test(dir) || dir === 'specs') return null
+  const rest =
+    dir.match(/(?:^|\/)openspec\/changes\/[^/]+\/specs\/(.+)$/)?.[1] ??
+    dir.match(/(?:^|\/)openspec\/specs\/(.+)$/)?.[1] ??
+    dir.match(/^specs\/(.+)$/)?.[1] ??
+    dir
+  return rest ? rest : null
+}
+
+/** Which delta section an `## <NAME> Requirements` heading opens, or null. */
+function deltaSection(h2) {
+  const name = h2.trim().split(/\s+/)[0]?.toUpperCase()
+  return DELTA_SECTIONS.has(name) ? name : null
+}
+
+/**
+ * Parse a spec's text, living or delta.
+ *
+ * `section` on a requirement is the delta section it sits under, and null in a
+ * living spec. `prose` is the block apart from its scenarios; `text` is the
+ * whole block, heading and scenarios included, ending where the next heading of
+ * the same or a higher level begins. A RENAMED section yields FROM/TO pairs and
+ * no requirements.
+ *
+ * @param {string} text
+ * @returns {{
+ *   purpose: string|null,
+ *   requirements: Array<{
+ *     heading: string, key: string, section: string|null, line: number,
+ *     prose: string, text: string,
+ *     scenarios: Array<{ title: string, line: number, given: boolean, when: boolean, then: boolean }>
+ *   }>,
+ *   renamed: Array<{ from: string, to: string }>
+ * }}
+ */
+export function parseSpec(text) {
+  const lines = String(text ?? '').split('\n')
+  const requirements = []
+  const renamed = []
+  const purposeLines = []
+
+  let h2 = null // the current `##` heading's text
+  let section = null // the delta section it opens, if any
+  let req = null // the requirement being read
+  let scenario = null // the scenario being read, inside `req`
+  let inFence = false
+  let pendingFrom = null
+
+  const closeRequirement = () => {
+    if (req) req.text = req.lines.join('\n').trimEnd()
+    if (req) req.prose = req.proseLines.join('\n').trim()
+    req = null
+    scenario = null
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNo = i + 1
+
+    if (FENCE.test(line)) {
+      inFence = !inFence
+      if (req) {
+        req.lines.push(line)
+        if (!scenario) req.proseLines.push(line)
+      }
+      continue
+    }
+
+    if (!inFence && ANY_HEADING.test(line)) {
+      const h2Match = line.match(H2)
+      if (h2Match) {
+        closeRequirement()
+        h2 = h2Match[1]
+        section = deltaSection(h2)
+        pendingFrom = null
+        continue
+      }
+      const reqMatch = line.match(REQUIREMENT_HEADING)
+      if (reqMatch) {
+        closeRequirement()
+        if (section !== 'RENAMED') {
+          const heading = reqMatch[1]
+          req = {
+            heading,
+            key: requirementKey(heading),
+            section,
+            line: lineNo,
+            prose: '',
+            text: '',
+            scenarios: [],
+            lines: [line],
+            proseLines: []
+          }
+          requirements.push(req)
+        }
+        continue
+      }
+      const scenarioMatch = line.match(SCENARIO_HEADING)
+      if (scenarioMatch && req) {
+        scenario = { title: scenarioMatch[1], line: lineNo, given: false, when: false, then: false }
+        req.scenarios.push(scenario)
+        req.lines.push(line)
+        continue
+      }
+      // A `###` that is not a requirement ends the block it interrupts. A
+      // deeper heading that is not a scenario is text inside the block.
+      if (req && /^#{4,}\s/.test(line)) {
+        req.lines.push(line)
+        if (!scenario) req.proseLines.push(line)
+        continue
+      }
+      if (req) closeRequirement()
+      continue
+    }
+
+    if (req) {
+      req.lines.push(line)
+      if (scenario) {
+        const kw = line.match(KEYWORD_LINE)
+        if (kw) scenario[kw[1].toLowerCase()] = true
+      } else {
+        req.proseLines.push(line)
+      }
+      continue
+    }
+
+    if (section === 'RENAMED') {
+      const m = line.match(RENAME_LINE)
+      if (m) {
+        if (m[1] === 'FROM') pendingFrom = m[2]
+        else if (pendingFrom !== null) {
+          renamed.push({ from: requirementKey(pendingFrom), to: requirementKey(m[2]) })
+          pendingFrom = null
+        }
+      }
+      continue
+    }
+
+    if (h2 !== null && /^purpose$/i.test(h2.trim())) purposeLines.push(line)
+  }
+  closeRequirement()
+
+  const purpose = purposeLines.join('\n').trim()
+  return {
+    purpose: purpose ? purpose : null,
+    requirements: requirements.map(({ lines: _lines, proseLines: _proseLines, ...r }) => r),
+    renamed
+  }
+}

package/lib/verify.mjs

@@ -829,8 +829,13 @@ export function judgeCoverageResult(result, opts = {}) {
  *   quietly taking the permissive branch on a typo is how a hard halt goes
  *   missing.
  * @returns {{halt: boolean, reason: string|null, context: string, haltingKinds: string[],
- *   unit: object|null, e2e: object|null, coverage: object|null, signals: Array,
- *   banners: string[], skipped: Array}}
+ *   unit: object|null, e2e: object|null, coverage: object|null,
+ *   typecheck: {ran: boolean, exitCode: number|null, passed: boolean}|null,
+ *   signals: Array, banners: string[], skipped: Array}}
+ *   `typecheck` is the type check's own result in every context — `null` when
+ *   no type-check result was reported, so a pass reads differently from a
+ *   result that never arrived. It moves no halting set: a failure at the final
+ *   gate is still the non-blocking banner.
  */
 export function judgeVerification(plan, results = [], opts = {}) {
   // Both halves matter: `skipped` is iterated below, so a hand-written plan
@@ -891,16 +896,23 @@ export function judgeVerification(plan, results = [], opts = {}) {
     banners.push(text)
   }
 
+  // The type check's own result, recorded whether it passed or failed and in
+  // every context, so a reader can tell "passed" from "never reported" without
+  // parsing a banner. `null` only when no type-check result was reported. It
+  // decides nothing here: whether a failure halts is still `record`'s call.
+  let typecheckResult = null
   const typecheck = byKind.get('typecheck')
   if (typecheck) {
     validateResult(typecheck, 'typecheck')
-    const ok = typecheck.ran !== false && Number(typecheck.exitCode) === 0
-    const detail = typecheck.ran === false
+    const ran = typecheck.ran !== false
+    const ok = ran && Number(typecheck.exitCode) === 0
+    const detail = !ran
       ? trimmedString(typecheck.reason) || 'the typecheck command could not be executed'
       : `exit ${Number(typecheck.exitCode)}`
     record('typecheck', !ok, `typecheck failed (${detail})`, {
       banner: BANNERS.typecheckFailed(detail)
     })
+    typecheckResult = { ran, exitCode: ran ? Number(typecheck.exitCode) : null, passed: ok }
   }
 
   let unit = null
@@ -937,6 +949,7 @@ export function judgeVerification(plan, results = [], opts = {}) {
     unit,
     e2e,
     coverage,
+    typecheck: typecheckResult,
     signals,
     banners,
     skipped: plan.skipped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@renzrollon/interlock",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Spec-driven development for Claude Code, layered on OpenSpec. You read one spec; parallel agents ship it to a tested commit.",
   "type": "module",
   "engines": {

package/shared/SESSION-SHAPES.md

@@ -133,7 +133,7 @@ is narrow. Not running tests after the fix.
 5. Resumable — a stopped run picks up where it left off
 
 **Flow (review):**
-1. `/interlock:review-code` fans out up to six dimension reviewers (language, architecture, QA, delivery; devops and security when the diff earns them)
+1. `/interlock:review-code` fans out up to seven dimension reviewers (language, architecture, QA, delivery; devops and security when the diff earns them; domain when a touched capability has a living spec)
 2. Two skeptics try to refute every blocker and warning; a dismissal must cite a `file:line` span
 3. Only surviving findings reach you; the report states how many were dismissed