Review Knowledge

export const meta = {
  name: 'review-knowledge-critics',
  description: 'Four adversarial Opus auditors (2 lenses x 2 trees), then a Fable cross-examination',
  phases: [
    { title: 'Audit', detail: 'four opus/high auditors: each lens over each tree' },
    { title: 'Cross-examine', detail: 'four fable/high refuters: lenses refute each other, paired within a tree', model: 'fable' },
  ],
  model: 'opus',
}

const SEVERITY = `Grade by CONSEQUENCE IF THE ENTRY IS TRUSTED AS WRITTEN, not by your confidence:
- critical: acting on this entry causes real harm or wasted work — it states a falsehood about the current tree, contradicts another entry, or (in skill-improvement-log.md) misinforms the dedup scan that reads it as memory.
- major: materially misleading — a stale path/pin/filter, an ADR status or number defect, a policy the base states but does not follow, a missing cross-reference that hides a correction.
- minor: hygiene — ordering, duplication, a cosmetic defect, a window one entry over.
If unsure whether a finding is real, set "confidence" to low/medium and say so in the claim — do NOT inflate or deflate severity to express doubt.`

const LENSES = [
  {
    key: 'accuracy',
    title: 'Accuracy & Staleness',
    brief: `Assume the text is lying to you. For every load-bearing factual claim, check it against the CURRENT tree and flag what no longer holds. Prioritise claims about things that move: Makefile targets and variables, .github/workflows/ci.yml (toolchain pins, job names, lint scopes, test filters), Package.swift (targets, dependencies, exclude lists), test-target layout and file locations, swiftlint/swiftformat pins, skill and tool names, and live-API behaviours. Hunt specifically for: text describing a FIXED problem as still live; passages that contradict EACH OTHER; passages that contradict CLAUDE.md; and text that has accreted several generations of truth instead of being rewritten to the present. Read git log for the PRs a passage cites — one whose fix shipped should have been retired. A cited file:line that no longer points at what it claims is itself a defect, and so is a claimed mechanism (a git hook, a make target, a tool, a skill) that does not exist — verify a mechanism by looking for it, never by trusting the sentence.`,
  },
  {
    key: 'structure',
    title: 'Structure, Policy Compliance & Gaps',
    brief: `Audit the tree against its OWN stated rules, and against what its siblings say about it. Hunt for: duplicate or out-of-order headings, numbering collisions, index drift, broken or missing cross-references, orphaned files, statuses that lag reality, content filed in the wrong place, and windows that have drifted. Then ask what is MISSING: a decision made but never recorded, a recurring trap with no entry, a deferred item with no trigger that would ever surface it, a rule stated where nothing enforces it. Check the tree applies its own hygiene rules TO ITSELF.`,
  },
]

// Both lenses run against BOTH trees — four audits. Widening the scope prose
// without widening these briefs is how this skill silently audited only half
// the repo while its own scope table claimed otherwise (#443).
const TREES = [
  {
    key: 'knowledge',
    title: 'the engineering knowledge base at knowledge/',
    scope: `Everything under knowledge/: gotchas.md, tmdb-api-notes.md, decisions/ (the ADRs, their README index, and 0000-template.md), delivery-retros.md, skill-improvement-log.md, next-major.md, README.md. Its own rules live in knowledge/README.md — rolling windows, retire-what-is-no-longer-true, ADR immutability and superseding, do-not-pre-split, dated grep-friendly headings, and CITE THE PR THAT DID THE WORK, NOT THE ISSUE (this repo's numbers interleave issues and PRs, so check each cited number with \`gh api\`) — and in knowledge/decisions/README.md: numbering, the 0000-template shape, and status upkeep, where an unreleased CHANGELOG section is NOT a release, only a tag is.`,
  },
  {
    key: 'claude',
    title: 'the operating instructions in CLAUDE.md, .claude/ and .github/CODE_REVIEW.md',
    scope: `CLAUDE.md, the topic docs under .claude/docs/, every SKILL.md and reference file under .claude/skills/, .claude/agents/*.md, .claude/workflows/*.js, .claude/settings.json, and .github/CODE_REVIEW.md. This tree is LARGER and MORE NORMATIVE than knowledge/ and decays the same way. Its decay modes, in the order they have actually bitten this repo: a rule stated in two or three places where the copies drift apart; a rule stated as advice where a gate, hook or frontmatter tools-allowlist could enforce it; a precedence clause ("if your memory and the file disagree, the file wins") pointing at a file that no longer says what the caller assumes, leaving the rule inert; two rules sharing one key, so the loser vanishes while the slot still looks filled; a skill delegating to another without passing the argument that skill needs, so it silently falls back to a default the caller just forbade; a phase mandated to write state that no phase actually writes; and a claimed mechanism that does not exist.`,
  },
]

const FINDING_SCHEMA = {
  type: 'object',
  additionalProperties: false,
  properties: {
    lens: { type: 'string' },
    verdict: { type: 'string', enum: ['healthy', 'needs-fixes', 'materially-stale'] },
    findings: {
      type: 'array',
      items: {
        type: 'object',
        additionalProperties: false,
        properties: {
          id: { type: 'string', description: 'short stable slug, e.g. "xcode-pin-stale"' },
          severity: { type: 'string', enum: ['critical', 'major', 'minor'] },
          confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
          claim: { type: 'string', description: 'one-line statement of the defect' },
          location: { type: 'string', description: 'the file:line at fault (in either audited tree)' },
          evidence: { type: 'string', description: 'how you VERIFIED it against the tree — the file:line or command whose output proves the entry wrong' },
          fix: { type: 'string', description: 'the concrete change: rewrite / retire / renumber / relocate, and to what' },
        },
        required: ['id', 'severity', 'confidence', 'claim', 'location', 'evidence', 'fix'],
      },
    },
    verifiedAccurate: { type: 'string', description: 'load-bearing claims you checked that ARE still true — say what you checked and how' },
  },
  required: ['lens', 'verdict', 'findings'],
}

const REBUTTAL_SCHEMA = {
  type: 'object',
  additionalProperties: false,
  properties: {
    assessments: {
      type: 'array',
      items: {
        type: 'object',
        additionalProperties: false,
        properties: {
          id: { type: 'string', description: "the other critic's finding id" },
          position: { type: 'string', enum: ['confirm', 'refute', 'amend'] },
          reasoning: { type: 'string', description: 'evidence from the tree — not an opinion' },
          amendedSeverity: { type: 'string', enum: ['critical', 'major', 'minor'], description: 'only when position is amend' },
        },
        required: ['id', 'position', 'reasoning'],
      },
    },
    missedByBoth: { type: 'string', description: 'anything the other report made you realise BOTH of you missed' },
  },
  required: ['assessments'],
}

const READONLY = `You are READ-ONLY. Read the repo freely (Read/Grep/Bash for git log, grep, ls) but do NOT edit any file, do not fix anything, and do not run builds or tests (slow and unnecessary). `

phase('Audit')
const JOBS = TREES.flatMap((tree) => LENSES.map((lens) => ({ tree, lens })))
const audits = await parallel(JOBS.map(({ tree, lens }) => () =>
  agent(
    `You are an ADVERSARIAL auditor of ${tree.title} in this repo, working the "${lens.title}" lens.\n\n` +
    `SCOPE — audit ONLY this tree, and cite every finding inside it:\n${tree.scope}\n\n` +
    `LENS:\n${lens.brief}\n\n` +
    `${READONLY}\n\n` +
    `EVERY finding must be VERIFIED against the current tree and cite the evidence that proves it — the file:line or command output that contradicts the text. A finding derived only from reading the documentation is inadmissible; that credulity is the exact failure mode you are auditing. Equally: do NOT manufacture findings to look thorough. If a file is accurate, say so in "verifiedAccurate" and name what you checked.\n\n` +
    `SEVERITY RUBRIC:\n${SEVERITY}`,
    { label: `audit:${tree.key}:${lens.key}`, phase: 'Audit', model: 'opus', effort: 'high', schema: FINDING_SCHEMA }
  ).then((v) => v && { ...v, lens: lens.title, key: lens.key, tree: tree.key, treeTitle: tree.title })
))

const live = audits.filter(Boolean)

// Cross-examine WITHIN each tree, so the two lenses challenge each other on the
// same material. A tree with fewer than two survivors is reported UNRECONCILED
// rather than passed off as consensus — a dead auditor is not a clean bill.
//
// This round stays on `fable` while the audit round above runs on `opus`, and
// the asymmetry is deliberate: a refutation here is written to the PERMANENT
// refutation memory in skill-improvement-log.md and suppresses that finding on
// every later audit, whereas a missed finding upstream is re-derived next run.
// Do not unify the two tiers without reading ADR-0020.
const groups = TREES.map((tree) => ({ tree, members: live.filter((a) => a.tree === tree.key) }))
const unreconciled = groups.filter((g) => g.members.length < 2).map((g) => g.tree.key)
unreconciled.forEach((k) => log(`WARNING: ${k} had fewer than 2 auditors return — its findings are UNRECONCILED, not consensus`))
if (live.length === 0) return { audits: [], rebuttals: [], unreconciled, degraded: true }

phase('Cross-examine')
const rebuttals = await parallel(
  groups.filter((g) => g.members.length === 2).flatMap((g) =>
    g.members.map((mine, i) => () => {
      const theirs = g.members[1 - i]
      return agent(
        `An audit of ${g.tree.title} was run through the "${mine.lens}" lens — those findings are YOURS, reproduced below. Another independent auditor worked the "${theirs.lens}" lens over the same tree. Your job now is to CROSS-EXAMINE their findings — try to refute each one.\n\n` +
        `YOUR findings (the "${mine.lens}" lens):\n${JSON.stringify(mine.findings, null, 2)}\n\n` +
        `THEIR findings (the "${theirs.lens}" lens), which you must assess:\n${JSON.stringify(theirs.findings, null, 2)}\n\n` +
        `For each, independently verify it against the tree and take a position: "confirm" (you checked, it holds), "refute" (you checked, it is wrong or the text is actually fine — say what they misread), or "amend" (real, but the severity or the proposed fix is wrong — give the corrected one).\n\n` +
        `Default to REFUTE when the evidence is thin. A finding that cannot be independently reproduced from the tree should not survive into the consensus. Do not confirm out of collegiality.\n\n` +
        `${READONLY}\n\n` +
        `Finally, in "missedByBoth", note anything their report made you realise you BOTH missed.`,
        // `fable` is deliberate and load-bearing — refutations are permanent. See ADR-0020.
        { label: `cross:${g.tree.key}:${mine.key}`, phase: 'Cross-examine', model: 'fable', effort: 'high', schema: REBUTTAL_SCHEMA }
      ).then((r) => r && { by: mine.lens, tree: g.tree.key, ...r })
    })
  )
)

return { audits: live, rebuttals: rebuttals.filter(Boolean), unreconciled, degraded: unreconciled.length > 0 }