@1aboveio/skills 0.10.0

package/skills/engineering/review-pr/schemas/findings.schema.json

@@ -0,0 +1,282 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "review-pr findings",
+  "description": "Canonical review document and finding contract. Generated from scripts/finding-contract.mjs and consumed by scripts/post-review.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "verdict",
+    "findings"
+  ],
+  "properties": {
+    "verdict": {
+      "enum": [
+        "PASS",
+        "NEEDS_CHANGES",
+        "FAIL",
+        "BLOCKED"
+      ]
+    },
+    "summary": {
+      "type": "string"
+    },
+    "overall_correctness": {
+      "enum": [
+        "correct",
+        "incorrect"
+      ]
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "title",
+          "axis",
+          "file",
+          "line_start",
+          "confidence",
+          "why",
+          "priority"
+        ],
+        "properties": {
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S",
+            "maxLength": 120
+          },
+          "axis": {
+            "type": "string",
+            "enum": [
+              "spec",
+              "coverage",
+              "correctness",
+              "standards"
+            ]
+          },
+          "subject": {
+            "type": "string",
+            "description": "What the finding is about: the code under review ('code', the default) or the evidence describing it \u2014 Review Contract wording, coverage-checklist rows, evidence locators, test-level tags ('evidence'). Absent means 'code'. Callers use this to route a round whose production diff has not moved; misclassifying a code defect as evidence skips its adversarial re-review, so classify 'evidence' only when the fix touches no source file.",
+            "enum": [
+              "code",
+              "evidence"
+            ],
+            "default": "code"
+          },
+          "in_scope": {
+            "type": "boolean",
+            "default": true
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 3
+          },
+          "file": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "line_start": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "line_count": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "why": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "consequence": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "recommendation": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "theme": {
+            "$ref": "#/$defs/theme"
+          },
+          "hazard_candidate": {
+            "$ref": "#/$defs/hazard_candidate"
+          }
+        }
+      }
+    },
+    "overMockFindings": {
+      "type": "array"
+    },
+    "previousFindingsResolution": {
+      "type": "array"
+    },
+    "reviewModel": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "independent": {
+      "type": "boolean"
+    },
+    "contractValidates": {
+      "type": "boolean"
+    }
+  },
+  "$defs": {
+    "theme": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "contract"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "other",
+            "state-machine",
+            "concurrency"
+          ]
+        },
+        "contract": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "stateSpace": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "states",
+            "taskKinds"
+          ],
+          "properties": {
+            "states": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              }
+            },
+            "taskKinds": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              }
+            }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "enum": [
+                  "state-machine",
+                  "concurrency"
+                ]
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "stateSpace"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "other"
+              }
+            }
+          },
+          "then": {
+            "not": {
+              "required": [
+                "stateSpace"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "hazard_candidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": [
+            "section",
+            "id",
+            "rule",
+            "prove"
+          ]
+        },
+        {
+          "required": [
+            "covered_by"
+          ]
+        }
+      ],
+      "properties": {
+        "section": {
+          "type": "string",
+          "enum": [
+            "auth",
+            "money",
+            "tenancy",
+            "migration",
+            "cross-cutting"
+          ]
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "rule": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "prove": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        },
+        "covered_by": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S"
+        }
+      }
+    }
+  }
+}

package/skills/engineering/review-pr/scripts/finding-contract.mjs

@@ -0,0 +1,285 @@
+// Canonical review finding/document contract.
+//
+// This module is the executable source of truth for the review-pr JSON schema,
+// post-review enforcement, and resolve-issues durable review history. The JSON
+// schema and the import-free workflow schema are generated/kept in parity with
+// these definitions; consumers must use the validators below for enforcement.
+
+import { validateTheme, THEME_KINDS } from './theme-contract.mjs'
+
+export const REVIEW_VERDICTS = ['PASS', 'NEEDS_CHANGES', 'FAIL', 'BLOCKED']
+export const FINDING_AXES = ['spec', 'coverage', 'correctness', 'standards']
+// What the finding is *about*, orthogonal to axis and to severity: the code under
+// review, or the material describing it. Absent means 'code' — the overwhelming
+// default — so existing producers stay valid. Callers route the evidence-only lane
+// on this (resolve-issues § Fix); only the reviewer read the diff, so only the
+// reviewer can set it.
+export const FINDING_SUBJECTS = ['code', 'evidence']
+export const FINDING_KEYS = [
+  'title', 'axis', 'subject', 'in_scope', 'priority', 'file', 'line_start', 'line_count',
+  'confidence', 'why', 'consequence', 'recommendation', 'theme', 'hazard_candidate',
+]
+// Fields the schema no longer defines but still *tolerates on read* — a finding
+// carrying one does not hard-fail; it warns (findingWarnings) and the value is
+// ignored. `blocking` was removed (#399): it is derived, never stored, as
+// `in_scope && priority <= 1`, so a persisted `blocking` is at best redundant and
+// at worst contradicts the derived value. Same removed-field posture as
+// resolve-issues run-state's obsolete-slot warnings.
+export const FINDING_OBSOLETE_KEYS = ['blocking']
+// Lean core: what every finding owes — a located, confident, explained defect.
+// consequence/recommendation/line_count are welcome but optional; `theme` is the
+// deep lane's identity mechanism (resolve-issues/references/high-risk.md) and is
+// validated only when present — forcing a taxonomy entry per lean-lane finding
+// was pure ceremony and schema-retry surface.
+export const FINDING_REQUIRED = [
+  'title', 'axis', 'file', 'line_start', 'confidence', 'why', 'priority',
+]
+export const FINDING_CONTRACT_VERSION = 2
+
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+const nonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key)
+
+function unknownKeys(value, allowed, label) {
+  return Object.keys(value || {})
+    .filter((key) => !allowed.includes(key))
+    .map((key) => `${label} has unknown property: ${key}`)
+}
+
+function validateHazardCandidate(value, index) {
+  if (value === undefined) return []
+  if (!isObject(value)) return [`finding[${index}]: hazard_candidate must be an object`]
+  const errors = unknownKeys(value, ['section', 'id', 'rule', 'prove', 'covered_by'], `finding[${index}].hazard_candidate`)
+  const covered = nonEmptyString(value.covered_by)
+  const complete = ['section', 'id', 'rule', 'prove'].every((key) => nonEmptyString(value[key]))
+  if (!covered && !complete) {
+    errors.push(`finding[${index}]: hazard_candidate requires section/id/rule/prove or covered_by`)
+  }
+  if (value.section !== undefined && !['auth', 'money', 'tenancy', 'migration', 'cross-cutting'].includes(value.section)) {
+    errors.push(`finding[${index}]: hazard_candidate.section is invalid`)
+  }
+  if (value.id !== undefined && (!nonEmptyString(value.id) || !/^[a-z][a-z0-9-]*$/.test(value.id))) {
+    errors.push(`finding[${index}]: hazard_candidate.id must be kebab-case`)
+  }
+  for (const key of ['rule', 'prove', 'covered_by']) {
+    if (value[key] !== undefined && !nonEmptyString(value[key])) errors.push(`finding[${index}]: hazard_candidate.${key} is required`)
+  }
+  return errors
+}
+
+export function validateFinding(finding, index = 0) {
+  const prefix = `finding[${index}]`
+  if (!isObject(finding)) return [`${prefix}: finding must be an object`]
+  // Obsolete keys (e.g. removed `blocking`) are read-tolerated, not unknown: they
+  // never error — findingWarnings surfaces them and the value is ignored.
+  const errors = unknownKeys(finding, [...FINDING_KEYS, ...FINDING_OBSOLETE_KEYS], prefix)
+  for (const key of FINDING_REQUIRED) {
+    if (!hasOwn(finding, key)) errors.push(`${prefix}: missing ${key}`)
+  }
+  if (!nonEmptyString(finding.title) || (typeof finding.title === 'string' && finding.title.length > 120)) {
+    errors.push(`${prefix}: title must be a non-empty string of at most 120 characters`)
+  }
+  if (!FINDING_AXES.includes(finding.axis)) errors.push(`${prefix}: axis must be one of ${FINDING_AXES.join('|')}`)
+  if (!nonEmptyString(finding.file)) errors.push(`${prefix}: file is required (a finding must locate changed code)`)
+  if (!Number.isInteger(finding.line_start) || finding.line_start < 1) errors.push(`${prefix}: line_start must be a positive integer`)
+  if (finding.line_count !== undefined && (!Number.isInteger(finding.line_count) || finding.line_count < 1)) {
+    errors.push(`${prefix}: line_count must be a positive integer`)
+  }
+  if (typeof finding.confidence !== 'number' || !Number.isFinite(finding.confidence) || finding.confidence < 0 || finding.confidence > 1) {
+    errors.push(`${prefix}: confidence must be a number in 0..1`)
+  }
+  if (!nonEmptyString(finding.why)) errors.push(`${prefix}: why is required`)
+  for (const key of ['consequence', 'recommendation']) {
+    if (finding[key] !== undefined && !nonEmptyString(finding[key])) errors.push(`${prefix}: ${key} must be a non-empty string when present`)
+  }
+  if (finding.priority !== undefined && (!Number.isInteger(finding.priority) || finding.priority < 0 || finding.priority > 3)) {
+    errors.push(`${prefix}: priority must be an integer in 0..3`)
+  }
+  if (finding.in_scope !== undefined && typeof finding.in_scope !== 'boolean') errors.push(`${prefix}: in_scope must be boolean`)
+  if (finding.theme !== undefined) errors.push(...validateTheme(finding.theme).map((error) => `${prefix}: ${error}`))
+  errors.push(...validateHazardCandidate(finding.hazard_candidate, index))
+  return errors
+}
+
+// Read-tolerance for removed fields (#399): a finding still carrying an obsolete
+// key is not rejected (validateFinding accepts it) but earns a warning so the
+// producer drops it. The derived value is authoritative; the stored one is
+// ignored. Callers print these; they never gate.
+export function findingWarnings(finding, index = 0) {
+  if (!isObject(finding)) return []
+  const warnings = []
+  if (hasOwn(finding, 'blocking')) {
+    warnings.push(`finding[${index}]: blocking is obsolete — it was removed and is now derived as (in_scope && priority <= 1); the stored value is ignored, drop the field`)
+  }
+  return warnings
+}
+
+export function reviewDocumentWarnings(document) {
+  if (!isObject(document) || !Array.isArray(document.findings)) return []
+  return document.findings.flatMap((finding, index) => findingWarnings(finding, index))
+}
+
+// Derived severity/routing from the two canonical fields. `blocking` is NEVER a
+// stored field — it is this function. `in_scope` defaults true (a finding is
+// about the diff unless the reviewer says otherwise). priority<=1 is a blocker
+// only when in scope; a p0/p1 out-of-scope finding is a dedicated critical issue,
+// not a PR-holding blocker.
+export function findingInScope(finding) {
+  return finding.in_scope !== false
+}
+
+export function isBlockingFinding(finding) {
+  return findingInScope(finding) && Number.isInteger(finding.priority) && finding.priority <= 1
+}
+
+export function isOutOfScopeCritical(finding) {
+  return !findingInScope(finding) && Number.isInteger(finding.priority) && finding.priority <= 1
+}
+
+// Legacy range support is deliberately explicit. Normal validation never
+// silently accepts or rewrites line_end.
+export function migrateLegacyFinding(finding, { version } = {}) {
+  if (version !== 1) throw new Error('legacy finding migration requires version 1')
+  if (!isObject(finding)) throw new Error('legacy finding must be an object')
+  if (hasOwn(finding, 'line_count')) throw new Error('legacy finding must use line_end, not line_count')
+  // A real v1 finding predates the #399 field changes: it may carry an obsolete key
+  // (e.g. `blocking`, which landed 2026-07-16) and may lack `priority` (optional
+  // pre-#399). Mirror validateFinding's read-tolerance — allow obsolete keys through
+  // (findingWarnings surfaces them, drop them on write) instead of hard-failing, so a
+  // historically-real finding stays migratable rather than bricking the whole unit.
+  const errors = unknownKeys(finding, [...FINDING_KEYS.filter((key) => key !== 'line_count'), ...FINDING_OBSOLETE_KEYS, 'line_end'], 'legacy finding')
+  for (const key of ['line_start', 'line_end']) {
+    if (!Number.isInteger(finding[key]) || finding[key] < 1) errors.push(`legacy finding ${key} must be a positive integer`)
+  }
+  if (Number.isInteger(finding.line_start) && Number.isInteger(finding.line_end) && finding.line_end < finding.line_start) {
+    errors.push('legacy finding line_end < line_start (reversed range)')
+  }
+  if (errors.length) throw new Error(errors.join('; '))
+  const { line_end, ...withoutEnd } = structuredClone(finding)
+  // Drop every obsolete key: the derived value is authoritative, the stored one ignored.
+  for (const key of FINDING_OBSOLETE_KEYS) delete withoutEnd[key]
+  const migrated = { ...withoutEnd, line_count: line_end - finding.line_start + 1 }
+  // Backfill the now-required priority when a pre-#399 finding lacks it: a stored
+  // blocking:true was an in-scope blocker → priority 1; anything else is an
+  // un-prioritized legacy note → priority 2 (a sensible non-blocking severity).
+  if (!hasOwn(migrated, 'priority')) migrated.priority = finding.blocking === true ? 1 : 2
+  return migrated
+}
+
+export function migrateLegacyReviewDocument(document, { version } = {}) {
+  if (version !== 1) throw new Error('legacy review migration requires version 1')
+  if (!isObject(document) || !Array.isArray(document.findings)) throw new Error('legacy review document requires findings')
+  return { ...structuredClone(document), findings: document.findings.map((finding) => migrateLegacyFinding(finding, { version: 1 })) }
+}
+
+const DOCUMENT_KEYS = [
+  'verdict', 'summary', 'overall_correctness', 'findings', 'overMockFindings',
+  'previousFindingsResolution', 'reviewModel', 'independent', 'contractValidates',
+]
+
+export function validateReviewDocument(document) {
+  if (!isObject(document)) return ['review document must be an object']
+  const errors = unknownKeys(document, DOCUMENT_KEYS, 'review document')
+  if (!REVIEW_VERDICTS.includes(document.verdict)) errors.push(`review document verdict must be one of ${REVIEW_VERDICTS.join('|')}`)
+  if (document.summary !== undefined && typeof document.summary !== 'string') errors.push('review document summary must be a string')
+  if (document.overall_correctness !== undefined && !['correct', 'incorrect'].includes(document.overall_correctness)) {
+    errors.push('review document overall_correctness must be correct|incorrect')
+  }
+  if (!Array.isArray(document.findings)) errors.push('review document findings is not an array')
+  else document.findings.forEach((finding, index) => errors.push(...validateFinding(finding, index)))
+  if (document.overMockFindings !== undefined && !Array.isArray(document.overMockFindings)) errors.push('review document overMockFindings must be an array')
+  if (document.previousFindingsResolution !== undefined && !Array.isArray(document.previousFindingsResolution)) errors.push('review document previousFindingsResolution must be an array')
+  if (document.reviewModel !== undefined && !nonEmptyString(document.reviewModel)) errors.push('review document reviewModel must be a non-empty string')
+  if (document.independent !== undefined && typeof document.independent !== 'boolean') errors.push('review document independent must be boolean')
+  if (document.contractValidates !== undefined && typeof document.contractValidates !== 'boolean') errors.push('review document contractValidates must be boolean')
+  return errors
+}
+
+// Canonical schema object used to generate schemas/findings.schema.json and to
+// mechanically compare the import-free independent-review workflow contract.
+export const FINDING_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: FINDING_REQUIRED,
+  properties: {
+    title: { type: 'string', minLength: 1, pattern: '\\S', maxLength: 120 },
+    axis: { type: 'string', enum: FINDING_AXES },
+    subject: { type: 'string', enum: FINDING_SUBJECTS, default: 'code' },
+    in_scope: { type: 'boolean', default: true },
+    priority: { type: 'integer', minimum: 0, maximum: 3 },
+    file: { type: 'string', minLength: 1, pattern: '\\S' },
+    line_start: { type: 'integer', minimum: 1 },
+    line_count: { type: 'integer', minimum: 1 },
+    confidence: { type: 'number', minimum: 0, maximum: 1 },
+    why: { type: 'string', minLength: 1, pattern: '\\S' },
+    consequence: { type: 'string', minLength: 1, pattern: '\\S' },
+    recommendation: { type: 'string', minLength: 1, pattern: '\\S' },
+    theme: { $ref: '#/$defs/theme' },
+    hazard_candidate: { $ref: '#/$defs/hazard_candidate' },
+  },
+}
+
+export const FINDING_SCHEMA_DEFS = {
+  theme: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'kind', 'contract'],
+    properties: {
+      id: { type: 'string', pattern: '^[a-z][a-z0-9-]*$' },
+      kind: { type: 'string', enum: THEME_KINDS },
+      contract: { type: 'string', minLength: 1, pattern: '\\S' },
+      stateSpace: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['states', 'taskKinds'],
+        properties: {
+          states: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string', minLength: 1, pattern: '\\S' } },
+          taskKinds: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string', minLength: 1, pattern: '\\S' } },
+        },
+      },
+    },
+    allOf: [
+      {
+        if: { properties: { kind: { enum: ['state-machine', 'concurrency'] } } },
+        then: { required: ['stateSpace'] },
+      },
+      {
+        if: { properties: { kind: { const: 'other' } } },
+        then: { not: { required: ['stateSpace'] } },
+      },
+    ],
+  },
+  hazard_candidate: {
+    type: 'object',
+    additionalProperties: false,
+    anyOf: [
+      { required: ['section', 'id', 'rule', 'prove'] },
+      { required: ['covered_by'] },
+    ],
+    properties: {
+      section: { type: 'string', enum: ['auth', 'money', 'tenancy', 'migration', 'cross-cutting'] },
+      id: { type: 'string', pattern: '^[a-z][a-z0-9-]*$' },
+      rule: { type: 'string', minLength: 1, pattern: '\\S' },
+      prove: { type: 'string', minLength: 1, pattern: '\\S' },
+      covered_by: { type: 'string', minLength: 1, pattern: '\\S' },
+    },
+  },
+}
+
+export const REVIEW_DOCUMENT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['verdict', 'findings'],
+  properties: {
+    verdict: { enum: REVIEW_VERDICTS },
+    summary: { type: 'string' },
+    overall_correctness: { enum: ['correct', 'incorrect'] },
+    findings: { type: 'array', items: FINDING_SCHEMA },
+    overMockFindings: { type: 'array' },
+    previousFindingsResolution: { type: 'array' },
+    reviewModel: { type: 'string', minLength: 1, pattern: '\\S' },
+    independent: { type: 'boolean' },
+    contractValidates: { type: 'boolean' },
+  },
+  $defs: FINDING_SCHEMA_DEFS,
+}