@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/required-check-plan.mjs

@@ -0,0 +1,172 @@
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { parseMergifyYaml } from '../../engineering-runtime/scripts/mergify-yaml.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { validateRequiredCheckPlan } from '../../engineering-runtime/scripts/required-check-plan.mjs'
+
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const unique = (values) => [...new Set(values.filter(nonEmpty))]
+
+function structuralConditionTree(value, label) {
+  if (typeof value === 'string' && value.trim()) return { condition: value.trim() }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be a condition string or and/or mapping`)
+  const keys = Object.keys(value)
+  if (keys.length !== 1 || !['and', 'or'].includes(keys[0])) throw new Error(`${label} has unsupported condition structure`)
+  const children = value[keys[0]]
+  if (!Array.isArray(children) || children.length === 0) throw new Error(`${label}.${keys[0]} must be a non-empty array`)
+  return { [keys[0] === 'and' ? 'all' : 'any']: children.map((child, index) => structuralConditionTree(child, `${label}.${keys[0]}[${index}]`)) }
+}
+
+const MERGIFY_PHASES = {
+  queue_conditions: { id: 'queue-entry', phase: 'pr-head', source: 'queue_conditions' },
+  merge_conditions: { id: 'queue-merge', phase: 'queue-head', source: 'merge_conditions' },
+  auto_merge_conditions: { id: 'auto-enqueue', phase: 'pr-head', source: 'auto_merge_conditions' },
+  success_conditions: { id: 'merge-protection', phase: 'pr-head', source: 'success_conditions' },
+}
+
+export function mergifyDiscovery(yaml) {
+  const document = parseMergifyYaml(yaml)
+  const phases = []
+  const phaseCounts = new Map()
+  const collect = (value, label = 'root') => {
+    if (!value || typeof value !== 'object') return
+    if (Array.isArray(value)) return value.forEach((entry, index) => collect(entry, `${label}[${index}]`))
+    for (const [key, child] of Object.entries(value)) {
+      const at = `${label}.${key}`
+      const shape = MERGIFY_PHASES[key]
+      if (shape) {
+        if (!Array.isArray(child) || child.length === 0) throw new Error(`${at} must be a non-empty condition array`)
+        const trees = [{ all: child.map((entry, index) => structuralConditionTree(entry, `${at}[${index}]`)) }]
+        const leaves = (tree) => tree.condition ? [tree.condition] : (tree.all || tree.any || []).flatMap(leaves)
+        const count = (phaseCounts.get(shape.id) ?? 0) + 1
+        phaseCounts.set(shape.id, count)
+        phases.push({ ...shape, id: count === 1 ? shape.id : `${shape.id}:${count}`, source: `${shape.source}@${at}`, trees, conditions: unique(trees.flatMap(leaves)) })
+      }
+      collect(child, at)
+    }
+  }
+  collect(document)
+  if (!phases.length) throw new Error('Mergify YAML has no merge-admission condition sections')
+  const leaves = (tree) => tree.condition ? [tree.condition] : (tree.all || tree.any || []).flatMap(leaves)
+  const trees = phases.flatMap((phase) => phase.trees)
+  return { phases, trees, conditions: unique(trees.flatMap(leaves)) }
+}
+
+export function mergifyConditions(yaml) { return mergifyDiscovery(yaml).conditions }
+
+function matchRefPattern(pattern, targetBranch, defaultBranch) {
+  if (pattern === '~ALL') return true
+  if (pattern === '~DEFAULT_BRANCH') {
+    if (!nonEmpty(defaultBranch)) throw new Error('GitHub default branch is required to evaluate ~DEFAULT_BRANCH ruleset conditions')
+    return targetBranch === defaultBranch
+  }
+  if (!nonEmpty(pattern)) throw new Error('ruleset ref_name include/exclude must contain non-empty strings')
+  if (!/^[A-Za-z0-9._/*?/-]+$/.test(pattern)) throw new Error(`unsupported ruleset ref_name pattern ${JSON.stringify(pattern)}`)
+  const expression = '^' + pattern.split('*').map((segment) => segment.split('?').map((part) => part.replace(/[.*+^${}()|[\]\\]/g, '\\$&')).join('[^/]')).join('.*') + '$'
+  return new RegExp(expression).test(targetBranch)
+}
+
+function rulesetApplies(ruleset, { targetBranch, defaultBranch }) {
+  if (ruleset?.enforcement && ruleset.enforcement !== 'active') return false
+  if (ruleset?.target && ruleset.target !== 'branch') throw new Error(`unsupported ruleset target ${JSON.stringify(ruleset.target)}`)
+  const conditions = ruleset?.conditions
+  if (conditions == null) return true
+  if (!conditions || typeof conditions !== 'object' || Array.isArray(conditions) || Object.keys(conditions).length !== 1 || !Object.hasOwn(conditions, 'ref_name')) throw new Error('unsupported or ambiguous GitHub ruleset condition structure')
+  const ref = conditions.ref_name
+  if (!ref || typeof ref !== 'object' || Array.isArray(ref) || Object.keys(ref).some((key) => !['include', 'exclude'].includes(key)) || !Array.isArray(ref.include) || !Array.isArray(ref.exclude)) throw new Error('unsupported or ambiguous GitHub ruleset ref_name condition shape')
+  const included = ref.include.some((pattern) => matchRefPattern(pattern, targetBranch, defaultBranch))
+  const excluded = ref.exclude.some((pattern) => matchRefPattern(pattern, targetBranch, defaultBranch))
+  return included && !excluded
+}
+
+export function githubConditions(rulesets, { targetBranch, defaultBranch, withDiscovery = false } = {}) {
+  const conditions = []
+  const applicable = []
+  for (const ruleset of Array.isArray(rulesets) ? rulesets : []) {
+    if (!rulesetApplies(ruleset, { targetBranch, defaultBranch })) continue
+    applicable.push({ id: ruleset?.id ?? null, target: ruleset?.target ?? 'branch', enforcement: ruleset?.enforcement ?? 'active', conditions: ruleset?.conditions ?? null })
+    for (const rule of ruleset?.rules || []) {
+      if (rule?.type !== 'required_status_checks') continue
+      for (const check of rule.parameters?.required_status_checks || []) if (nonEmpty(check.context)) conditions.push('required_status_checks: ' + check.context)
+    }
+  }
+  const result = { conditions: unique(conditions), rulesets: applicable }
+  return withDiscovery ? result : result.conditions
+}
+
+const checksFrom = (conditions) => conditions.filter((condition) => /^required_status_checks:\s*|^check-success\s*=\s*/.test(condition)).map((condition) => condition.replace(/^required_status_checks:\s*|^check-success\s*=\s*/, '')).filter(nonEmpty)
+
+export function buildRequiredCheckPlan({ repository, targetBranch, defaultBranch, headSha, githubRulesets, mergifyYaml, mappings = {}, allowedSkippedJobs = [] }) {
+  const githubResult = githubConditions(githubRulesets, { targetBranch, defaultBranch, withDiscovery: true })
+  const github = githubResult.conditions
+  const mergifyResult = mergifyDiscovery(mergifyYaml)
+  const mergify = mergifyResult.conditions
+  const requiredChecks = unique([...checksFrom(github), ...checksFrom(mergify)]).sort()
+  const leaves = (tree) => tree.condition ? [tree.condition] : (tree.all || tree.any || []).flatMap(leaves)
+  const checks = requiredChecks.map((name) => {
+    const mapping = mappings[name]
+    if (!mapping) throw new Error('live required check ' + name + ' has no classification/evidence mapping; classify it locally-reproduced or publish-only before freeze')
+    const phases = unique([
+      ...(github.includes('required_status_checks: ' + name) ? ['pr-head'] : []),
+      ...mergifyResult.phases.filter((phase) => phase.trees.flatMap(leaves).includes('check-success = ' + name)).map((phase) => phase.phase),
+    ])
+    const sources = [...(github.includes('required_status_checks: ' + name) ? ['github-ruleset'] : []), ...mergifyResult.phases.filter((phase) => phase.trees.flatMap(leaves).includes('check-success = ' + name)).map((phase) => `mergify:${phase.id}`)]
+    const queueEvidence = phases.includes('queue-head')
+      ? mapping.queueEvidence ?? { provider: mapping.evidence?.provider ?? 'github', acquisition: 'github-check-runs' }
+      : undefined
+    return { name, admission: 'required', sources, phases, ...mapping, ...(queueEvidence ? { queueEvidence } : {}) }
+  })
+  const tree = (condition) => ({ condition })
+  const plan = { version: 2, kind: 'required-check-plan', repository, targetBranch, headSha, discovery: { github: { conditions: github, trees: github.map(tree), rulesets: githubResult.rulesets }, mergify: { conditions: mergify, trees: mergifyResult.trees, phases: mergifyResult.phases }, requiredChecks }, checks, allowedSkippedJobs }
+  const verdict = validateRequiredCheckPlan(plan, { expectedHeadSha: headSha })
+  if (!verdict.ok) throw new Error('invalid discovered required-check plan: ' + verdict.errors.join('; '))
+  return plan
+}
+
+function parseArgs(argv) {
+  const options = {}
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--repository') options.repository = argv[++index]
+    else if (arg === '--target') options.targetBranch = argv[++index]
+    else if (arg === '--head') options.headSha = argv[++index]
+    else if (arg === '--mappings') options.mappings = argv[++index]
+    else if (arg === '--allowed-skipped-jobs') options.allowedSkippedJobs = argv[++index]
+    else if (arg === '--out') options.out = argv[++index]
+    else if (arg === '--help' || arg === '-h') options.help = true
+    else throw new Error('unknown argument ' + arg)
+  }
+  return options
+}
+
+function ghJson(args) { return JSON.parse(execFileSync('gh', args, { encoding: 'utf8' })) }
+
+export function runCli(argv) {
+  let options
+  try { options = parseArgs(argv) } catch (error) { console.error('required-check-plan: ' + error.message); return 2 }
+  if (options.help) {
+    console.log('required-check-plan --repository owner/name --target main --head <40-sha> --mappings mappings.json [--allowed-skipped-jobs skips.json] --out required-check-plan.json')
+    return 0
+  }
+  if (![options.repository, options.targetBranch, options.headSha, options.mappings, options.out].every(nonEmpty)) {
+    console.error('required-check-plan requires --repository --target --head --mappings --out')
+    return 2
+  }
+  try {
+    const summary = ghJson(['api', 'repos/' + options.repository + '/rulesets'])
+    const repository = ghJson(['api', 'repos/' + options.repository])
+    const defaultBranch = repository.default_branch
+    if (!nonEmpty(defaultBranch)) throw new Error('GitHub repository default_branch is unavailable; cannot evaluate ruleset conditions')
+    const githubRulesets = summary.map((ruleset) => ghJson(['api', 'repos/' + options.repository + '/rulesets/' + ruleset.id]))
+    const content = ghJson(['api', 'repos/' + options.repository + '/contents/.mergify.yml?ref=' + options.targetBranch])
+    const mergifyYaml = Buffer.from(content.content.replace(/\s/g, ''), 'base64').toString('utf8')
+    const mappings = JSON.parse(fs.readFileSync(options.mappings, 'utf8'))
+    const allowedSkippedJobs = options.allowedSkippedJobs ? JSON.parse(fs.readFileSync(options.allowedSkippedJobs, 'utf8')) : []
+    const plan = buildRequiredCheckPlan({ repository: options.repository, targetBranch: options.targetBranch, defaultBranch, headSha: options.headSha, githubRulesets, mergifyYaml, mappings, allowedSkippedJobs })
+    fs.writeFileSync(options.out, JSON.stringify(plan, null, 2) + '\n')
+    console.log('required-check-plan: discovered ' + plan.checks.length + ' live required checks at ' + plan.headSha)
+    return 0
+  } catch (error) { console.error('required-check-plan: ' + error.message); return 1 }
+}
+
+if (isMainModule(import.meta.url)) process.exit(runCli(process.argv.slice(2)))

package/skills/engineering/resolve-issues/scripts/round-metadata.mjs

@@ -0,0 +1,79 @@
+import { execFileSync } from 'node:child_process'
+
+export const CHANGED_SURFACES = [
+  'runtime',
+  'tests',
+  'verification-harness',
+  'evidence',
+  'docs',
+  'none',
+]
+
+export const LEGACY_CHANGED_SURFACE = 'unknown'
+
+const SURFACE_ORDER = new Map(CHANGED_SURFACES.map((surface, index) => [surface, index]))
+const TEST_PATH = /(?:^|\/)(?:test|tests|__tests__|spec|specs)(?:\/|$)|\.(?:test|spec)\.[^/]+$/i
+const EVIDENCE_PATH = /(?:^|\/)(?:evidence|artifacts?|screenshots?|snapshots?|traces?)(?:\/|$)|(?:coverage-checklist|smoke-results|smoke-verdict|runtime-smoke)\.(?:json|md)$/i
+const DOC_PATH = /(?:^|\/)(?:docs?|documentation)(?:\/|$)|\.(?:md|mdx|rst|adoc|txt)$/i
+const HARNESS_PATH = /(?:^|\/)(?:e2e|harness|verification|validators?|sanitizers?|gates?|scripts)(?:\/|$)|(?:^|\/)(?:run-state|coverage-ledger|coverage-checklist|lint-tests|scan-diff)\.mjs$/i
+
+const normalizedPath = (value) => String(value).replaceAll('\\', '/').replace(/^\.\//, '')
+
+export function classifyChangedPath(file) {
+  const value = normalizedPath(file)
+  if (!value) return null
+  if (TEST_PATH.test(value)) return 'tests'
+  if (EVIDENCE_PATH.test(value)) return 'evidence'
+  if (DOC_PATH.test(value)) return 'docs'
+  if (HARNESS_PATH.test(value)) return 'verification-harness'
+  return 'runtime'
+}
+
+export function normalizeChangedSurfaces(surfaces, { legacy = false } = {}) {
+  const allowed = legacy ? [...CHANGED_SURFACES, LEGACY_CHANGED_SURFACE] : CHANGED_SURFACES
+  if (!Array.isArray(surfaces) || !surfaces.length) {
+    throw new Error(`changedSurfaces must be a non-empty array of ${allowed.join('|')}`)
+  }
+  const unique = [...new Set(surfaces)]
+  const bad = unique.find((surface) => !allowed.includes(surface))
+  if (bad) throw new Error(`changedSurfaces[] must each be one of ${allowed.join('|')} (got ${JSON.stringify(bad)})`)
+  if (unique.includes('none') && unique.length !== 1) {
+    throw new Error('changedSurfaces "none" is exclusive and cannot be combined with another surface')
+  }
+  if (unique.includes(LEGACY_CHANGED_SURFACE) && unique.length !== 1) {
+    throw new Error('changedSurfaces "unknown" is a legacy-only exclusive classification')
+  }
+  return unique.sort((a, b) => (SURFACE_ORDER.get(a) ?? Number.MAX_SAFE_INTEGER) - (SURFACE_ORDER.get(b) ?? Number.MAX_SAFE_INTEGER))
+}
+
+export function classifyChangedPaths(paths) {
+  const surfaces = [...new Set((Array.isArray(paths) ? paths : []).map(classifyChangedPath).filter(Boolean))]
+  return normalizeChangedSurfaces(surfaces.length ? surfaces : ['none'])
+}
+
+export function deriveChangedSurfaces({ cwd = process.cwd(), fromRef, toRef = 'HEAD' } = {}) {
+  if (typeof fromRef !== 'string' || !fromRef.trim()) throw new Error('fromRef is required to derive changedSurfaces')
+  if (typeof toRef !== 'string' || !toRef.trim()) throw new Error('toRef is required to derive changedSurfaces')
+  let output
+  try {
+    output = execFileSync(
+      'git',
+      ['diff', '--name-only', '--no-renames', '-z', fromRef, toRef, '--'],
+      { cwd, encoding: 'buffer', maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] },
+    )
+  } catch (error) {
+    const detail = error.stderr?.toString().trim() || error.message
+    throw new Error(`cannot derive changedSurfaces from ${fromRef}..${toRef}: ${detail}`)
+  }
+  const paths = output.toString('utf8').split('\0').filter(Boolean)
+  return classifyChangedPaths(paths)
+}
+
+export function assertChangedSurfacesMatch(actual, expected) {
+  const declared = normalizeChangedSurfaces(actual)
+  const derived = normalizeChangedSurfaces(expected)
+  if (JSON.stringify(declared) !== JSON.stringify(derived)) {
+    throw new Error(`changedSurfaces override ${JSON.stringify(declared)} does not match diff-derived ${JSON.stringify(derived)}`)
+  }
+  return derived
+}

package/skills/engineering/resolve-issues/scripts/run-state-review6-cases.mjs

@@ -0,0 +1,334 @@
+// The sole round-7 source of truth for the contract-complete public matrix.
+// Keep the 42 case objects literal: the executor and durable evidence consume
+// these objects rather than maintaining a parallel declaration.
+
+export const MATRIX_THEME = {
+  id: 'generic-writer-composability',
+  kind: 'concurrency',
+  contract: 'Generic writes preserve durable roster identity and dependency-bound history across every run-state state and task kind.',
+  stateSpace: {
+    states: [
+      'staged-manifest',
+      'new-versionless-unit',
+      'new-v2-unit',
+      'existing-versionless-unit',
+      'existing-v2-unit',
+      'existing-protected-unit',
+      'malformed-legacy-unit',
+    ],
+    taskKinds: ['set', 'merge', 'upsert-unit', 'validate', 'migrate-unit', 'round-transition'],
+  },
+}
+
+const NOW = '2026-07-17T00:00:00.000Z'
+const unit = (id = '#809', extra = {}) => ({ id, status: 'in-progress', ...extra })
+const v2 = (id = '#809', extra = {}) => unit(id, { stateVersion: 2, ...extra })
+const protectedHistory = [
+  { round: 1, verdict: 'PASS', themes: [] },
+]
+const protectedUnit = (extra = {}) => v2('#protected', {
+  status: 'in-progress',
+  pr: '#334',
+  branch: 'feat/809-contract-complete-fix-rounds',
+  reviewHistory: structuredClone(protectedHistory),
+  fixRounds: [],
+  ...extra,
+})
+const malformedUnits = () => [unit('#malformed', { reviewHistory: { malformed: true }, fixRounds: ['malformed'] })]
+
+export function fixtureFor(arrange) {
+  switch (arrange) {
+    case 'staged-empty':
+      return { models: { implementation: 'impl' } }
+    case 'new-versionless-empty':
+      return {}
+    case 'new-versionless':
+      return { units: [unit('#809')] }
+    case 'new-v2-empty':
+      return {}
+    case 'new-v2':
+      return { units: [v2('#809')] }
+    case 'existing-versionless':
+      return { units: [unit('#809')] }
+    case 'existing-v2':
+      return { units: [v2('#809')] }
+    case 'existing-protected':
+      return { units: [protectedUnit()] }
+    case 'existing-protected-roster':
+      return { units: [protectedUnit(), unit('#ordinary', { stateVersion: 2, status: 'queued' })] }
+    case 'malformed-legacy':
+      return { units: malformedUnits() }
+    default:
+      throw new Error(`unknown round-7 arrangement ${arrange}`)
+  }
+}
+
+const json = (value) => JSON.stringify(value)
+const operation = (command, args, expectedExitStatus, stderrClass, mutation, assertion, expected = {}) => ({
+  argv: [command, '<slug>', ...args, '--now', NOW],
+  expectedExitStatus,
+  stderrClass,
+  mutation,
+  assertion,
+  expected,
+})
+const reject = (command, args, stderrClass, mutation = 'none/raw-byte-identical', assertion = 'rejection') => operation(command, args, 1, stderrClass, mutation, assertion)
+const accept = (command, args, mutation, assertion, expected = {}) => operation(command, args, 0, 'empty', mutation, assertion, expected)
+const readAccept = (args = []) => operation('validate', args, 0, 'validation-success', 'none/raw-byte-identical', 'read-only')
+const transition = (commands) => ({
+  commands,
+  expectedExitStatus: 0,
+  stderrClass: 'empty',
+  mutation: 'append-only-transition',
+  assertion: 'transition',
+})
+const transitionCommand = (command, unitId, payload, expected) => ({ command, unitId, payload, expected })
+const transitionReject = (commands) => ({
+  commands,
+  expectedExitStatus: 1,
+  stderrClass: 'transition-rejection',
+  mutation: 'none/raw-byte-identical',
+  assertion: 'rejection',
+})
+const markerRewrite = (command, args) => reject(command, args, 'generic-rejection', 'none/raw-byte-identical', 'rejection')
+const metadata = (command, args, expectedUnit) => accept(command, args, 'exact-delta', 'metadata', { unit: expectedUnit })
+export const MATRIX_CASES = [
+  {
+    caseId: 'staged-manifest--set', state: 'staged-manifest', taskKind: 'set', arrange: 'staged-empty',
+    operation: accept('set', ['models.implementation', 'impl-next'], 'exact-delta', 'model-add', { models: { implementation: 'impl-next' } }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:97', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:199',
+  },
+  {
+    caseId: 'staged-manifest--merge', state: 'staged-manifest', taskKind: 'merge', arrange: 'staged-empty',
+    operation: accept('merge', [json({ models: { review: 'review' } })], 'exact-delta', 'model-add', { models: { review: 'review' } }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:102', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:237',
+  },
+  {
+    caseId: 'staged-manifest--upsert-unit', state: 'staged-manifest', taskKind: 'upsert-unit', arrange: 'staged-empty',
+    operation: accept('upsert-unit', [json(unit('#queued', { status: 'queued' }))], 'exact-delta', 'new-id', { unit: unit('#queued', { status: 'queued' }), order: ['#queued'] }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:107', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:274',
+  },
+  {
+    caseId: 'staged-manifest--validate', state: 'staged-manifest', taskKind: 'validate', arrange: 'staged-empty',
+    operation: reject('validate', [], 'validation-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:112', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:312',
+  },
+  {
+    caseId: 'staged-manifest--migrate-unit', state: 'staged-manifest', taskKind: 'migrate-unit', arrange: 'staged-empty',
+    operation: reject('migrate-unit', ['#missing', '--version', '1'], 'migration-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:116', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:347',
+  },
+  {
+    caseId: 'staged-manifest--round-transition', state: 'staged-manifest', taskKind: 'round-transition', arrange: 'staged-empty',
+    operation: transitionReject([
+      transitionCommand('record-review-round', '#missing', { round: 1, verdict: 'PASS', findings: [] }, { type: 'reject' }),
+      transitionCommand('record-fix-round', '#missing', { round: 1, reviewRound: 1, themeId: 'missing' }, { type: 'reject' }),
+    ]), protectedState: [], testLocator: 'run-state-review6-cases.mjs:120', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:385',
+  },
+
+  {
+    caseId: 'new-versionless-unit--set', state: 'new-versionless-unit', taskKind: 'set', arrange: 'new-versionless-empty',
+    operation: accept('set', ['units', json([unit('#809', { status: 'queued' })])], 'exact-delta', 'create-v1', { unit: unit('#809', { status: 'queued' }), order: ['#809'] }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:128', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:434',
+  },
+  {
+    caseId: 'new-versionless-unit--merge', state: 'new-versionless-unit', taskKind: 'merge', arrange: 'new-versionless-empty',
+    operation: accept('merge', [json({ units: [unit('#809', { status: 'queued' })] })], 'exact-delta', 'create-v1', { unit: unit('#809', { status: 'queued' }), order: ['#809'] }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:133', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:472',
+  },
+  {
+    caseId: 'new-versionless-unit--upsert-unit', state: 'new-versionless-unit', taskKind: 'upsert-unit', arrange: 'new-versionless-empty',
+    operation: accept('upsert-unit', [json(unit('#809', { status: 'queued' }))], 'exact-delta', 'create-v1', { unit: unit('#809', { status: 'queued' }), order: ['#809'] }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:138', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:509',
+  },
+  {
+    caseId: 'new-versionless-unit--validate', state: 'new-versionless-unit', taskKind: 'validate', arrange: 'new-versionless',
+    operation: readAccept(), protectedState: [], testLocator: 'run-state-review6-cases.mjs:143', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:546',
+  },
+  {
+    caseId: 'new-versionless-unit--migrate-unit', state: 'new-versionless-unit', taskKind: 'migrate-unit', arrange: 'new-versionless',
+    operation: accept('migrate-unit', ['#809', '--version', '1'], 'migration', 'migration', { unit: v2('#809', { status: 'in-progress', reviewHistory: [] }) }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:147', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:581',
+  },
+  {
+    caseId: 'new-versionless-unit--round-transition', state: 'new-versionless-unit', taskKind: 'round-transition', arrange: 'new-versionless',
+    operation: transitionReject([
+      transitionCommand('record-review-round', '#809', { round: 1, verdict: 'PASS', findings: [] }, { type: 'reject' }),
+      transitionCommand('record-fix-round', '#809', { round: 1, reviewRound: 1, themeId: 'missing' }, { type: 'reject' }),
+    ]), protectedState: [], testLocator: 'run-state-review6-cases.mjs:152', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:620',
+  },
+
+  {
+    caseId: 'new-v2-unit--set', state: 'new-v2-unit', taskKind: 'set', arrange: 'new-v2-empty',
+    operation: accept('set', ['units', json([v2('#809', { status: 'queued' })])], 'exact-delta', 'create-v2', { unit: v2('#809', { status: 'queued' }), order: ['#809'] }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:160', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:669',
+  },
+  {
+    caseId: 'new-v2-unit--merge', state: 'new-v2-unit', taskKind: 'merge', arrange: 'new-v2-empty',
+    operation: accept('merge', [json({ units: [v2('#809', { status: 'queued' })] })], 'exact-delta', 'create-v2', { unit: v2('#809', { status: 'queued' }), order: ['#809'] }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:165', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:707',
+  },
+  {
+    caseId: 'new-v2-unit--upsert-unit', state: 'new-v2-unit', taskKind: 'upsert-unit', arrange: 'new-v2-empty',
+    operation: accept('upsert-unit', [json(v2('#809', { status: 'queued' }))], 'exact-delta', 'create-v2', { unit: v2('#809', { status: 'queued' }), order: ['#809'] }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:170', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:744',
+  },
+  {
+    caseId: 'new-v2-unit--validate', state: 'new-v2-unit', taskKind: 'validate', arrange: 'new-v2',
+    operation: readAccept(), protectedState: [], testLocator: 'run-state-review6-cases.mjs:175', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:781',
+  },
+  {
+    caseId: 'new-v2-unit--migrate-unit', state: 'new-v2-unit', taskKind: 'migrate-unit', arrange: 'new-v2',
+    operation: reject('migrate-unit', ['#809', '--version', '1'], 'migration-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:179', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:816',
+  },
+  {
+    caseId: 'new-v2-unit--round-transition', state: 'new-v2-unit', taskKind: 'round-transition', arrange: 'new-v2',
+    operation: transition([
+      transitionCommand('record-review-round', '#809', { round: 1, verdict: 'PASS', findings: [] }, {
+        type: 'review-append',
+        record: { round: 1, verdict: 'PASS', themes: [] },
+      }),
+    ]), protectedState: [], testLocator: 'run-state-review6-cases.mjs:183', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:854',
+  },
+
+  {
+    caseId: 'existing-versionless-unit--set', state: 'existing-versionless-unit', taskKind: 'set', arrange: 'existing-versionless',
+    operation: markerRewrite('set', ['units', json([unit('#809', { status: 'queued', stateVersion: 2 })])]),
+    variants: [{ name: 'ordinary metadata is allowed', arrange: 'existing-versionless', operation: metadata('set', ['units', json([unit('#809', { status: 'merge-ready', pr: '#809', lastVerdict: 'PASS' })])], unit('#809', { status: 'merge-ready', pr: '#809', lastVerdict: 'PASS' })) }],
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:193', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:892',
+  },
+  {
+    caseId: 'existing-versionless-unit--merge', state: 'existing-versionless-unit', taskKind: 'merge', arrange: 'existing-versionless',
+    operation: markerRewrite('merge', [json({ units: [unit('#809', { status: 'queued', stateVersion: 2 })] })]),
+    variants: [{ name: 'ordinary metadata is allowed', arrange: 'existing-versionless', operation: metadata('merge', [json({ units: [unit('#809', { status: 'merge-ready', pr: '#809', lastVerdict: 'PASS' })] })], unit('#809', { status: 'merge-ready', pr: '#809', lastVerdict: 'PASS' })) }],
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:199', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:961',
+  },
+  {
+    caseId: 'existing-versionless-unit--upsert-unit', state: 'existing-versionless-unit', taskKind: 'upsert-unit', arrange: 'existing-versionless',
+    operation: markerRewrite('upsert-unit', [json(v2('#809', { status: 'queued' }))]),
+    variants: [{ name: 'ordinary metadata is allowed', arrange: 'existing-versionless', operation: metadata('upsert-unit', [json(unit('#809', { status: 'merge-ready', pr: '#809', lastVerdict: 'PASS' }))], unit('#809', { status: 'merge-ready', pr: '#809', lastVerdict: 'PASS' })) }],
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:205', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1028',
+  },
+  {
+    caseId: 'existing-versionless-unit--validate', state: 'existing-versionless-unit', taskKind: 'validate', arrange: 'existing-versionless',
+    operation: readAccept(), protectedState: [], testLocator: 'run-state-review6-cases.mjs:211', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1095',
+  },
+  {
+    caseId: 'existing-versionless-unit--migrate-unit', state: 'existing-versionless-unit', taskKind: 'migrate-unit', arrange: 'existing-versionless',
+    operation: accept('migrate-unit', ['#809', '--version', '1'], 'migration', 'migration', { unit: v2('#809', { status: 'in-progress', reviewHistory: [] }) }),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:215', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1130',
+  },
+  {
+    caseId: 'existing-versionless-unit--round-transition', state: 'existing-versionless-unit', taskKind: 'round-transition', arrange: 'existing-versionless',
+    operation: transitionReject([
+      transitionCommand('record-review-round', '#809', { round: 1, verdict: 'PASS', findings: [] }, { type: 'reject' }),
+      transitionCommand('record-fix-round', '#809', { round: 1, reviewRound: 1, themeId: 'missing' }, { type: 'reject' }),
+    ]), protectedState: [], testLocator: 'run-state-review6-cases.mjs:220', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1169',
+  },
+
+  {
+    caseId: 'existing-v2-unit--set', state: 'existing-v2-unit', taskKind: 'set', arrange: 'existing-v2',
+    operation: metadata('set', ['units', json([v2('#809', { status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })])], v2('#809', { status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:228', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1218',
+  },
+  {
+    caseId: 'existing-v2-unit--merge', state: 'existing-v2-unit', taskKind: 'merge', arrange: 'existing-v2',
+    operation: metadata('merge', [json({ units: [v2('#809', { status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })] })], v2('#809', { status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:233', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1257',
+  },
+  {
+    caseId: 'existing-v2-unit--upsert-unit', state: 'existing-v2-unit', taskKind: 'upsert-unit', arrange: 'existing-v2',
+    operation: metadata('upsert-unit', [json({ id: '#809', status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })], v2('#809', { status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })),
+    protectedState: [], testLocator: 'run-state-review6-cases.mjs:238', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1295',
+  },
+  {
+    caseId: 'existing-v2-unit--validate', state: 'existing-v2-unit', taskKind: 'validate', arrange: 'existing-v2',
+    operation: readAccept(), protectedState: [], testLocator: 'run-state-review6-cases.mjs:243', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1333',
+  },
+  {
+    caseId: 'existing-v2-unit--migrate-unit', state: 'existing-v2-unit', taskKind: 'migrate-unit', arrange: 'existing-v2',
+    operation: reject('migrate-unit', ['#809', '--version', '1'], 'migration-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:247', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1368',
+  },
+  {
+    caseId: 'existing-v2-unit--round-transition', state: 'existing-v2-unit', taskKind: 'round-transition', arrange: 'existing-v2',
+    operation: transition([
+      transitionCommand('record-review-round', '#809', { round: 1, verdict: 'PASS', findings: [] }, {
+        type: 'review-append',
+        record: { round: 1, verdict: 'PASS', themes: [] },
+      }),
+    ]), protectedState: [], testLocator: 'run-state-review6-cases.mjs:251', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1406',
+  },
+
+  {
+    caseId: 'existing-protected-unit--set', state: 'existing-protected-unit', taskKind: 'set', arrange: 'existing-protected',
+    operation: metadata('set', ['units', json([protectedUnit({ status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })])], protectedUnit({ status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })),
+    variants: [
+      { name: 'reorder complete protected roster', arrange: 'existing-protected-roster', operation: accept('set', ['units', json([unit('#ordinary', { stateVersion: 2, status: 'queued' }), protectedUnit()])], 'exact-delta', 'reorder', { order: ['#ordinary', '#protected'] }) },
+      { name: 'add a new ID through set', arrange: 'existing-protected-roster', operation: accept('set', ['units', json([protectedUnit(), unit('#ordinary', { stateVersion: 2, status: 'queued' }), unit('#new', { status: 'queued' })])], 'exact-delta', 'new-id', { unit: unit('#new', { status: 'queued' }), order: ['#protected', '#ordinary', '#new'] }) },
+      { name: 'protected history mutation rejects', arrange: 'existing-protected', operation: reject('set', ['units', json([protectedUnit({ reviewHistory: [...protectedHistory, { round: 2, verdict: 'PASS', themes: [] }] })])], 'generic-rejection') },
+    ],
+    protectedState: ['#protected'], testLocator: 'run-state-review6-cases.mjs:261', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1444',
+  },
+  {
+    caseId: 'existing-protected-unit--merge', state: 'existing-protected-unit', taskKind: 'merge', arrange: 'existing-protected',
+    operation: metadata('merge', [json({ units: [protectedUnit({ status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })] })], protectedUnit({ status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })),
+    variants: [
+      { name: 'add a new ID while retaining protected roster', arrange: 'existing-protected-roster', operation: accept('merge', [json({ units: [protectedUnit(), unit('#ordinary', { stateVersion: 2, status: 'queued' }), unit('#new', { status: 'queued' })] })], 'exact-delta', 'new-id', { unit: unit('#new', { status: 'queued' }), order: ['#protected', '#ordinary', '#new'] }) },
+      { name: 'reorder complete roster through merge', arrange: 'existing-protected-roster', operation: accept('merge', [json({ units: [unit('#ordinary', { stateVersion: 2, status: 'queued' }), protectedUnit()] })], 'exact-delta', 'reorder', { order: ['#ordinary', '#protected'] }) },
+      { name: 'protected history mutation rejects', arrange: 'existing-protected', operation: reject('merge', [json({ units: [protectedUnit({ fixRounds: [{ round: 1 }] })] })], 'generic-rejection') },
+    ],
+    protectedState: ['#protected'], testLocator: 'run-state-review6-cases.mjs:271', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1571',
+  },
+  {
+    caseId: 'existing-protected-unit--upsert-unit', state: 'existing-protected-unit', taskKind: 'upsert-unit', arrange: 'existing-protected',
+    operation: metadata('upsert-unit', [json({ id: '#protected', status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })], protectedUnit({ status: 'merge-ready', pr: '#334', branch: 'feat/809-contract-complete-fix-rounds', lastVerdict: 'PASS' })),
+    variants: [
+      { name: 'protected history mutation rejects', arrange: 'existing-protected', operation: reject('upsert-unit', [json({ id: '#protected', reviewHistory: [...protectedHistory, { round: 2, verdict: 'PASS', themes: [] }] })], 'generic-rejection') },
+      { name: 'add a new ID through upsert-unit', arrange: 'existing-protected-roster', operation: accept('upsert-unit', [json(unit('#new', { status: 'queued' }))], 'exact-delta', 'new-id', { unit: unit('#new', { status: 'queued' }), order: ['#protected', '#ordinary', '#new'] }) },
+    ],
+    protectedState: ['#protected'], testLocator: 'run-state-review6-cases.mjs:281', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1694',
+  },
+  {
+    caseId: 'existing-protected-unit--validate', state: 'existing-protected-unit', taskKind: 'validate', arrange: 'existing-protected',
+    operation: readAccept(), protectedState: ['#protected'], testLocator: 'run-state-review6-cases.mjs:290', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1789',
+  },
+  {
+    caseId: 'existing-protected-unit--migrate-unit', state: 'existing-protected-unit', taskKind: 'migrate-unit', arrange: 'existing-protected',
+    operation: reject('migrate-unit', ['#protected', '--version', '1'], 'migration-rejection'), protectedState: ['#protected'], testLocator: 'run-state-review6-cases.mjs:294', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1824',
+  },
+  {
+    caseId: 'existing-protected-unit--round-transition', state: 'existing-protected-unit', taskKind: 'round-transition', arrange: 'existing-protected',
+    operation: transitionReject([
+      // Pre-#888 deep history is readable, but appending without universal typed rounds
+      // would keep writing the old schema. Reconstruct unknown classifications first.
+      transitionCommand('record-review-round', '#protected', { round: 2, verdict: 'PASS', findings: [] }, { type: 'reject' }),
+    ]), protectedState: ['#protected'], testLocator: 'run-state-review6-cases.mjs:298', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1862',
+  },
+  {
+    caseId: 'malformed-legacy-unit--set', state: 'malformed-legacy-unit', taskKind: 'set', arrange: 'malformed-legacy',
+    operation: reject('set', ['units', json([unit('#malformed', { status: 'merge-ready', reviewHistory: { malformed: true }, fixRounds: ['malformed'] })])], 'generic-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:306', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1899',
+  },
+  {
+    caseId: 'malformed-legacy-unit--merge', state: 'malformed-legacy-unit', taskKind: 'merge', arrange: 'malformed-legacy',
+    operation: reject('merge', [json({ units: [unit('#malformed', { status: 'merge-ready' })] })], 'generic-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:310', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1936',
+  },
+  {
+    caseId: 'malformed-legacy-unit--upsert-unit', state: 'malformed-legacy-unit', taskKind: 'upsert-unit', arrange: 'malformed-legacy',
+    operation: reject('upsert-unit', [json({ id: '#malformed', status: 'merge-ready' })], 'generic-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:314', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:1972',
+  },
+  {
+    caseId: 'malformed-legacy-unit--validate', state: 'malformed-legacy-unit', taskKind: 'validate', arrange: 'malformed-legacy',
+    operation: reject('validate', [], 'validation-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:318', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:2008',
+  },
+  {
+    caseId: 'malformed-legacy-unit--migrate-unit', state: 'malformed-legacy-unit', taskKind: 'migrate-unit', arrange: 'malformed-legacy',
+    operation: reject('migrate-unit', ['#malformed', '--version', '1'], 'migration-rejection'), protectedState: [], testLocator: 'run-state-review6-cases.mjs:322', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:2043',
+  },
+  {
+    caseId: 'malformed-legacy-unit--round-transition', state: 'malformed-legacy-unit', taskKind: 'round-transition', arrange: 'malformed-legacy',
+    operation: transitionReject([
+      transitionCommand('record-review-round', '#malformed', { round: 1, verdict: 'PASS', findings: [] }, { type: 'reject' }),
+      transitionCommand('record-fix-round', '#malformed', { round: 1, reviewRound: 1, themeId: 'missing' }, { type: 'reject' }),
+    ]), protectedState: [], testLocator: 'run-state-review6-cases.mjs:326', evidenceLocator: 'docs/evidence/809-runtime-smoke.json:2081',
+  },
+]
+
+if (MATRIX_CASES.length !== 42) throw new Error(`round-6 matrix must contain exactly 42 literal cases; got ${MATRIX_CASES.length}`)