@plainconceptsplatform/agent-harness 3.1.1 → 3.2.0

package/harness/.opencode/commands/repo-initialize.md

@@ -1,5 +1,5 @@
----
-description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
----
-
-Load the `pc-repo-initialize` skill.
+---
+description: Initialize the project. Presents a single form with all setup questions, then executes selected steps.
+---
+
+Load the `pc-repo-initialize` skill.

package/harness/.opencode/commands/repo-onboard.md

@@ -1,5 +1,5 @@
----
-description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system.
----
-
-Load the `pc-repo-onboard` skill.
+---
+description: Walk the user through the project and its agentic infrastructure. Explains what exists, how agents work, and how to use the system.
+---
+
+Load the `pc-repo-onboard` skill.

package/harness/.opencode/commands/repo-verify.md

@@ -1,5 +1,5 @@
----
-description: Verify current-branch changes, plus immutable dependency installs, builds, and tests for every discovered project.
----
-
-Load the `pc-repo-verify` skill.
+---
+description: Verify current-branch changes, plus immutable dependency installs, builds, and tests for every discovered project.
+---
+
+Load the `pc-repo-verify` skill.

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

@@ -0,0 +1,225 @@
+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,
+}
+
+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 }
+
+export function evaluate(files, limits = DEFAULT_LIMITS) {
+  const violations = []
+  const add = (rule, file, line, detail) => violations.push({ rule, file, line, detail, fix: FIX[rule] })
+  const totals = { sourceCode: 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.sourceCode += 1
+        else totals.testCode += 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 testBudget = Math.max(limits.testAllowance, Math.floor(limits.testRatio * totals.sourceCode))
+  const caseBudget = Math.max(limits.caseAllowance, Math.floor((limits.casesPerKloc * totals.sourceCode) / 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
+}
+
+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 result = evaluate(collect(root, base.base), readLimits(root))
+  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,280 @@
+// 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'))
+}
+
+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) {
+      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/AGENTS.md

@@ -1,49 +1,49 @@
-# AGENTS.md
-
-<!-- PC-NOT-INITIALIZED -->
-
-# Agent operating guide
-
-The operating contract for AI agents in this repository. Agent-agnostic: OpenCode, Claude Code, Codex, Gemini and others.
-
-## Session context
-
-Before a non-trivial change, read `AGENTS.md` for workflow rules, `ARCHITECTURE.md` for boundaries and component interactions, `DESIGN.md` for UI and design-system work, and the active OpenSpec change or the specification covering the area you are changing.
-
-Command aliases: OpenSpec skills may reference `/opsx-propose`, `/opsx-apply`, `/opsx-archive`, or `/opsx-explore`. Always substitute them with the `pc-plan-propose`, `pc-plan-apply`, `pc-plan-archive`, and `pc-plan-explore` skills respectively. User-facing command names are `/plan-propose`, `/plan-apply`, `/plan-archive`, and `/plan-explore`. Never mention the `opsx-` names to the user.
-
-## Workflow ownership
-
-<!-- PC-PLATFORM-WORKFLOW-START -->
-<!-- PC-PLATFORM-WORKFLOW-END -->
-
-## Planning and execution
-
-- Never combine an unrelated refactor with the work you were asked to do. It arrives under a message that does not mention it, and the reviewer approves both.
-- Never introduce a new convention where the repository already has one, and never guess when requirements, architecture or a security constraint are unclear. Ask.
-
-## Engineer selection
-
-Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `build` and `plan` are the only primaries and are never spawned; `fullstack-engineer` is the body they share and the fallback worker, so prefer a specialist over it. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
-
-The `pc-plan-apply` skill is authoritative for subagent waves, dependency ordering, retries, and concurrency. A spawn past `agents.maxConcurrent` is denied (`pc-subagent-monitor`); a denied spawn is not a failed task, so re-issue it in the next wave.
-
-## Tool and repository safety
-
-- Never expose or commit secrets, credentials, tokens, or production data.
-- Never overwrite a generated file, or uncommitted changes you did not make. The tree may be shared with a person and another agent.
-- Never bypass a check, weaken a test, or silence a lint rule to reach a green result. A green run that was arranged is worse than a red one, because nobody looks again.
-- Commit, push, open a pull request, change dependencies, or touch deployment configuration only with the user's explicit approval and the repository's stated process.
-
-## Verification and completion
-
-- Never call a bug fixed without a test that would have caught it, where one is practical.
-- Never leave a specification, `ARCHITECTURE.md` or `DESIGN.md` asserting something this change made false.
-- Never end on a blocker without naming it and the decision it needs. An unattended run that stops quietly looks like one that finished.
-
-## Skills
-
-Skills live in `.agents/skills/`. Always installed: `@pc-guardrails-generic`, `@pc-guardrails-project`, and `@browser-automation`. An entry under `## Abilities` is not a passive reference: call the `skill` tool once per `@skill-name`, guardrails first. Editing, shell and spawning stay blocked until you have (`pc-system-reminders`), and a loaded skill can require further loads.
-
-<!-- PC-PLATFORM-SKILLS-GUIDE-START -->
-<!-- PC-PLATFORM-SKILLS-GUIDE-END -->
+# AGENTS.md
+
+<!-- PC-NOT-INITIALIZED -->
+
+# Agent operating guide
+
+The operating contract for AI agents in this repository. Agent-agnostic: OpenCode, Claude Code, Codex, Gemini and others.
+
+## Session context
+
+Before a non-trivial change, read `AGENTS.md` for workflow rules, `ARCHITECTURE.md` for boundaries and component interactions, `DESIGN.md` for UI and design-system work, and the active OpenSpec change or the specification covering the area you are changing.
+
+Command aliases: OpenSpec skills may reference `/opsx-propose`, `/opsx-apply`, `/opsx-archive`, or `/opsx-explore`. Always substitute them with the `pc-plan-propose`, `pc-plan-apply`, `pc-plan-archive`, and `pc-plan-explore` skills respectively. User-facing command names are `/plan-propose`, `/plan-apply`, `/plan-archive`, and `/plan-explore`. Never mention the `opsx-` names to the user.
+
+## Workflow ownership
+
+<!-- PC-PLATFORM-WORKFLOW-START -->
+<!-- PC-PLATFORM-WORKFLOW-END -->
+
+## Planning and execution
+
+- Never combine an unrelated refactor with the work you were asked to do. It arrives under a message that does not mention it, and the reviewer approves both.
+- Never introduce a new convention where the repository already has one, and never guess when requirements, architecture or a security constraint are unclear. Ask.
+
+## Engineer selection
+
+Inspect `.opencode/agents/*.md` before spawning. Prefer the most specialized custom engineer. `build` and `plan` are the only primaries and are never spawned; `fullstack-engineer` is the body they share and the fallback worker, so prefer a specialist over it. If no specialist matches, tell the user to create one with `/make-engineer`. Spawn only engineers present in that directory.
+
+The `pc-plan-apply` skill is authoritative for subagent waves, dependency ordering, retries, and concurrency. A spawn past `agents.maxConcurrent` is denied (`pc-subagent-monitor`); a denied spawn is not a failed task, so re-issue it in the next wave.
+
+## Tool and repository safety
+
+- Never expose or commit secrets, credentials, tokens, or production data.
+- Never overwrite a generated file, or uncommitted changes you did not make. The tree may be shared with a person and another agent.
+- Never bypass a check, weaken a test, or silence a lint rule to reach a green result. A green run that was arranged is worse than a red one, because nobody looks again.
+- Commit, push, open a pull request, change dependencies, or touch deployment configuration only with the user's explicit approval and the repository's stated process.
+
+## Verification and completion
+
+- Never call a bug fixed without a test that would have caught it, where one is practical.
+- Never leave a specification, `ARCHITECTURE.md` or `DESIGN.md` asserting something this change made false.
+- Never end on a blocker without naming it and the decision it needs. An unattended run that stops quietly looks like one that finished.
+
+## Skills
+
+Skills live in `.agents/skills/`. Always installed: `@pc-guardrails-generic`, `@pc-guardrails-project`, and `@browser-automation`. An entry under `## Abilities` is not a passive reference: call the `skill` tool once per `@skill-name`, guardrails first. Editing, shell and spawning stay blocked until you have (`pc-system-reminders`), and a loaded skill can require further loads.
+
+<!-- PC-PLATFORM-SKILLS-GUIDE-START -->
+<!-- PC-PLATFORM-SKILLS-GUIDE-END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/agent-harness",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Installs the Plain Concepts Platform Harness into any codebase, and keeps it up to date. Wires OpenCode, OpenSpec, codegraph, and agentmemory into a multi-agent workflow that runs on native parallel subagents.",
   "keywords": [
     "opencode",