@plainconceptsplatform/agent-harness 3.4.1 → 3.6.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/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.