@plainconceptsplatform/agent-harness 3.8.2 → 3.9.0

package/harness/.opencode/scripts/code-rules.mjs

@@ -1,288 +1,288 @@
-// The same rules Project-Health uses to score a repository (collector/src/metrics/code-rules.ts).
-// Keep the two in step: a rule that differs makes the gate and the dashboard disagree.
-
-const SOURCE = /\.(?:[cm]?[jt]sx?|cs)$/
-const SKIP =
-  /(?:^|\/)(?:node_modules|dist|build|out|\.next|bin|obj|coverage|Migrations|migrations|wwwroot|vendor|generated|__generated__|\.github|\.opencode|\.agents|\.claude|openspec)(?:\/|$)|(?:^|\/)components\/ui\/|\.d\.ts$|\.g\.cs$|\.Designer\.cs$|\.min\.js$|AssemblyInfo\.cs$/
-const TEST =
-  /(?:^|\/)(?:tests?|__tests__|e2e|specs?)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|(?:^|\/)[\w.]+\.(?:Unit|Integration|E2E|Acceptance|Architecture)?Tests?\/|Tests?\.cs$/
-const GENERATED_HEADER =
-  /Managed by @plainconceptsplatform|<auto-generated|@generated|This file was (?:auto-)?generated/i
-
-export function kindOf(path) {
-  if (!SOURCE.test(path) || SKIP.test(path)) return null
-  return TEST.test(path) ? 'test' : 'source'
-}
-
-export function isGenerated(text) {
-  return GENERATED_HEADER.test(text.split('\n', 4).join('\n'))
-}
-
-// A comment that is an instruction to a tool, not prose for a reader. Semgrep demands a
-// `nosemgrep` justification on an empty catch; counting it against the comment budget made the
-// two gates trade lines with each other.
-const PRAGMA = /^(\/\/|\/\*)\s*(nosemgrep|biome-ignore|eslint-(disable|enable)|@ts-(expect-error|ignore)|prettier-ignore|(istanbul|c8|v8) ignore|stryker (disable|restore)|ReSharper (disable|restore)|NOSONAR)\b/i
-
-export function lineKinds(text) {
-  const kinds = []
-  let inBlock = false
-  for (const raw of text.split('\n')) {
-    const t = raw.trim()
-    if (!t) kinds.push('blank')
-    else if (!inBlock && PRAGMA.test(t)) {
-      kinds.push('pragma')
-      inBlock = t.startsWith('/*') && !t.includes('*/')
-    } else if (inBlock) {
-      kinds.push('comment')
-      if (t.includes('*/')) inBlock = false
-    } else if (t.startsWith('/*')) {
-      kinds.push('comment')
-      inBlock = !t.includes('*/')
-    } else if (t.startsWith('//')) kinds.push('comment')
-    else kinds.push('code')
-  }
-  return kinds
-}
-
-export function countLines(text) {
-  let codeLines = 0
-  let commentLines = 0
-  for (const kind of lineKinds(text)) {
-    if (kind === 'code') codeLines += 1
-    else if (kind === 'comment') commentLines += 1
-  }
-  return { codeLines, commentLines }
-}
-
-const FILLER = new Set(
-  'a an the this that of for to in on is are be or and with by from its it get gets set sets getting setting value values instance class record struct interface enum new initializes initialises creates constructor property field method current specified given provided object function component hook type props'.split(' '),
-)
-const RETURNS_FILLER = new Set([
-  ...FILLER,
-  'result', 'results', 'task', 'representing', 'asynchronous', 'async', 'operation', 'returns', 'returned', 'which', 'that',
-])
-
-const words = text =>
-  text
-    .replace(/<see\s+cref="([^"]+)"\s*\/>/g, ' $1 ')
-    .replace(/<paramref\s+name="([^"]+)"\s*\/>/g, ' $1 ')
-    .replace(/\{@link\s+([^}\s]+)[^}]*\}/g, ' $1 ')
-    .replace(/<[^>]+>/g, ' ')
-    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
-    .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
-    .toLowerCase()
-    .split(/[^a-z0-9]+/)
-    .filter(Boolean)
-
-const stem = w => (w.length > 3 && w.endsWith('s') && !w.endsWith('ss') ? w.slice(0, -1) : w)
-
-export function restates(text, identifier, filler = FILLER) {
-  const name = new Set(words(identifier.replace(/^I(?=[A-Z])/, '')).map(stem))
-  const said = words(text).filter(w => !filler.has(w) && !filler.has(stem(w))).map(stem)
-  return said.every(w => name.has(w))
-}
-
-const DECL_KEYWORD = /\b(?:class|record|struct|interface|enum|namespace|type|function)\s+([A-Za-z_$][\w$]*)/
-const DECL_VAR = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)/
-const DECL_CALL = /([A-Za-z_$][\w$]*)\s*(?:<[^()]*>)?\s*\(/
-const DECL_PROP = /([A-Za-z_$][\w$]*)\s*[?!]?\s*(?:\{|=>|=|;|:|$)/
-
-export function declaredName(line) {
-  const l = line.trim()
-  if (!l || l.startsWith('[') || l.startsWith('@')) return null
-  return (l.match(DECL_KEYWORD) ?? l.match(DECL_VAR) ?? l.match(DECL_CALL) ?? l.match(DECL_PROP))?.[1] ?? null
-}
-
-const BANNER = /^\/\/+\s*(?:([=\-*#~_+])\1{2,}.*|.*([=\-*#~_+])\2{2,})\s*$/
-const REGION = /^#(?:region|endregion)\b/
-const TODO = /\/\/.*\b(?:TODO|FIXME|HACK|XXX)\b/
-const TRACKED = /#\d+|https?:\/\/|\b[A-Z][A-Z0-9]+-\d+\b|\(\s*issue\s/i
-const APOLOGETIC =
-  /\b(?:not sure (?:if|whether|this|why)|hope this works|might not work|probably wrong|no idea why|i think this (?:works|is right)|quick and dirty)\b/i
-const CODE_BODY =
-  /^(?:(?:var|let|const|await|return|using|import|export|if|else|for|foreach|while|switch|throw|new|public|private|protected|internal|static|async)\b.*[;{(]\s*$|[\w.$[\]]+\s*(?:\+\+|--|[+\-*/]?=)\s*[^=].*;\s*$|[\w.$]+(?:<[^>]*>)?\([^)]*\)\s*;\s*$|[{}]\s*;?\s*$|\}\s*else\b.*$)/
-const TOOL_PRAGMA =
-  /^(?:nosemgrep|eslint|biome|jscpd|@ts-|prettier|istanbul|c8|v8|webpack|vite|ReSharper|resharper|language=|<auto-generated|#pragma)/
-
-const bodyOf = trimmed => trimmed.replace(/^\/\/+\s?/, '')
-
-export function trailingComment(line) {
-  let quote = null
-  for (let i = 0; i < line.length; i++) {
-    const c = line[i]
-    if (quote) {
-      if (c === '\\') i += 1
-      else if (c === quote) quote = null
-    } else if (c === "'" || c === '"' || c === '`') quote = c
-    else if (c === '/' && line[i + 1] === '/' && line[i - 1] !== ':') return line.slice(i)
-  }
-  return null
-}
-
-export function slopFindings(text) {
-  const lines = text.split('\n')
-  const out = []
-  const add = (rule, line) => out.push({ rule, line })
-  const nameAfter = from => {
-    for (let k = from; k < lines.length && k < from + 6; k++) {
-      const name = declaredName(lines[k])
-      if (name) return name
-    }
-    return null
-  }
-  let codeRun = false
-  for (let i = 0; i < lines.length; i++) {
-    const t = lines[i].trim()
-    const isLineComment = t.startsWith('//') && !t.startsWith('///')
-    const body = isLineComment ? bodyOf(t).trim() : ''
-    const isCode =
-      isLineComment && body !== '' && !TOOL_PRAGMA.test(body) && CODE_BODY.test(body) && !/\s(?:https?:)?\/\//.test(body)
-    if (isCode && !codeRun) add('commented-out-code', i + 1)
-    codeRun = isCode || (codeRun && isLineComment && !body)
-
-    if (isLineComment && BANNER.test(t)) add('banner', i + 1)
-    if (REGION.test(t)) add('region', i + 1)
-    const comment = trailingComment(t)
-    if (comment && TODO.test(comment) && !TRACKED.test(comment)) add('untracked-todo', i + 1)
-    if ((t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) && APOLOGETIC.test(t)) add('apologetic', i + 1)
-
-    if (t.startsWith('///') && t.includes('<summary>')) {
-      const start = i
-      let doc = ''
-      let j = i
-      for (; j < lines.length && lines[j].trim().startsWith('///'); j++) {
-        doc += ` ${lines[j].trim().replace(/^\/\/\/\s?/, '')}`
-      }
-      const name = nameAfter(j)
-      const summary = doc.match(/<summary>([\s\S]*?)<\/summary>/)?.[1] ?? ''
-      if (name && summary.trim() && restates(summary, name)) add('restating-summary', start + 1)
-      for (const m of doc.matchAll(/<param\s+name="([^"]+)"\s*>([\s\S]*?)<\/param>/g)) {
-        if (m[2].trim() && restates(m[2], m[1])) add('restating-param', start + 1)
-      }
-      for (const m of doc.matchAll(/<returns>([\s\S]*?)<\/returns>/g)) {
-        if (m[1].trim() && restates(m[1], '', RETURNS_FILLER)) add('filler-returns', start + 1)
-      }
-      i = j - 1
-    } else if (t.startsWith('/**') && !t.startsWith('/***')) {
-      const start = i
-      let j = i
-      let doc = ''
-      for (; j < lines.length; j++) {
-        doc += ` ${lines[j].trim()}`
-        if (lines[j].includes('*/')) break
-      }
-      const text = doc.replace(/^\s*\/\*\*|\*\/\s*$/g, ' ').replace(/\s\*\s?/g, ' ').trim()
-      const summary = text.split(/\s@\w+/)[0]?.trim() ?? ''
-      const name = nameAfter(j + 1)
-      if (name && summary && restates(summary, name)) add('restating-jsdoc', start + 1)
-      for (const m of text.matchAll(/@param\s+(?:\{[^}]*\}\s*)?\[?([\w$.]+)\]?\s*(?:-\s*)?([^@]*)/g)) {
-        if (m[2].trim() && restates(m[2], m[1])) add('restating-param', start + 1)
-      }
-      for (const m of text.matchAll(/@returns?\s+(?:\{[^}]*\}\s*)?([^@]*)/g)) {
-        if (m[1].trim() && restates(m[1], '', RETURNS_FILLER)) add('filler-returns', start + 1)
-      }
-      i = j
-    }
-  }
-  return out
-}
-
-const ISSUE_REF = /(?:\b[A-Z][\w-]*\s)?#\d+\b|\b[A-Z][A-Z0-9]+-\d+\b/
-const PAST =
-  /\b(?:was|were|used to|previously|before|had|broke|regressed|ended up|turned out|once|anymore|no longer|caused)\b/i
-const TS_INTERNAL = /^(?:async\s+)?(?:function|const|let|var|class|interface|type|enum)\b/
-const CS_INTERNAL = /^(?:private|internal|private\s+protected)\b/
-
-export function commentBlocks(text) {
-  const lines = text.split('\n')
-  const blocks = []
-  const firstCode = lines.findIndex(l => {
-    const t = l.trim()
-    return t !== '' && !t.startsWith('//') && !t.startsWith('/*') && !t.startsWith('*')
-  })
-  let i = 0
-  while (i < lines.length) {
-    const t = lines[i].trim()
-    if (!(t.startsWith('//') || t.startsWith('/*'))) {
-      i += 1
-      continue
-    }
-    const start = i
-    let inBlock = false
-    let body = ''
-    for (; i < lines.length; i++) {
-      const s = lines[i].trim()
-      if (inBlock) {
-        body += ` ${s}`
-        if (s.includes('*/')) inBlock = false
-        continue
-      }
-      if (s.startsWith('/*')) {
-        body += ` ${s}`
-        inBlock = !s.includes('*/')
-        continue
-      }
-      if (s.startsWith('//')) {
-        body += ` ${s}`
-        continue
-      }
-      break
-    }
-    const rules = []
-    if (ISSUE_REF.test(body) && PAST.test(body)) rules.push('history')
-    if (i - start >= 5 && start > firstCode) rules.push('essay')
-    if (body.trimStart().startsWith('/**') || body.trimStart().startsWith('///')) {
-      const next = lines.slice(i, i + 4).find(l => {
-        const s = l.trim()
-        return s !== '' && !s.startsWith('[') && !s.startsWith('@')
-      })
-      const decl = next?.trim() ?? ''
-      if (TS_INTERNAL.test(decl) || CS_INTERNAL.test(decl)) rules.push('internal-doc')
-    }
-    blocks.push({ start: start + 1, end: i, rules })
-  }
-  return blocks
-}
-
-const TS_CASE =
-  /(?:^|[^\w.$])(x|f)?(?:it|test)(\.only|\.skip|\.todo|\.concurrent|\.each\s*(?:\([^)]*\)|`[^`]*`))?\s*\(\s*['"`]/g
-const CS_CASE = /\[(?:Fact|Theory|SkippableFact|SkippableTheory|Test|TestMethod)\b([^\]]*)\]/g
-const TS_ASSERT = /\b(?:expect|assert)\w*(?:\.\w+)?\s*\(|\.should\b/g
-const TS_CALL_ASSERT = /\.(?:not\.)?(?:toHaveBeenCalled\w*|toBeCalled\w*|toHaveBeenNthCalledWith)\s*\(/g
-const CS_ASSERT = /\bAssert\w*\.\w+|\.Should\w*\(|\bVerify\w*\(|\bThrows\w*(?:Async)?\s*[<(]|\.Received\(/g
-const CS_CALL_ASSERT = /\.Received\(|\.DidNotReceive\(|\.Verify\(\s*\w+\s*=>/g
-const SNAPSHOT = /\.toMatch(?:Inline|File)?Snapshot\s*\(|\bawait\s+Verify(?:Json|Xml)?\s*\(/
-
-const count = (text, re) => (text.match(re) ?? []).length
-
-export function testStats(path, text) {
-  const cs = path.endsWith('.cs')
-  const starts = []
-  for (const m of text.matchAll(cs ? CS_CASE : TS_CASE)) {
-    if (cs) {
-      starts.push({ index: m.index, skipped: /\bSkip\s*=/.test(m[1] ?? ''), focused: false })
-    } else {
-      const modifier = m[2] ?? ''
-      if (modifier === '.todo') continue
-      starts.push({ index: m.index, skipped: m[1] === 'x' || modifier === '.skip', focused: m[1] === 'f' || modifier === '.only' })
-    }
-  }
-  const stats = { cases: starts.length, skipped: 0, focused: 0, snapshot: 0, noAssertion: 0, mockOnly: 0 }
-  if (cs) stats.skipped += count(text, /\[Ignore\b/g)
-  else {
-    stats.skipped += count(text, /\b(?:describe\.skip|xdescribe)\s*\(/g)
-    stats.focused += count(text, /\b(?:describe\.only|fdescribe)\s*\(/g)
-  }
-  for (let k = 0; k < starts.length; k++) {
-    const s = starts[k]
-    const segment = text.slice(s.index, starts[k + 1]?.index ?? text.length)
-    if (s.skipped) stats.skipped += 1
-    if (s.focused) stats.focused += 1
-    if (SNAPSHOT.test(segment)) stats.snapshot += 1
-    const asserts = count(segment, cs ? CS_ASSERT : TS_ASSERT)
-    const callAsserts = count(segment, cs ? CS_CALL_ASSERT : TS_CALL_ASSERT)
-    if (asserts === 0) stats.noAssertion += 1
-    else if (callAsserts > 0 && callAsserts >= asserts) stats.mockOnly += 1
-  }
-  return stats
-}
+// The same rules Project-Health uses to score a repository (collector/src/metrics/code-rules.ts).
+// Keep the two in step: a rule that differs makes the gate and the dashboard disagree.
+
+const SOURCE = /\.(?:[cm]?[jt]sx?|cs)$/
+const SKIP =
+  /(?:^|\/)(?:node_modules|dist|build|out|\.next|bin|obj|coverage|Migrations|migrations|wwwroot|vendor|generated|__generated__|\.github|\.opencode|\.agents|\.claude|openspec)(?:\/|$)|(?:^|\/)components\/ui\/|\.d\.ts$|\.g\.cs$|\.Designer\.cs$|\.min\.js$|AssemblyInfo\.cs$/
+const TEST =
+  /(?:^|\/)(?:tests?|__tests__|e2e|specs?)\/|\.(?:test|spec)\.[cm]?[jt]sx?$|(?:^|\/)[\w.]+\.(?:Unit|Integration|E2E|Acceptance|Architecture)?Tests?\/|Tests?\.cs$/
+const GENERATED_HEADER =
+  /Managed by @plainconceptsplatform|<auto-generated|@generated|This file was (?:auto-)?generated/i
+
+export function kindOf(path) {
+  if (!SOURCE.test(path) || SKIP.test(path)) return null
+  return TEST.test(path) ? 'test' : 'source'
+}
+
+export function isGenerated(text) {
+  return GENERATED_HEADER.test(text.split('\n', 4).join('\n'))
+}
+
+// A comment that is an instruction to a tool, not prose for a reader. Semgrep demands a
+// `nosemgrep` justification on an empty catch; counting it against the comment budget made the
+// two gates trade lines with each other.
+const PRAGMA = /^(\/\/|\/\*)\s*(nosemgrep|biome-ignore|eslint-(disable|enable)|@ts-(expect-error|ignore)|prettier-ignore|(istanbul|c8|v8) ignore|stryker (disable|restore)|ReSharper (disable|restore)|NOSONAR)\b/i
+
+export function lineKinds(text) {
+  const kinds = []
+  let inBlock = false
+  for (const raw of text.split('\n')) {
+    const t = raw.trim()
+    if (!t) kinds.push('blank')
+    else if (!inBlock && PRAGMA.test(t)) {
+      kinds.push('pragma')
+      inBlock = t.startsWith('/*') && !t.includes('*/')
+    } else if (inBlock) {
+      kinds.push('comment')
+      if (t.includes('*/')) inBlock = false
+    } else if (t.startsWith('/*')) {
+      kinds.push('comment')
+      inBlock = !t.includes('*/')
+    } else if (t.startsWith('//')) kinds.push('comment')
+    else kinds.push('code')
+  }
+  return kinds
+}
+
+export function countLines(text) {
+  let codeLines = 0
+  let commentLines = 0
+  for (const kind of lineKinds(text)) {
+    if (kind === 'code') codeLines += 1
+    else if (kind === 'comment') commentLines += 1
+  }
+  return { codeLines, commentLines }
+}
+
+const FILLER = new Set(
+  'a an the this that of for to in on is are be or and with by from its it get gets set sets getting setting value values instance class record struct interface enum new initializes initialises creates constructor property field method current specified given provided object function component hook type props'.split(' '),
+)
+const RETURNS_FILLER = new Set([
+  ...FILLER,
+  'result', 'results', 'task', 'representing', 'asynchronous', 'async', 'operation', 'returns', 'returned', 'which', 'that',
+])
+
+const words = text =>
+  text
+    .replace(/<see\s+cref="([^"]+)"\s*\/>/g, ' $1 ')
+    .replace(/<paramref\s+name="([^"]+)"\s*\/>/g, ' $1 ')
+    .replace(/\{@link\s+([^}\s]+)[^}]*\}/g, ' $1 ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+
+const stem = w => (w.length > 3 && w.endsWith('s') && !w.endsWith('ss') ? w.slice(0, -1) : w)
+
+export function restates(text, identifier, filler = FILLER) {
+  const name = new Set(words(identifier.replace(/^I(?=[A-Z])/, '')).map(stem))
+  const said = words(text).filter(w => !filler.has(w) && !filler.has(stem(w))).map(stem)
+  return said.every(w => name.has(w))
+}
+
+const DECL_KEYWORD = /\b(?:class|record|struct|interface|enum|namespace|type|function)\s+([A-Za-z_$][\w$]*)/
+const DECL_VAR = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)/
+const DECL_CALL = /([A-Za-z_$][\w$]*)\s*(?:<[^()]*>)?\s*\(/
+const DECL_PROP = /([A-Za-z_$][\w$]*)\s*[?!]?\s*(?:\{|=>|=|;|:|$)/
+
+export function declaredName(line) {
+  const l = line.trim()
+  if (!l || l.startsWith('[') || l.startsWith('@')) return null
+  return (l.match(DECL_KEYWORD) ?? l.match(DECL_VAR) ?? l.match(DECL_CALL) ?? l.match(DECL_PROP))?.[1] ?? null
+}
+
+const BANNER = /^\/\/+\s*(?:([=\-*#~_+])\1{2,}.*|.*([=\-*#~_+])\2{2,})\s*$/
+const REGION = /^#(?:region|endregion)\b/
+const TODO = /\/\/.*\b(?:TODO|FIXME|HACK|XXX)\b/
+const TRACKED = /#\d+|https?:\/\/|\b[A-Z][A-Z0-9]+-\d+\b|\(\s*issue\s/i
+const APOLOGETIC =
+  /\b(?:not sure (?:if|whether|this|why)|hope this works|might not work|probably wrong|no idea why|i think this (?:works|is right)|quick and dirty)\b/i
+const CODE_BODY =
+  /^(?:(?:var|let|const|await|return|using|import|export|if|else|for|foreach|while|switch|throw|new|public|private|protected|internal|static|async)\b.*[;{(]\s*$|[\w.$[\]]+\s*(?:\+\+|--|[+\-*/]?=)\s*[^=].*;\s*$|[\w.$]+(?:<[^>]*>)?\([^)]*\)\s*;\s*$|[{}]\s*;?\s*$|\}\s*else\b.*$)/
+const TOOL_PRAGMA =
+  /^(?:nosemgrep|eslint|biome|jscpd|@ts-|prettier|istanbul|c8|v8|webpack|vite|ReSharper|resharper|language=|<auto-generated|#pragma)/
+
+const bodyOf = trimmed => trimmed.replace(/^\/\/+\s?/, '')
+
+export function trailingComment(line) {
+  let quote = null
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i]
+    if (quote) {
+      if (c === '\\') i += 1
+      else if (c === quote) quote = null
+    } else if (c === "'" || c === '"' || c === '`') quote = c
+    else if (c === '/' && line[i + 1] === '/' && line[i - 1] !== ':') return line.slice(i)
+  }
+  return null
+}
+
+export function slopFindings(text) {
+  const lines = text.split('\n')
+  const out = []
+  const add = (rule, line) => out.push({ rule, line })
+  const nameAfter = from => {
+    for (let k = from; k < lines.length && k < from + 6; k++) {
+      const name = declaredName(lines[k])
+      if (name) return name
+    }
+    return null
+  }
+  let codeRun = false
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim()
+    const isLineComment = t.startsWith('//') && !t.startsWith('///')
+    const body = isLineComment ? bodyOf(t).trim() : ''
+    const isCode =
+      isLineComment && body !== '' && !TOOL_PRAGMA.test(body) && CODE_BODY.test(body) && !/\s(?:https?:)?\/\//.test(body)
+    if (isCode && !codeRun) add('commented-out-code', i + 1)
+    codeRun = isCode || (codeRun && isLineComment && !body)
+
+    if (isLineComment && BANNER.test(t)) add('banner', i + 1)
+    if (REGION.test(t)) add('region', i + 1)
+    const comment = trailingComment(t)
+    if (comment && TODO.test(comment) && !TRACKED.test(comment)) add('untracked-todo', i + 1)
+    if ((t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) && APOLOGETIC.test(t)) add('apologetic', i + 1)
+
+    if (t.startsWith('///') && t.includes('<summary>')) {
+      const start = i
+      let doc = ''
+      let j = i
+      for (; j < lines.length && lines[j].trim().startsWith('///'); j++) {
+        doc += ` ${lines[j].trim().replace(/^\/\/\/\s?/, '')}`
+      }
+      const name = nameAfter(j)
+      const summary = doc.match(/<summary>([\s\S]*?)<\/summary>/)?.[1] ?? ''
+      if (name && summary.trim() && restates(summary, name)) add('restating-summary', start + 1)
+      for (const m of doc.matchAll(/<param\s+name="([^"]+)"\s*>([\s\S]*?)<\/param>/g)) {
+        if (m[2].trim() && restates(m[2], m[1])) add('restating-param', start + 1)
+      }
+      for (const m of doc.matchAll(/<returns>([\s\S]*?)<\/returns>/g)) {
+        if (m[1].trim() && restates(m[1], '', RETURNS_FILLER)) add('filler-returns', start + 1)
+      }
+      i = j - 1
+    } else if (t.startsWith('/**') && !t.startsWith('/***')) {
+      const start = i
+      let j = i
+      let doc = ''
+      for (; j < lines.length; j++) {
+        doc += ` ${lines[j].trim()}`
+        if (lines[j].includes('*/')) break
+      }
+      const text = doc.replace(/^\s*\/\*\*|\*\/\s*$/g, ' ').replace(/\s\*\s?/g, ' ').trim()
+      const summary = text.split(/\s@\w+/)[0]?.trim() ?? ''
+      const name = nameAfter(j + 1)
+      if (name && summary && restates(summary, name)) add('restating-jsdoc', start + 1)
+      for (const m of text.matchAll(/@param\s+(?:\{[^}]*\}\s*)?\[?([\w$.]+)\]?\s*(?:-\s*)?([^@]*)/g)) {
+        if (m[2].trim() && restates(m[2], m[1])) add('restating-param', start + 1)
+      }
+      for (const m of text.matchAll(/@returns?\s+(?:\{[^}]*\}\s*)?([^@]*)/g)) {
+        if (m[1].trim() && restates(m[1], '', RETURNS_FILLER)) add('filler-returns', start + 1)
+      }
+      i = j
+    }
+  }
+  return out
+}
+
+const ISSUE_REF = /(?:\b[A-Z][\w-]*\s)?#\d+\b|\b[A-Z][A-Z0-9]+-\d+\b/
+const PAST =
+  /\b(?:was|were|used to|previously|before|had|broke|regressed|ended up|turned out|once|anymore|no longer|caused)\b/i
+const TS_INTERNAL = /^(?:async\s+)?(?:function|const|let|var|class|interface|type|enum)\b/
+const CS_INTERNAL = /^(?:private|internal|private\s+protected)\b/
+
+export function commentBlocks(text) {
+  const lines = text.split('\n')
+  const blocks = []
+  const firstCode = lines.findIndex(l => {
+    const t = l.trim()
+    return t !== '' && !t.startsWith('//') && !t.startsWith('/*') && !t.startsWith('*')
+  })
+  let i = 0
+  while (i < lines.length) {
+    const t = lines[i].trim()
+    if (!(t.startsWith('//') || t.startsWith('/*'))) {
+      i += 1
+      continue
+    }
+    const start = i
+    let inBlock = false
+    let body = ''
+    for (; i < lines.length; i++) {
+      const s = lines[i].trim()
+      if (inBlock) {
+        body += ` ${s}`
+        if (s.includes('*/')) inBlock = false
+        continue
+      }
+      if (s.startsWith('/*')) {
+        body += ` ${s}`
+        inBlock = !s.includes('*/')
+        continue
+      }
+      if (s.startsWith('//')) {
+        body += ` ${s}`
+        continue
+      }
+      break
+    }
+    const rules = []
+    if (ISSUE_REF.test(body) && PAST.test(body)) rules.push('history')
+    if (i - start >= 5 && start > firstCode) rules.push('essay')
+    if (body.trimStart().startsWith('/**') || body.trimStart().startsWith('///')) {
+      const next = lines.slice(i, i + 4).find(l => {
+        const s = l.trim()
+        return s !== '' && !s.startsWith('[') && !s.startsWith('@')
+      })
+      const decl = next?.trim() ?? ''
+      if (TS_INTERNAL.test(decl) || CS_INTERNAL.test(decl)) rules.push('internal-doc')
+    }
+    blocks.push({ start: start + 1, end: i, rules })
+  }
+  return blocks
+}
+
+const TS_CASE =
+  /(?:^|[^\w.$])(x|f)?(?:it|test)(\.only|\.skip|\.todo|\.concurrent|\.each\s*(?:\([^)]*\)|`[^`]*`))?\s*\(\s*['"`]/g
+const CS_CASE = /\[(?:Fact|Theory|SkippableFact|SkippableTheory|Test|TestMethod)\b([^\]]*)\]/g
+const TS_ASSERT = /\b(?:expect|assert)\w*(?:\.\w+)?\s*\(|\.should\b/g
+const TS_CALL_ASSERT = /\.(?:not\.)?(?:toHaveBeenCalled\w*|toBeCalled\w*|toHaveBeenNthCalledWith)\s*\(/g
+const CS_ASSERT = /\bAssert\w*\.\w+|\.Should\w*\(|\bVerify\w*\(|\bThrows\w*(?:Async)?\s*[<(]|\.Received\(/g
+const CS_CALL_ASSERT = /\.Received\(|\.DidNotReceive\(|\.Verify\(\s*\w+\s*=>/g
+const SNAPSHOT = /\.toMatch(?:Inline|File)?Snapshot\s*\(|\bawait\s+Verify(?:Json|Xml)?\s*\(/
+
+const count = (text, re) => (text.match(re) ?? []).length
+
+export function testStats(path, text) {
+  const cs = path.endsWith('.cs')
+  const starts = []
+  for (const m of text.matchAll(cs ? CS_CASE : TS_CASE)) {
+    if (cs) {
+      starts.push({ index: m.index, skipped: /\bSkip\s*=/.test(m[1] ?? ''), focused: false })
+    } else {
+      const modifier = m[2] ?? ''
+      if (modifier === '.todo') continue
+      starts.push({ index: m.index, skipped: m[1] === 'x' || modifier === '.skip', focused: m[1] === 'f' || modifier === '.only' })
+    }
+  }
+  const stats = { cases: starts.length, skipped: 0, focused: 0, snapshot: 0, noAssertion: 0, mockOnly: 0 }
+  if (cs) stats.skipped += count(text, /\[Ignore\b/g)
+  else {
+    stats.skipped += count(text, /\b(?:describe\.skip|xdescribe)\s*\(/g)
+    stats.focused += count(text, /\b(?:describe\.only|fdescribe)\s*\(/g)
+  }
+  for (let k = 0; k < starts.length; k++) {
+    const s = starts[k]
+    const segment = text.slice(s.index, starts[k + 1]?.index ?? text.length)
+    if (s.skipped) stats.skipped += 1
+    if (s.focused) stats.focused += 1
+    if (SNAPSHOT.test(segment)) stats.snapshot += 1
+    const asserts = count(segment, cs ? CS_ASSERT : TS_ASSERT)
+    const callAsserts = count(segment, cs ? CS_CALL_ASSERT : TS_CALL_ASSERT)
+    if (asserts === 0) stats.noAssertion += 1
+    else if (callAsserts > 0 && callAsserts >= asserts) stats.mockOnly += 1
+  }
+  return stats
+}

package/harness/.opencode/scripts/harness-doctor.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Print the effective model routing and the generated agents. --strict exits 1
+// on any warning, a missing planner-sub, or a manifest older than its configs.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const rootIndex = args.indexOf("--root");
+const root = rootIndex !== -1 ? path.resolve(args[rootIndex + 1]) : process.cwd();
+const strict = args.includes("--strict");
+const manifestPath = path.join(root, ".opencode", "harness-models.json");
+
+function fail(message, code = 1) {
+  console.error(message);
+  process.exit(code);
+}
+
+if (!fs.existsSync(manifestPath)) {
+  fail(`harness-doctor: ${manifestPath} is missing; run node .opencode/scripts/sync-agents.mjs`, 2);
+}
+
+let manifest;
+try {
+  manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+} catch (error) {
+  fail(`harness-doctor: ${manifestPath} is not valid JSON: ${error.message}`, 2);
+}
+
+const models = manifest.models ?? {};
+const sources = manifest.source ?? {};
+const warnings = Array.isArray(manifest.warnings) ? manifest.warnings : [];
+const agents = manifest.agents ?? {};
+const planner = agents["planner-sub"] ?? agents.planner;
+const plannerFile = planner?.file ? path.join(root, ".opencode", "agents", planner.file) : null;
+const plannerExists = plannerFile ? fs.existsSync(plannerFile) : false;
+
+console.log("Model routing");
+console.log(`  ${"tier".padEnd(6)} ${"effective".padEnd(40)} source`);
+for (const tier of ["plan", "build", "fast"]) {
+  console.log(`  ${tier.padEnd(6)} ${String(models[tier] ?? "(session)").padEnd(40)} ${sources[tier] ?? "missing"}`);
+}
+console.log(`  ${"lead".padEnd(6)} ${"session model (ci-workflow-agent)".padEnd(40)} session`);
+console.log(`  ${"planner".padEnd(6)} ${String(planner?.model ?? "(session)").padEnd(40)} ${planner?.mode ?? "missing"}`);
+console.log(`  planner file: ${plannerFile ? `${planner.file}${plannerExists ? "" : " (missing)"}` : "missing"}`);
+console.log(`  agents: ${Object.keys(agents).length} entries, ${warnings.length} warning(s)`);
+
+for (const warning of warnings) console.error(`warning: ${warning}`);
+
+if (strict && (!planner || !plannerExists || warnings.length > 0)) {
+  process.exit(1);
+}