@plainconceptsplatform/agent-harness 3.1.1 → 3.3.0

package/harness/.opencode/scripts/check-diff.mjs

@@ -0,0 +1,244 @@
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { commentBlocks, countLines, isGenerated, kindOf, lineKinds, slopFindings, testStats } from './code-rules.mjs'
+
+export const DEFAULT_LIMITS = {
+  commentRatio: 0.1,
+  commentAllowance: 2,
+  testRatio: 1,
+  testAllowance: 40,
+  casesPerKloc: 40,
+  caseAllowance: 3,
+  complexityBaseline: 'scripts/complexity-baseline.json',
+}
+
+const FIX = {
+  'comment-budget': 'Delete comments until the diff is within budget. Keep only one that explains a constraint the code cannot show: a third-party bug, an external contract, a legal requirement.',
+  'banner': 'Delete the separator.',
+  'region': 'Delete the region markers.',
+  'untracked-todo': 'Link an issue or delete the TODO.',
+  'restating-summary': 'Delete the doc comment: it repeats the name.',
+  'restating-jsdoc': 'Delete the doc comment: it repeats the name.',
+  'restating-param': 'Delete the parameter doc: it repeats the name.',
+  'filler-returns': 'Delete the returns doc: it says nothing the signature does not.',
+  'commented-out-code': 'Delete it; git keeps the history.',
+  'apologetic': 'Make the code right or delete the note.',
+  'history': 'Delete the incident story; it belongs in the commit message or the pull request.',
+  'essay': 'Cut the block to one line or delete it; long explanations belong in docs or the pull request.',
+  'internal-doc': 'Delete the doc comment: nothing outside the file calls this.',
+  'touched-file-slop': 'This file is in the diff, so leave it clean: delete the finding even though it predates the change.',
+  'touched-file-density': 'This file now has more comments per code line than before. Delete comments until it does not.',
+  'test-budget': 'Too much test code for the change. Keep the tests of the public contract; a bug fix gets one regression test.',
+  'case-budget': 'Too many test cases for the change. Merge or delete the ones that test internals or repeat each other.',
+  'test-skipped': 'Delete the skipped test or make it run.',
+  'test-focused': 'Remove .only / f-prefix: it hides every other test.',
+  'test-snapshot': 'Assert the values that matter instead of a snapshot.',
+  'test-no-assertion': 'Assert something, or delete the test.',
+  'test-mock-only': 'Assert on state or output, not only that a mock was called.',
+}
+
+const SUSPICIOUS = {
+  skipped: 'test-skipped',
+  focused: 'test-focused',
+  snapshot: 'test-snapshot',
+  noAssertion: 'test-no-assertion',
+  mockOnly: 'test-mock-only',
+}
+
+const EMPTY_STATS = { cases: 0, skipped: 0, focused: 0, snapshot: 0, noAssertion: 0, mockOnly: 0 }
+
+// `tracked` holds the files a complexity gate has methods on record for. Their new lines buy twice
+// the test budget: that gate fails a method whose coverage drops, so a change there needs its new
+// branches tested, and trimming those tests to fit this budget is what broke Pliny-Bot #633.
+export function evaluate(files, limits = DEFAULT_LIMITS, tracked = new Set()) {
+  const violations = []
+  const add = (rule, file, line, detail) => violations.push({ rule, file, line, detail, fix: FIX[rule] })
+  const totals = { sourceCode: 0, trackedCode: 0, testCode: 0, comments: 0, testLines: 0, cases: 0 }
+  const commentsByFile = new Map()
+
+  for (const file of files) {
+    const kind = kindOf(file.path)
+    if (!kind || isGenerated(file.after)) continue
+    const kinds = lineKinds(file.after)
+    for (const n of file.added) {
+      const k = kinds[n - 1]
+      if (k === 'comment') {
+        totals.comments += 1
+        commentsByFile.set(file.path, (commentsByFile.get(file.path) ?? 0) + 1)
+      } else if (k === 'code') {
+        if (kind !== 'source') totals.testCode += 1
+        else {
+          totals.sourceCode += 1
+          if (tracked.has(file.path)) totals.trackedCode += 1
+        }
+      }
+    }
+
+    const findings = slopFindings(file.after)
+    for (const f of findings) {
+      if (file.added.has(f.line)) add(f.rule, file.path, f.line)
+      else if (file.before != null) add('touched-file-slop', file.path, f.line, f.rule)
+    }
+    for (const block of commentBlocks(file.after)) {
+      let touched = false
+      for (let n = block.start; n <= block.end && !touched; n++) touched = file.added.has(n)
+      if (touched) for (const rule of block.rules) add(rule, file.path, block.start)
+    }
+
+    const before = file.before == null ? { codeLines: 0, commentLines: 0 } : countLines(file.before)
+    const after = countLines(file.after)
+    if (kind === 'source') {
+      const density = c => (c.codeLines > 0 ? c.commentLines / c.codeLines : c.commentLines > 0 ? Infinity : 0)
+      if (file.before != null && after.commentLines > before.commentLines && density(after) > density(before)) {
+        add('touched-file-density', file.path, undefined, `${before.commentLines}/${before.codeLines} -> ${after.commentLines}/${after.codeLines}`)
+      }
+      continue
+    }
+    totals.testLines += after.codeLines - before.codeLines
+    const statsBefore = file.before == null ? EMPTY_STATS : testStats(file.path, file.before)
+    const statsAfter = testStats(file.path, file.after)
+    totals.cases += Math.max(0, statsAfter.cases - statsBefore.cases)
+    for (const [key, rule] of Object.entries(SUSPICIOUS)) {
+      const grew = statsAfter[key] - statsBefore[key]
+      if (grew > 0) add(rule, file.path, undefined, `+${grew}`)
+    }
+  }
+
+  const commentBudget = Math.max(limits.commentAllowance, Math.floor(limits.commentRatio * (totals.sourceCode + totals.testCode)))
+  const testedCode = totals.sourceCode + totals.trackedCode
+  const testBudget = Math.max(limits.testAllowance, Math.floor(limits.testRatio * testedCode))
+  const caseBudget = Math.max(limits.caseAllowance, Math.floor((limits.casesPerKloc * testedCode) / 1000))
+  if (totals.comments > commentBudget) {
+    const where = [...commentsByFile].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([f, n]) => `${f} (${n})`).join(', ')
+    add('comment-budget', undefined, undefined, `${totals.comments} comment lines added, budget ${commentBudget}: ${where}`)
+  }
+  if (totals.testLines > testBudget) {
+    add('test-budget', undefined, undefined, `${totals.testLines} test lines added for ${totals.sourceCode} code lines, budget ${testBudget}`)
+  }
+  if (totals.cases > caseBudget) {
+    add('case-budget', undefined, undefined, `${totals.cases} test cases added for ${totals.sourceCode} code lines, budget ${caseBudget}`)
+  }
+  return { totals, budgets: { comments: commentBudget, testLines: testBudget, cases: caseBudget }, violations }
+}
+
+export function addedLines(unifiedDiff) {
+  const added = new Set()
+  for (const m of unifiedDiff.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
+    const start = Number(m[1])
+    const length = m[2] === undefined ? 1 : Number(m[2])
+    for (let n = start; n < start + length; n++) added.add(n)
+  }
+  return added
+}
+
+function git(root, args) {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 1 << 28, stdio: ['ignore', 'pipe', 'pipe'] })
+}
+
+function tryGit(root, args) {
+  try {
+    return git(root, args).trim()
+  } catch {
+    return null
+  }
+}
+
+function resolveBase(root, requested) {
+  const candidates = requested ? [requested] : ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master']
+  for (const ref of candidates) {
+    const base = tryGit(root, ['merge-base', ref, 'HEAD'])
+    if (base) return { ref, base }
+  }
+  return null
+}
+
+const normalize = text => text.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n')
+
+export function collect(root, base) {
+  const files = []
+  const entries = git(root, ['diff', '--name-status', '-M', '-z', base]).split('\0').filter(Boolean)
+  for (let i = 0; i < entries.length; ) {
+    const status = entries[i]
+    const renamed = status.startsWith('R') || status.startsWith('C')
+    const from = entries[i + 1]
+    const to = renamed ? entries[i + 2] : from
+    i += renamed ? 3 : 2
+    if (status === 'D' || !kindOf(to)) continue
+    const full = path.join(root, to)
+    if (!fs.existsSync(full)) continue
+    const after = normalize(fs.readFileSync(full, 'utf8'))
+    const before = status === 'A' ? null : normalize(git(root, ['show', `${base}:${from}`]))
+    const diff = git(root, ['diff', '-U0', '--no-color', '--no-ext-diff', '-M', base, '--', ...new Set([from, to])])
+    files.push({ path: to, before, after, added: addedLines(diff) })
+  }
+  for (const untracked of git(root, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean)) {
+    if (!kindOf(untracked)) continue
+    const after = normalize(fs.readFileSync(path.join(root, untracked), 'utf8'))
+    const count = after.split('\n').length - (after.endsWith('\n') ? 1 : 0)
+    files.push({ path: untracked, before: null, after, added: new Set(Array.from({ length: count }, (_, k) => k + 1)) })
+  }
+  return files
+}
+
+// Paths of the files a complexity gate tracks, from its baseline keyed `path::method`.
+export function trackedFiles(root, baseline) {
+  try {
+    const entries = Object.keys(JSON.parse(fs.readFileSync(path.join(root, baseline), 'utf8')))
+    return new Set(entries.map(key => key.split('::')[0]))
+  } catch {
+    return new Set()
+  }
+}
+
+function readLimits(root) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(root, '.opencode', 'harness.json'), 'utf8'))
+    return { ...DEFAULT_LIMITS, ...config.codeRules }
+  } catch {
+    return DEFAULT_LIMITS
+  }
+}
+
+function report(result, base) {
+  const { totals, budgets, violations } = result
+  const lines = [
+    `check-diff against ${base.ref} (${base.base.slice(0, 7)}): ${violations.length === 0 ? 'clean' : `${violations.length} problem${violations.length === 1 ? '' : 's'}`}`,
+    `  code lines added ${totals.sourceCode}, comment lines ${totals.comments}/${budgets.comments}, test lines ${totals.testLines}/${budgets.testLines}, test cases ${totals.cases}/${budgets.cases}`,
+  ]
+  const byRule = new Map()
+  for (const v of violations) byRule.set(v.rule, [...(byRule.get(v.rule) ?? []), v])
+  for (const [rule, list] of byRule) {
+    lines.push('', `${rule}: ${FIX[rule]}`)
+    for (const v of list.slice(0, 50)) {
+      const where = v.file ? `${v.file}${v.line ? `:${v.line}` : ''}` : ''
+      lines.push(`  ${[where, v.detail].filter(Boolean).join('  ')}`)
+    }
+    if (list.length > 50) lines.push(`  ... ${list.length - 50} more`)
+  }
+  return lines.join('\n')
+}
+
+function main(argv) {
+  const option = name => {
+    const i = argv.indexOf(`--${name}`)
+    return i === -1 ? undefined : argv[i + 1]
+  }
+  const root = tryGit(process.cwd(), ['rev-parse', '--show-toplevel'])
+  if (!root) {
+    console.error('check-diff: not inside a git repository.')
+    return 2
+  }
+  const base = resolveBase(root, option('base') ?? process.env.CHECK_DIFF_BASE)
+  if (!base) {
+    console.error('check-diff: no base to compare against. Pass --base <ref> or fetch origin.')
+    return 2
+  }
+  const limits = readLimits(root)
+  const result = evaluate(collect(root, base.base), limits, trackedFiles(root, limits.complexityBaseline))
+  console.log(argv.includes('--json') ? JSON.stringify({ base, ...result }, null, 2) : report(result, base))
+  return result.violations.length === 0 ? 0 : 1
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) process.exitCode = main(process.argv.slice(2))

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

@@ -0,0 +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
+}

package/harness/ARCHITECTURE.md

@@ -1,13 +1,13 @@
-> NOT GENERATED YET
->
-> This file has not been populated yet. It is intentionally empty.
->
-> **If this is a greenfield project** (no codebase exists yet): skip this for now. Come back and run `/make-architecture` once you have meaningful code, structure, or infrastructure in place.
->
-> **If this is a brownfield project** (existing codebase): run this command now to generate the architecture documentation:
->
-> ```
-> /make-architecture
-> ```
->
-> This command analyzes your folder structure, config files, routes, data models, integrations, and build setup, then writes a complete ARCHITECTURE.md covering components, data flow, tech stack, deployment, and more. It is safe to rerun any time the architecture changes significantly.
+> NOT GENERATED YET
+>
+> This file has not been populated yet. It is intentionally empty.
+>
+> **If this is a greenfield project** (no codebase exists yet): skip this for now. Come back and run `/make-architecture` once you have meaningful code, structure, or infrastructure in place.
+>
+> **If this is a brownfield project** (existing codebase): run this command now to generate the architecture documentation:
+>
+> ```
+> /make-architecture
+> ```
+>
+> This command analyzes your folder structure, config files, routes, data models, integrations, and build setup, then writes a complete ARCHITECTURE.md covering components, data flow, tech stack, deployment, and more. It is safe to rerun any time the architecture changes significantly.

package/harness/DESIGN.md

@@ -1,13 +1,13 @@
-> NOT GENERATED YET
->
-> This file has not been populated yet. It is intentionally empty.
->
-> **If this is a greenfield project** (no UI exists yet): skip this for now. Come back and run `/make-design` once you have a design system, UI components, or styles in place.
->
-> **If this is a brownfield project** (existing UI/styles): run this command now to generate the design documentation:
->
-> ```
-> /make-design
-> ```
->
-> This command analyzes your CSS, Tailwind config, component files, and design tokens, then writes a complete DESIGN.md with structured YAML tokens and written design intent. It is safe to rerun any time your design system changes.
+> NOT GENERATED YET
+>
+> This file has not been populated yet. It is intentionally empty.
+>
+> **If this is a greenfield project** (no UI exists yet): skip this for now. Come back and run `/make-design` once you have a design system, UI components, or styles in place.
+>
+> **If this is a brownfield project** (existing UI/styles): run this command now to generate the design documentation:
+>
+> ```
+> /make-design
+> ```
+>
+> This command analyzes your CSS, Tailwind config, component files, and design tokens, then writes a complete DESIGN.md with structured YAML tokens and written design intent. It is safe to rerun any time your design system changes.

package/harness/opencode.jsonc

@@ -1,36 +1,36 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "servers": {
-      "agent-browser": {
-        "type": "local",
-        "command": ["agent-browser", "mcp", "--tools", "core"],
-        "disabled": false
-      }
-    },
-    "timeout": {
-      "catalog": 300000,
-      "execution": 300000
-    }
-  },
-  "compaction": {
-    "auto": true,
-    "buffer": 10000
-  },
-  "permissions": [
-    { "action": "question", "resource": "*", "effect": "allow" },
-    { "action": "skill", "resource": "*", "effect": "allow" }
-  ],
-  "skills": [".agents/skills"],
-  "default_agent": "plan",
-  "agents": {
-    "build": { "mode": "primary" },
-    "plan": {
-      "mode": "primary",
-      "permissions": [
-        { "action": "edit", "resource": "*", "effect": "deny" },
-        { "action": "subagent", "resource": "*", "effect": "deny" }
-      ]
-    }
-  }
-}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "servers": {
+      "agent-browser": {
+        "type": "local",
+        "command": ["agent-browser", "mcp", "--tools", "core"],
+        "disabled": false
+      }
+    },
+    "timeout": {
+      "catalog": 300000,
+      "execution": 300000
+    }
+  },
+  "compaction": {
+    "auto": true,
+    "buffer": 10000
+  },
+  "permissions": [
+    { "action": "question", "resource": "*", "effect": "allow" },
+    { "action": "skill", "resource": "*", "effect": "allow" }
+  ],
+  "skills": [".agents/skills"],
+  "default_agent": "plan",
+  "agents": {
+    "build": { "mode": "primary" },
+    "plan": {
+      "mode": "primary",
+      "permissions": [
+        { "action": "edit", "resource": "*", "effect": "deny" },
+        { "action": "subagent", "resource": "*", "effect": "deny" }
+      ]
+    }
+  }
+}