@llm4ts/flow 2.30.1 → 2.31.0

package/src/OracleGuard.ts

@@ -0,0 +1,205 @@
+// The oracle guard (ADR 0027, decision 4): a change may not delete a test
+// file, add a skip or focus marker, or lower the passed-test count unless
+// its plan entry says it may. Deterministic, from the diff and the gate
+// output; a violation is a gate failure the fix round can undo.
+import * as Schema from "effect/Schema"
+import { ReviewIssue } from "./Review.ts"
+
+export class OracleRules extends Schema.Class<OracleRules>("OracleRules")({
+  /** Regex source: a path matching it is a test file. */
+  testFiles: Schema.String,
+  /** Substrings whose appearance on an added line marks a skipped or focused test. */
+  markers: Schema.Array(Schema.String)
+}) {}
+
+export const defaultOracleRules = OracleRules.make({
+  testFiles:
+    "(?:^|/)(?:__tests__|tests?|spec|src/test)/|\\.(?:test|spec)\\.[cm]?[jt]sx?$|_test\\.(?:go|py|rs)$|Tests?\\.(?:java|kt|scala|cs)$|^tests?_.*\\.py$",
+  markers: [
+    ".skip(",
+    ".only(",
+    "xit(",
+    "xdescribe(",
+    "xtest(",
+    "test.todo(",
+    "it.todo(",
+    "@Ignore",
+    "@Disabled",
+    "@pytest.mark.skip",
+    "#[ignore]"
+  ]
+})
+
+/** The parsed body of a pack's `## Oracle` section: `- tests: <regex>` and `- markers: a, b`. */
+export const oracleRulesFrom = (fields: {
+  readonly tests?: string
+  readonly markers?: ReadonlyArray<string>
+}): OracleRules =>
+  OracleRules.make({
+    testFiles: fields.tests ?? defaultOracleRules.testFiles,
+    markers: [...defaultOracleRules.markers, ...(fields.markers ?? [])]
+  })
+
+export interface AddedLine {
+  readonly file: string
+  readonly line: number
+  readonly text: string
+}
+
+export interface DiffShape {
+  /** Files the diff deletes outright. */
+  readonly deleted: ReadonlyArray<string>
+  /** Lines the diff adds, with the path and the new line number. */
+  readonly added: ReadonlyArray<AddedLine>
+}
+
+const fileHeader = /^diff --git a\/(.+?) b\/(.+)$/u
+const hunkHeader = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/u
+
+/** The deletions and added lines of a unified diff; pure, tolerant of noise between files. */
+export const parseUnifiedDiff = (diff: string): DiffShape => {
+  const deleted: Array<string> = []
+  const added: Array<AddedLine> = []
+  let file: string | undefined
+  let line = 0
+  let inHunk = false
+  for (const raw of diff.split(/\r?\n/u)) {
+    const header = fileHeader.exec(raw)
+    if (header !== null) {
+      file = header[2]
+      inHunk = false
+      continue
+    }
+    if (file === undefined) continue
+    if (raw.startsWith("deleted file mode")) {
+      deleted.push(file)
+      continue
+    }
+    const hunk = hunkHeader.exec(raw)
+    if (hunk !== null) {
+      line = Number.parseInt(hunk[1] ?? "0", 10)
+      inHunk = true
+      continue
+    }
+    if (!inHunk) continue
+    if (raw.startsWith("+++") || raw.startsWith("---")) continue
+    if (raw.startsWith("+")) {
+      added.push({ file, line, text: raw.slice(1) })
+      line += 1
+    } else if (raw.startsWith("-")) {
+      // a removed line: the new file's numbering does not advance
+    } else if (raw.startsWith("\\")) {
+      // ""
+    } else {
+      line += 1
+    }
+  }
+  return { deleted, added }
+}
+
+const vitestLike = /\bTests\b[^\n]*?(\d+)\s+passed/u
+const jestLike = /\bTests:\s[^\n]*?(\d+)\s+passed/u
+const pytestLike = /(?:^|\n)[^\n]*?\b(\d+)\s+passed\b[^\n]*\bin\s+[\d.]+s/u
+const cargoLike = /test result:[^\n]*?(\d+)\s+passed/u
+const mochaLike = /(?:^|\n)\s*(\d+)\s+passing\b/u
+const junitLike =
+  /Tests run:\s*(\d+),\s*Failures:\s*(\d+),\s*Errors:\s*(\d+)(?:,\s*Skipped:\s*(\d+))?/gu
+
+/**
+ * The passed-test count in a test runner's output, when a summary line the
+ * guard knows is present (Vitest, Jest, pytest, cargo test, mocha, JUnit
+ * via Maven/Gradle); `undefined` otherwise, which the guard reports as an
+ * Info rather than a verdict.
+ */
+export const passedCountIn = (output: string): number | undefined => {
+  for (const pattern of [vitestLike, jestLike, cargoLike, pytestLike, mochaLike]) {
+    const match = pattern.exec(output)
+    if (match?.[1] !== undefined) {
+      return Number.parseInt(match[1], 10)
+    }
+  }
+  // Maven prints a line per class and one grand total; the largest run is the total.
+  let largestRun = -1
+  let passedOfLargest: number | undefined
+  junitLike.lastIndex = 0
+  for (let match = junitLike.exec(output); match !== null; match = junitLike.exec(output)) {
+    const run = Number.parseInt(match[1] ?? "0", 10)
+    const failures = Number.parseInt(match[2] ?? "0", 10)
+    const errors = Number.parseInt(match[3] ?? "0", 10)
+    const skipped = Number.parseInt(match[4] ?? "0", 10)
+    if (run >= largestRun) {
+      largestRun = run
+      passedOfLargest = run - failures - errors - skipped
+    }
+  }
+  return passedOfLargest
+}
+
+export interface OracleCounts {
+  /** Tests passing on the base, from its baseline; `undefined` when unknown. */
+  readonly base: number | undefined
+  /** Tests passing on the change, from its test gate; `undefined` when unknown. */
+  readonly current: number | undefined
+}
+
+export const oracleIssuePrefix = "oracle: "
+
+/**
+ * The guard's verdict on a change: one Critical per deleted test file, one
+ * per added marker (with `file:line`), one for a passed-count drop; empty
+ * when `declared` (the plan entry says tests may change). Counts are judged
+ * only when both are known; a caller reports the unknown case as an Info.
+ */
+export const checkOracle = (
+  diff: DiffShape,
+  counts: OracleCounts | undefined,
+  rules: OracleRules,
+  declared: boolean
+): ReadonlyArray<ReviewIssue> => {
+  if (declared) {
+    return []
+  }
+  const testFile = new RegExp(rules.testFiles, "u")
+  const issues: Array<ReviewIssue> = []
+  for (const path of diff.deleted) {
+    if (testFile.test(path)) {
+      issues.push(
+        ReviewIssue.make({
+          severity: "Critical",
+          title: `${oracleIssuePrefix}test file deleted: ${path}`,
+          description:
+            "Restore it. A story may not delete a test unless its plan entry declares `testsChange: true`.",
+          file: path
+        })
+      )
+    }
+  }
+  for (const line of diff.added) {
+    if (!testFile.test(line.file)) continue
+    const marker = rules.markers.find((candidate) => line.text.includes(candidate))
+    if (marker === undefined) continue
+    issues.push(
+      ReviewIssue.make({
+        severity: "Critical",
+        title: `${oracleIssuePrefix}skip or focus marker added: ${marker.trim()}`,
+        description: `${line.file}:${line.line}: ${line.text.trim()}\nRemove the marker and make the test pass, or report the test as wrong in your Findings.`,
+        file: line.file,
+        line: line.line
+      })
+    )
+  }
+  if (counts?.base !== undefined && counts.current !== undefined && counts.current < counts.base) {
+    issues.push(
+      ReviewIssue.make({
+        severity: "Critical",
+        title: `${oracleIssuePrefix}fewer tests pass than on the base (${counts.current} < ${counts.base})`,
+        description:
+          "Tests were removed, skipped or no longer discovered. Restore them; declare `testsChange: true` on the story if the change is intended."
+      })
+    )
+  }
+  return issues
+}
+
+export const isOracleIssue = (issue: ReviewIssue): boolean =>
+  issue.title.startsWith(oracleIssuePrefix)

package/src/Pack.ts

@@ -3,6 +3,7 @@ import * as Schema from "effect/Schema"
 import { Dimension } from "@llm4ts/core/eval/Eval"
 import type { ConsolidateRules } from "./Domains.ts"
 import { PlanParseError } from "./FlowError.ts"
+import { oracleRulesFrom, type OracleRules } from "./OracleGuard.ts"
 import { parseReviewer, type Reviewer } from "./Reviewer.ts"
 import { CoverageRule } from "./SpecChecks.ts"
 import type { WorkspaceError, WorkspaceShape } from "./Workspace.ts"
@@ -67,6 +68,12 @@ export interface Pack {
    * fragment as context (`context:`). Absent: every program is its own feature.
    */
   readonly consolidate: ConsolidateRules | undefined
+  /**
+   * The `## Oracle` section (ADR 0027): `- tests: <regex>` for what a test
+   * file is and `- markers: a, b` for extra skip or focus markers, merged
+   * over the defaults. Absent: the defaults.
+   */
+  readonly oracle: OracleRules | undefined
   readonly dir: string
   readonly gate: (name: string) => ReadonlyArray<string> | undefined
   readonly prompt: (name: string) => string | undefined
@@ -266,6 +273,14 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
       message: `pack manifest 'spec-schema:' must be 'pagespec' when set, got: ${specSchema}`
     })
   }
+  const oracleValues = namedItems(section(manifest.sections, "Oracle"))
+  const oracle: OracleRules | undefined =
+    section(manifest.sections, "Oracle") === undefined
+      ? undefined
+      : oracleRulesFrom({
+          ...(oracleValues.tests === undefined ? {} : { tests: oracleValues.tests }),
+          markers: commaList(oracleValues.markers)
+        })
   const consolidateValues = namedItems(section(manifest.sections, "Consolidate"))
   const consolidate: ConsolidateRules | undefined =
     section(manifest.sections, "Consolidate") === undefined
@@ -330,6 +345,7 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     featureFiles,
     specSchema,
     consolidate,
+    oracle,
     dir: directory,
     gate: (name) => gates[name],
     prompt: (name) => prompts[name],

package/src/Retro.ts

@@ -461,6 +461,13 @@ export const renderRetroDigest = (inputs: RetroInputs): string => {
       case "CapabilityUnenforceable":
         runLines.push(`- capability unenforceable: ${event.detail}`)
         break
+      case "EvidenceChecked":
+        if (event.unverified > 0) {
+          runLines.push(
+            `- fabricated status: task "${event.task}"${event.lane === undefined ? "" : ` (story ${event.lane})`} claimed ${event.unverified} command(s) that never ran`
+          )
+        }
+        break
       case "ExecutorExcluded":
         runLines.push(`- executor excluded: ${event.executor} — ${event.reason}`)
         break

package/src/Review.ts

@@ -1,16 +1,26 @@
 import { join } from "node:path"
 import * as Clock from "effect/Clock"
+import * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
 import type { LlmError } from "@llm4ts/core/Errors"
 import type { LlmServiceShape } from "@llm4ts/core/LlmService"
 import type { JsonSchema } from "@llm4ts/core/Models"
-import type { ProcessExecutorShape } from "@llm4ts/core/ProcessExecutor"
+import type { ProcessExecutorShape, ProcessResult } from "@llm4ts/core/ProcessExecutor"
 import { Capabilities } from "@llm4ts/core/Capability"
 import { guarded } from "./CapabilityGuard.ts"
 import type { Chat } from "./Chat.ts"
 import { FlowLlmError, ProcessError, describeFlowError, type FlowError } from "./FlowError.ts"
 import type { PlainFileStoreShape } from "./Persistence.ts"
+import { GateBaseline, isGateIssue, triageGates } from "./GateTriage.ts"
+import {
+  type OracleRules,
+  checkOracle,
+  defaultOracleRules,
+  parseUnifiedDiff,
+  passedCountIn
+} from "./OracleGuard.ts"
 import { cachedReview, fingerprintOf } from "./ReviewCache.ts"
 import {
   Info,
@@ -51,7 +61,13 @@ export class ReviewIssue extends Schema.Class<ReviewIssue>("ReviewIssue")({
   confidence: Schema.Number.pipe(
     Schema.withConstructorDefault(Effect.succeed(1)),
     Schema.withDecodingDefaultKey(Effect.succeed(1))
-  )
+  ),
+  /** A gate failure's triage against the base (ADR 0027); absent for review findings. */
+  origin: Schema.optionalKey(Schema.Literals(["new", "base", "flaky"])),
+  /** How a gate ended: a red exit, killed at the timeout, or a signal exit. */
+  gateClass: Schema.optionalKey(Schema.Literals(["red", "hang", "crash"])),
+  /** Where the gate's full output was written, when the caller asked for a log. */
+  logPath: Schema.optionalKey(Schema.String)
 }) {}
 
 export class ReviewResult extends Schema.Class<ReviewResult>("ReviewResult")({
@@ -59,7 +75,9 @@ export class ReviewResult extends Schema.Class<ReviewResult>("ReviewResult")({
   summary: Schema.String.pipe(
     Schema.withConstructorDefault(Effect.succeed("")),
     Schema.withDecodingDefaultKey(Effect.succeed(""))
-  )
+  ),
+  /** A test gate's passed-test count, when its output had a summary the oracle guard reads (ADR 0027). */
+  passed: Schema.optionalKey(Schema.Int)
 }) {
   get isClean(): boolean {
     return this.issues.length === 0
@@ -241,20 +259,165 @@ export const reviewPrompt = (task: string, diff: string): string =>
     diff
   ].join("\n")
 
-export const fixPrompt = (result: ReviewResult): string =>
-  [
+export interface FixPromptOptions {
+  /** Characters of a gate's output kept in the prompt, from the end. Default 4000. */
+  readonly tailChars?: number
+  /** Name the gate log's path (a CLI coder can open it; an API coder cannot). Default false. */
+  readonly showPaths?: boolean
+}
+
+export const defaultGateTailChars = 4_000
+
+const evidenceNote =
+  "The gate output above is your only runtime evidence. If you are guessing without it, say `confidence: low` in your Findings."
+
+export const fixPrompt = (result: ReviewResult, options: FixPromptOptions = {}): string => {
+  const tailChars = options.tailChars ?? defaultGateTailChars
+  const lines = result.issues.map((issue) => {
+    const gate = isGateIssue(issue)
+    const description =
+      gate && issue.description.length > tailChars
+        ? `…${issue.description.slice(-tailChars)}`
+        : issue.description
+    const path =
+      gate && options.showPaths === true && issue.logPath !== undefined
+        ? ` (full output: ${issue.logPath})`
+        : ""
+    return `- [${issue.severity}] ${issue.title}: ${description}${path}`
+  })
+  const hasGate = result.issues.some(isGateIssue)
+  return [
     "Address these review findings, then stop:",
-    ...result.issues.map((issue) => `- [${issue.severity}] ${issue.title}: ${issue.description}`)
+    ...lines,
+    ...(hasGate ? ["", evidenceNote] : [])
   ].join("\n")
+}
+
+export interface GateTriageOptions {
+  /** The baseline for the code this change started from; `undefined` means no triage. */
+  readonly baseline: Effect.Effect<GateBaseline | undefined, FlowError>
+  /** Root prefixes stripped from gate output before comparing (the work dir, the app dir). */
+  readonly roots: ReadonlyArray<string>
+  /** Re-run the test gate alone to tell a flaky line from a new one; omit to never rerun. */
+  readonly rerunTest?: Effect.Effect<ReviewResult, FlowError>
+}
+
+const listed = (lines: ReadonlyArray<string>): string => lines.map((line) => `  ${line}`).join("\n")
+
+export interface OracleGateOptions {
+  /** The change under review as a unified diff (committed and uncommitted). */
+  readonly diff: Effect.Effect<string, FlowError>
+  readonly rules?: OracleRules
+  /** The plan entry says tests may change (`testsChange: true`); the guard then stays silent. */
+  readonly declared?: boolean
+  /** Tests passing on the base, from its baseline; omitted or `undefined` skips the count check. */
+  readonly baseCount?: Effect.Effect<number | undefined, FlowError>
+}
+
+/**
+ * The oracle guard (ADR 0027 decision 4) joined to a lint result: deleted
+ * test files, added skip or focus markers and a passed-count drop become
+ * Critical issues the fix round can undo. When a count is unknown on either
+ * side the comparison is skipped and said once.
+ */
+export const withOracle = Effect.fn("@llm4ts/flow/Review.withOracle")(function* (
+  lint: ReviewResult,
+  oracle: OracleGateOptions | undefined,
+  events: FlowEventsShape,
+  noted: Ref.Ref<boolean>
+): Effect.fn.Return<ReviewResult, FlowError> {
+  if (oracle === undefined || oracle.declared === true) {
+    return lint
+  }
+  const diff = yield* oracle.diff
+  const base = oracle.baseCount === undefined ? undefined : yield* oracle.baseCount
+  if ((base === undefined || lint.passed === undefined) && !(yield* Ref.get(noted))) {
+    yield* Ref.set(noted, true)
+    yield* events.publish(
+      Info.make({
+        message:
+          "oracle guard: no passed-test count on the base or the change (no summary line the guard reads), count comparison skipped"
+      })
+    )
+  }
+  const issues = checkOracle(
+    parseUnifiedDiff(diff),
+    { base, current: lint.passed },
+    oracle.rules ?? defaultOracleRules,
+    false
+  )
+  return issues.length === 0
+    ? lint
+    : ReviewResult.make({
+        issues: [...lint.issues, ...issues],
+        summary: [lint.summary, "oracle guard"].filter((part) => part.length > 0).join("; "),
+        ...(lint.passed === undefined ? {} : { passed: lint.passed })
+      })
+})
 
-export const mergeReviewResults = (results: ReadonlyArray<ReviewResult>): ReviewResult =>
-  ReviewResult.make({
+/**
+ * Charges a lint result only with what the change caused (ADR 0027).
+ * Inherited lines are published once per `reported` set as Info; with
+ * `rerunTest`, a new line that is green on one rerun of the test gate is
+ * flaky: published, not charged. Without options or a baseline the result
+ * is returned as is.
+ */
+export const applyTriage = Effect.fn("@llm4ts/flow/Review.applyTriage")(function* (
+  lint: ReviewResult,
+  triage: GateTriageOptions | undefined,
+  events: FlowEventsShape,
+  reported: Ref.Ref<ReadonlySet<string>>
+): Effect.fn.Return<ReviewResult, FlowError> {
+  if (triage === undefined || lint.isClean) {
+    return lint
+  }
+  const baseline = yield* triage.baseline
+  if (baseline === undefined) {
+    return lint
+  }
+  let triaged = triageGates(lint, baseline, triage.roots)
+  const seen = yield* Ref.get(reported)
+  const unseen = triaged.inherited.filter((line) => !seen.has(line))
+  if (unseen.length > 0) {
+    yield* Ref.update(reported, (set) => new Set([...set, ...unseen]))
+    yield* events.publish(
+      Info.make({
+        message: `${unseen.length} gate failure(s) inherited from the base, not charged to this change:\n${listed(unseen)}`
+      })
+    )
+  }
+  if (!triaged.blocking.isClean && triaged.newLines.length > 0 && triage.rerunTest !== undefined) {
+    const again = yield* triage.rerunTest
+    const stillRed = new Set(triageGates(again, baseline, triage.roots).newLines)
+    const flaky = triaged.newLines.filter((line) => !stillRed.has(line))
+    if (flaky.length > 0) {
+      yield* events.publish(
+        Info.make({
+          message: `${flaky.length} gate failure(s) flaky (red once, green on rerun), not charged:\n${listed(flaky)}`
+        })
+      )
+      triaged = triageGates(
+        again,
+        GateBaseline.make({ ...baseline, failingLines: [...baseline.failingLines, ...flaky] }),
+        triage.roots
+      )
+    }
+  }
+  return triaged.blocking
+})
+
+export const mergeReviewResults = (results: ReadonlyArray<ReviewResult>): ReviewResult => {
+  const counts = results.flatMap((result) => (result.passed === undefined ? [] : [result.passed]))
+  return ReviewResult.make({
     issues: results.flatMap((result) => result.issues),
     summary: results
       .map((result) => result.summary)
       .filter((summary) => summary.length > 0)
-      .join("; ")
+      .join("; "),
+    // Several gates may count tests (unit and e2e): the sum is what the change must keep.
+    ...(counts.length === 0 ? {} : { passed: counts.reduce((sum, value) => sum + value, 0) })
   })
+}
 
 const processProblem = (
   stdout: ReadonlyArray<string>,
@@ -265,57 +428,107 @@ const processProblem = (
   return detail.length === 0 ? `process exited with code ${exitCode}` : detail
 }
 
+export interface LintCommandOptions {
+  /** Kill the gate after this long; the issue is then `gateClass: "hang"`. Default: never. */
+  readonly timeout?: Duration.Duration
+  /** Write the gate's whole stdout and stderr here; the issue carries `logPath`. */
+  readonly log?: { readonly files: PlainFileStoreShape; readonly path: string }
+}
+
+const gateClassOf = (exitCode: number): "red" | "crash" => (exitCode >= 128 ? "crash" : "red")
+
 export const lintCommand = Effect.fn("@llm4ts/flow/Review.lintCommand")(function* (
   process: ProcessExecutorShape,
   events: FlowEventsShape,
   command: ReadonlyArray<string>,
-  workDir: string
+  workDir: string,
+  options: LintCommandOptions = {}
 ): Effect.fn.Return<ReviewResult, FlowError> {
   const executable = command[0]
   if (executable === undefined) {
     return ReviewResult.make({ issues: [], summary: "" })
   }
+  const label = command.join(" ")
   const started = yield* Clock.currentTimeMillis
+  const run = guarded(
+    Capabilities.Exec(executable),
+    `lint: ${label}`,
+    events,
+    process.run(command, workDir, {}).pipe(
+      Effect.mapError((cause) =>
+        ProcessError.make({
+          message: label,
+          detail: cause.message
+        })
+      )
+    )
+  )
+  // Interrupting `run` interrupts the child through the executor's scope;
+  // `undefined` here means the gate never exited (ADR 0027: a hang is a
+  // gate failure that says so, never a stuck run).
+  const bounded: Effect.Effect<ProcessResult | undefined, FlowError> =
+    options.timeout === undefined
+      ? run
+      : run.pipe(
+          Effect.timeoutOption(options.timeout),
+          Effect.map((option) => (option._tag === "Some" ? option.value : undefined))
+        )
   // A TOOL span (ADR 0026) and a Timed event: the command as configured and
   // its exit code, never its output.
   const result = yield* withKindSpan(
-    `gate ${command.join(" ")}`,
-    { kind: "TOOL", attributes: { [attr.gateCommand]: command.join(" ") } },
-    guarded(
-      Capabilities.Exec(executable),
-      `lint: ${command.join(" ")}`,
-      events,
-      process.run(command, workDir, {}).pipe(
-        Effect.mapError((cause) =>
-          ProcessError.make({
-            message: command.join(" "),
-            detail: cause.message
-          })
-        )
+    `gate ${label}`,
+    { kind: "TOOL", attributes: { [attr.gateCommand]: label } },
+    bounded.pipe(
+      Effect.tap((ran) =>
+        ran === undefined ? Effect.void : Effect.annotateCurrentSpan(attr.gateExit, ran.exitCode)
       )
-    ).pipe(Effect.tap((ran) => Effect.annotateCurrentSpan(attr.gateExit, ran.exitCode)))
+    )
   )
+  const failed = result === undefined || result.exitCode !== 0
   yield* events.publish(
     Timed.make({
       kind: "gate",
-      label: command.join(" "),
+      label,
       ms: (yield* Clock.currentTimeMillis) - started,
-      exitCode: result.exitCode,
-      ...(result.exitCode === 0 ? {} : { failed: true })
+      ...(result === undefined ? {} : { exitCode: result.exitCode }),
+      ...(failed ? { failed: true } : {})
     })
   )
-  if (result.exitCode === 0) {
-    return ReviewResult.make({ issues: [], summary: "lint passed" })
+  let logPath: string | undefined
+  if (options.log !== undefined) {
+    const output =
+      result === undefined ? "" : [...result.stdout, ...result.stderr].join("\n").trim()
+    yield* options.log.files.writeAtomic(options.log.path, output)
+    logPath = options.log.path
   }
+  const passed =
+    result === undefined
+      ? undefined
+      : passedCountIn([...result.stdout, ...result.stderr].join("\n"))
+  if (result !== undefined && result.exitCode === 0) {
+    return ReviewResult.make({
+      issues: [],
+      summary: "lint passed",
+      ...(passed === undefined ? {} : { passed })
+    })
+  }
+  const seconds =
+    options.timeout === undefined ? 0 : Math.round(Duration.toSeconds(options.timeout))
   return ReviewResult.make({
     issues: [
       ReviewIssue.make({
         severity: "Critical",
-        title: `lint failed: ${command.join(" ")}`,
-        description: processProblem(result.stdout, result.stderr, result.exitCode)
+        title: `lint failed: ${label}`,
+        description:
+          result === undefined
+            ? `gate killed: no exit after ${seconds} seconds (LLM4TS_GATE_TIMEOUT)`
+            : processProblem(result.stdout, result.stderr, result.exitCode),
+        gateClass: result === undefined ? "hang" : gateClassOf(result.exitCode),
+        ...(logPath === undefined ? {} : { logPath })
       })
     ],
-    summary: "lint failed"
+    summary: "lint failed",
+    ...(passed === undefined ? {} : { passed })
   })
 })
 
@@ -350,6 +563,12 @@ export interface ReviewAndFixOptions {
     result: ReviewResult,
     settled: boolean
   ) => Effect.Effect<void, FlowError>
+  /** Charge the lint gate only with failures the change caused (ADR 0027). */
+  readonly triage?: GateTriageOptions
+  /** How gate output reaches the coder in the fix prompt. */
+  readonly fix?: FixPromptOptions
+  /** Fail the round when the change deletes or skips tests (ADR 0027 decision 4). */
+  readonly oracle?: OracleGateOptions
 }
 
 export interface ReviewCacheLocation {
@@ -493,13 +712,21 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
     )
   )
   const format = options.format ?? Effect.void
+  const reported = yield* Ref.make<ReadonlySet<string>>(new Set())
+  const oracleNoted = yield* Ref.make(false)
 
   const reviewOnce = (
     round: number,
     previous: ReviewResult | undefined
   ): Effect.Effect<ReviewResult, FlowError> =>
     Effect.gen(function* () {
-      const lint = yield* options.lint ?? Effect.succeed(ReviewResult.make({ issues: [] }))
+      const lintRaw = yield* options.lint ?? Effect.succeed(ReviewResult.make({ issues: [] }))
+      const lint = yield* withOracle(
+        yield* applyTriage(lintRaw, options.triage, options.events, reported),
+        options.oracle,
+        options.events,
+        oracleNoted
+      )
       if (!lint.isClean) {
         return lint
       }
@@ -585,7 +812,7 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
       if (settled) {
         return result
       }
-      yield* options.coder.ask(fixPrompt(result))
+      yield* options.coder.ask(fixPrompt(result, options.fix))
       return yield* loop(round + 1, result)
     })
 

package/src/Roster.ts

@@ -63,7 +63,9 @@ export class ExecutorSpec extends Schema.Class<ExecutorSpec>("ExecutorSpec")({
   health: Schema.optionalKey(Schema.String),
   cooldown: Schema.optionalKey(Cooldown),
   /** In a repository roster: removes the user roster's entry with this id. */
-  disabled: Schema.optionalKey(Schema.Boolean)
+  disabled: Schema.optionalKey(Schema.Boolean),
+  /** The autonomy contract profile this executor's coder prompts carry (ADR 0027); default `full`. */
+  contract: Schema.optionalKey(Schema.Literals(["full", "minimal", "off"]))
 }) {}
 
 export class RosterDocument extends Schema.Class<RosterDocument>("RosterDocument")({

package/src/RosterSeats.ts

@@ -44,6 +44,8 @@ export interface RosterView {
   readonly executor: Effect.Effect<string | undefined>
   /** Every executor that held this context's coder, in order (handovers). */
   readonly history: Effect.Effect<ReadonlyArray<string>>
+  /** The autonomy contract profile an executor's roster entry asks for (ADR 0027), when it does. */
+  readonly contractOf?: (executor: string) => "full" | "minimal" | "off" | undefined
 }
 
 /** A roster failure seen through an `LlmServiceShape`, whose failures are `LlmError`s. */