@llm4ts/flow 2.30.0 → 2.31.0

package/src/Stories.ts

@@ -20,6 +20,16 @@ import type { LlmError } from "@llm4ts/core/Errors"
 import { BoardItem, type BoardSyncShape } from "./BoardSync.ts"
 import { makeChat } from "./Chat.ts"
 import { implementPlanFlow } from "./Flow.ts"
+import {
+  GateBaseline,
+  baselineKey,
+  ensureBaseline as ensureStoredBaseline,
+  failingLinesOf,
+  storyGateLogDir,
+  triageGates,
+  writeBaseline,
+  type GateLogDir
+} from "./Gates.ts"
 import type { ContextOptions, FlowContextShape } from "./FlowContext.ts"
 import {
   describeFlowError,
@@ -31,6 +41,7 @@ import {
   type FlowError
 } from "./FlowError.ts"
 import {
+  EvidenceChecked,
   Info,
   JudgedDimension,
   StoryJudged,
@@ -57,8 +68,23 @@ import {
 import { Plan, Task } from "./Plan.ts"
 import { stage } from "./PlanExecution.ts"
 import { planFrom } from "./Planner.ts"
-import { ReviewIssue, ReviewResult } from "./Review.ts"
+import {
+  ReviewIssue,
+  ReviewResult,
+  applyTriage,
+  type FixPromptOptions,
+  type GateTriageOptions
+} from "./Review.ts"
+import {
+  type OracleRules,
+  checkOracle,
+  defaultOracleRules,
+  parseUnifiedDiff
+} from "./OracleGuard.ts"
 import { cachedValue, fingerprintOf } from "./ReviewCache.ts"
+import { withContract, type ContractProfile } from "./AutonomyContract.ts"
+import { fabricatedStatusIssues, unverifiedClaims } from "./Evidence.ts"
+import type { Trailer } from "./CarriedNotes.ts"
 import type { Reviewer } from "./Reviewer.ts"
 import {
   dependentsOf,
@@ -133,7 +159,9 @@ export class StoryOutcome extends Schema.Class<StoryOutcome>("StoryOutcome")({
   executor: Schema.optionalKey(Schema.String),
   /** ESTIMATES, never measurements (ADR 0012). */
   estimatedTokens: Schema.optionalKey(Schema.Int),
-  estimatedCostUsd: Schema.optionalKey(Schema.Number)
+  estimatedCostUsd: Schema.optionalKey(Schema.Number),
+  /** Gate failures already red on the story's base, not charged to it (ADR 0027). */
+  inherited: Schema.optionalKey(Schema.Array(Schema.String))
 }) {}
 
 export class EpicReport extends Schema.Class<EpicReport>("EpicReport")({
@@ -184,6 +212,24 @@ export const renderEpicReport = (report: EpicReport): string => {
   if (cost.length > 0) {
     lines.push(`- Estimated cost: ${money(cost.reduce((sum, value) => sum + value, 0))}`)
   }
+  const inherited = new Map<string, Array<string>>()
+  for (const story of report.stories) {
+    for (const line of story.inherited ?? []) {
+      inherited.set(line, [...(inherited.get(line) ?? []), story.id])
+    }
+  }
+  if (inherited.size > 0) {
+    lines.push(
+      "",
+      "## Inherited gate failures",
+      "",
+      "Red on the base before the story ran; not charged to it. A cleanup story may own them.",
+      ""
+    )
+    for (const [line, stories] of inherited) {
+      lines.push(`- ${line} (stories: ${stories.join(", ")})`)
+    }
+  }
   const coded = report.stories.filter((story) => story.executor !== undefined)
   if (coded.length > 0) {
     // A story is counted for the executor that finished it; a handover chain
@@ -591,9 +637,43 @@ export interface StoriesOptions {
    * gate's timing names its story; a gate may ignore it.
    */
   readonly gates: (
+    workDir: string,
+    events?: FlowEventsShape,
+    /** Where to write one log per gate command for this run; absent writes none. */
+    log?: GateLogDir
+  ) => Effect.Effect<ReviewResult, FlowError>
+  /**
+   * The gate commands as configured and the application directory (ADR 0027):
+   * with them, the gates' result on each epic head is recorded as a baseline
+   * and a story is charged only with the failing lines it added. Without
+   * them every red line blocks, as before.
+   */
+  readonly gateCommands?: ReadonlyArray<ReadonlyArray<string>>
+  readonly appDir?: string
+  /** The test gate alone, for one rerun that tells a flaky line from a new one; omit to never rerun. */
+  readonly testGate?: (
     workDir: string,
     events?: FlowEventsShape
   ) => Effect.Effect<ReviewResult, FlowError>
+  /** How gate output reaches the coder in the fix prompt. */
+  readonly fix?: FixPromptOptions
+  /** Test-file and marker patterns for the oracle guard; default rules when absent (ADR 0027). */
+  readonly oracleRules?: OracleRules
+  /**
+   * The autonomy contract profile for the coder's system prompt (ADR 0027
+   * decision 5). Default: the roster executor's `contract`, else `full`.
+   */
+  readonly contract?: ContractProfile
+  /**
+   * The arguments of every tool call the story's coder made since `since`
+   * (epoch ms), from the run's transcript; `undefined` when the run keeps
+   * none for it. With it, a task's `verified:` claims are checked
+   * (ADR 0027 decision 6).
+   */
+  readonly toolCalls?: (
+    story: Story,
+    since: number
+  ) => Effect.Effect<ReadonlyArray<string> | undefined, FlowError>
   /** Story-level judge over the branch's diff against the epic branch; omit to skip. */
   readonly judge?: (
     story: Story,
@@ -717,6 +797,49 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     join(options.stateDir, `stories/${story.id}.findings.md`)
   /** What the coder's tasks learned, carried into the next task of the same story. */
   const notesPath = (story: Story): string => join(options.stateDir, `stories/${story.id}.notes.md`)
+  // Gates with a memory (ADR 0027): baselines are keyed by the commit a
+  // change started from, the app dir and the commands; without commands
+  // nothing is recorded and every red line blocks, as before.
+  const appDir = options.appDir ?? "."
+  const gateCommands = options.gateCommands
+  const rootsOf = (workDir: string): ReadonlyArray<string> => [join(workDir, appDir), workDir]
+  const keyFor = (commit: string): string =>
+    baselineKey({ baseCommit: commit, appDir, commands: gateCommands ?? [] })
+  const baselineOf = (
+    commit: string,
+    result: ReviewResult,
+    workDir: string
+  ): Effect.Effect<GateBaseline> =>
+    Effect.map(Clock.currentTimeMillis, (recordedAt) =>
+      GateBaseline.make({
+        baseCommit: commit,
+        appDir,
+        commands: (gateCommands ?? []).map((command) => command.join(" ")),
+        failingLines: failingLinesOf(result, rootsOf(workDir)),
+        ...(result.passed === undefined ? {} : { passedCount: result.passed }),
+        recordedAt
+      })
+    )
+  /** The baseline for `commit`, recording one from `run` when none is stored. */
+  const ensureBaseline = (
+    commit: string,
+    run: Effect.Effect<ReviewResult, FlowError>,
+    workDir: string
+  ): Effect.Effect<GateBaseline | undefined, FlowError> =>
+    gateCommands === undefined
+      ? Effect.succeed(undefined)
+      : ensureStoredBaseline({
+          files,
+          stateDir: options.stateDir,
+          commit,
+          appDir,
+          commands: gateCommands,
+          run,
+          roots: rootsOf(workDir),
+          now: Clock.currentTimeMillis
+        })
+  /** What each story inherited, for its outcome. */
+  const inheritedByStory = new Map<string, ReadonlyArray<string>>()
   const findingLines = (result: ReviewResult): ReadonlyArray<string> =>
     result.issues.map((issue) => {
       const where =
@@ -774,6 +897,11 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
 
   yield* epicCheckoutClean()
   yield* stage(events, "epic branch", context.git.checkoutOrCreate(epicBranch))
+  if (gateCommands !== undefined) {
+    // The gates as the epic head stands: what every story may inherit.
+    const epicHead = yield* context.git.checkpoint
+    yield* ensureBaseline(epicHead, options.gates(context.workDir, events), context.workDir)
+  }
 
   const waves = topologicalWaves(plan)
   const waveOf = (id: string): string | undefined => {
@@ -814,12 +942,29 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
               Timed.make({ kind: "merge", label: "merge", ms, ...(failed ? { failed } : {}) })
           )
           const gate = yield* options.gates(context.workDir, lane)
-          if (!gate.isClean) {
+          // Charged only with what the merge added: the head before it had
+          // a baseline (run start or the previous merge).
+          const before = yield* ensureBaseline(
+            checkpoint,
+            Effect.succeed(ReviewResult.make({ issues: [] })),
+            context.workDir
+          )
+          const verdict = triageGates(gate, before, rootsOf(context.workDir))
+          if (!verdict.blocking.isClean) {
             // Never leave a red epic head for the next story to inherit.
             yield* context.git.rollback(checkpoint)
             return yield* failed(
               story,
-              `epic gates failed after merging; merge undone:\n${issueLines(gate)}`
+              `epic gates failed after merging; merge undone:\n${issueLines(verdict.blocking)}`
+            )
+          }
+          if (gateCommands !== undefined) {
+            const mergedHead = yield* context.git.checkpoint
+            yield* writeBaseline(
+              files,
+              options.stateDir,
+              keyFor(mergedHead),
+              yield* baselineOf(mergedHead, gate, context.workDir)
             )
           }
           yield* laneOf(story).publish(
@@ -972,13 +1117,69 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     const git = storyContext.git
     const watchedSeats: StorySeats = { ...seats, context: storyContext }
     const extra = options.system === undefined ? undefined : yield* options.system(story)
-    const system = [
-      perimeterRules(story, { plan, worktree: state.worktree, epicCheckout: context.workDir }),
-      gateRules,
-      extra
-    ]
-      .filter((part): part is string => part !== undefined && part.trim().length > 0)
-      .join("\n\n")
+    const contractProfile: ContractProfile =
+      options.contract ??
+      (coderExecutor === undefined ? undefined : roster?.contractOf?.(coderExecutor)) ??
+      "full"
+    const system = withContract(
+      [
+        perimeterRules(story, { plan, worktree: state.worktree, epicCheckout: context.workDir }),
+        gateRules,
+        extra
+      ]
+        .filter((part): part is string => part !== undefined && part.trim().length > 0)
+        .join("\n\n"),
+      contractProfile
+    )
+    /** What the coder claimed to have run and did not, task by task, for the judge. */
+    const evidenceNotes: Array<string> = []
+    const checkEvidence = (
+      task: Task,
+      trailer: Trailer,
+      startedAt: number
+    ): Effect.Effect<void, FlowError> =>
+      Effect.gen(function* () {
+        const calls =
+          options.toolCalls === undefined ? undefined : yield* options.toolCalls(story, startedAt)
+        const confidence =
+          trailer.confidence === undefined ? {} : { confidence: trailer.confidence }
+        if (calls === undefined) {
+          yield* laneOf(story).publish(
+            EvidenceChecked.make({
+              task: task.title,
+              claimed: trailer.verified.length,
+              unverified: 0,
+              unchecked: true,
+              lane: story.id,
+              ...confidence
+            })
+          )
+          return
+        }
+        const unverified = unverifiedClaims(trailer.verified, calls)
+        yield* laneOf(story).publish(
+          EvidenceChecked.make({
+            task: task.title,
+            claimed: trailer.verified.length,
+            unverified: unverified.length,
+            lane: story.id,
+            ...confidence
+          })
+        )
+        if (unverified.length > 0) {
+          evidenceNotes.push(
+            `task "${task.title}": claimed ${unverified.map((command) => `\`${command}\``).join(", ")} — no tool call ran it`
+          )
+          yield* appendFindings(
+            story,
+            `evidence "${task.title}" — ${unverified.length} claimed command(s) never ran`,
+            ReviewResult.make({ issues: fabricatedStatusIssues(unverified), summary: "" })
+          )
+        }
+        if (trailer.confidence === "low") {
+          evidenceNotes.push(`task "${task.title}": the coder said confidence: low`)
+        }
+      })
     const prompt = storyPrompt(story)
 
     // Catch up before setup: the epic may have changed the manifest too.
@@ -1024,11 +1225,65 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
 
     // The target's gates plus the perimeter: a stray path is a gate failure
     // the task review loop hands back to the coder before anything commits.
+    // The epic head this worktree started from: what the story may inherit.
+    const storyBase = yield* git.checkpoint
+    const storyBaseline = ensureBaseline(
+      storyBase,
+      options.gates(state.worktree, laneOf(story)),
+      state.worktree
+    )
+    // The oracle guard over the story's whole change against the epic:
+    // committed on the branch and uncommitted in the worktree (ADR 0027).
+    const oracleGate = (target: ReviewResult): Effect.Effect<ReviewResult, FlowError> =>
+      story.testsChange
+        ? Effect.succeed(ReviewResult.make({ issues: [] }))
+        : Effect.gen(function* () {
+            const committed = yield* git.diffVsBase(epicBranch)
+            const uncommitted = yield* git.diffAll
+            const base =
+              gateCommands === undefined ? undefined : (yield* storyBaseline)?.passedCount
+            const issues = checkOracle(
+              parseUnifiedDiff(`${committed}\n${uncommitted}`),
+              { base, current: target.passed },
+              options.oracleRules ?? defaultOracleRules,
+              false
+            )
+            return ReviewResult.make({ issues, summary: issues.length === 0 ? "" : "oracle guard" })
+          })
     const gates: Effect.Effect<ReviewResult, FlowError> = Effect.gen(function* () {
-      const target = yield* options.gates(state.worktree, laneOf(story))
+      const target = yield* options.gates(state.worktree, laneOf(story), {
+        files,
+        dir: storyGateLogDir(options.stateDir, story.id)
+      })
       const changed = yield* perimeterNow(story, git)
-      return combined(target, perimeterGate([...changed.sharedReadOnly, ...changed.outside], story))
+      return combined(
+        combined(target, perimeterGate([...changed.sharedReadOnly, ...changed.outside], story)),
+        yield* oracleGate(target)
+      )
     })
+    const triage: GateTriageOptions = {
+      baseline: storyBaseline,
+      roots: rootsOf(state.worktree),
+      ...(options.testGate === undefined
+        ? {}
+        : { rerunTest: options.testGate(state.worktree, laneOf(story)) })
+    }
+    if (gateCommands !== undefined) {
+      const inherited = (yield* storyBaseline)?.failingLines ?? []
+      if (inherited.length > 0) {
+        inheritedByStory.set(story.id, inherited)
+        yield* appendFindings(
+          story,
+          "gate failures inherited from the base (not charged to this story)",
+          ReviewResult.make({
+            issues: inherited.map((line) =>
+              ReviewIssue.make({ severity: "Info", title: line, description: "", origin: "base" })
+            ),
+            summary: ""
+          })
+        )
+      }
+    }
 
     const coderTurn = (text: string): Effect.Effect<string, FlowError> =>
       Effect.flatMap(makeChat(storyContext.coder, { system, events, agent: "coder" }), (chat) =>
@@ -1037,7 +1292,8 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
 
     const commitGreen = (message: string, why: string): Effect.Effect<void, FlowError> =>
       Effect.gen(function* () {
-        const regated = yield* gates
+        const reported = yield* Ref.make<ReadonlySet<string>>(new Set())
+        const regated = yield* applyTriage(yield* gates, triage, laneOf(story), reported)
         if (!regated.isClean) {
           return yield* failed(story, `gates broke ${why}:\n${issueLines(regated)}`)
         }
@@ -1171,6 +1427,8 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       },
       checkoutBranch: false,
       lint: gates,
+      triage,
+      ...(options.fix === undefined ? {} : { fix: options.fix }),
       // A story's final state is judged and gated downstream (judge round,
       // perimeter check, epic gates), so a task the coder finds already
       // satisfied — without saying the exact sentinel — must not sink the
@@ -1188,6 +1446,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
           }${settled ? "" : ", fixing"}`,
           result
         ),
+      onTaskReply: (task, _reply, trailer, startedAt) => checkEvidence(task, trailer, startedAt),
       ...(options.reviewers === undefined ? {} : { reviewers: options.reviewers }),
       ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds })
     })
@@ -1239,7 +1498,19 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         // be on the epic (an earlier story or run put it there). Judge that
         // code instead: the owned paths against the empty tree.
         const empty = diff.trim().length === 0
-        const subject = empty ? yield* git.diffVsBaseScoped(emptyTree, story.owned, false) : diff
+        const judgedCode = empty ? yield* git.diffVsBaseScoped(emptyTree, story.owned, false) : diff
+        // What the coder claimed and could not show travels with the subject
+        // (ADR 0027 decision 6): the judge weighs the code knowing the
+        // story's own account of its testing is not evidence.
+        const subject =
+          evidenceNotes.length === 0
+            ? judgedCode
+            : [
+                "Evidence notes from the run (not part of the diff):",
+                ...evidenceNotes.map((note) => `- ${note}`),
+                "",
+                judgedCode
+              ].join("\n")
         // The verdict is kept beside a fingerprint of what was judged: a
         // rerun that finds the same diff gets the same answer without a
         // model call, and the last verdict is on disk to read. Only the
@@ -1406,6 +1677,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         ...(last === undefined ? {} : { executor: last })
       })
     )
+    const inherited = inheritedByStory.get(story.id)
     return StoryOutcome.make({
       id: story.id,
       title: story.title,
@@ -1414,7 +1686,8 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       ...(result.judge === undefined ? {} : { judge: result.judge }),
       ...(result.executor === undefined ? {} : { executor: result.executor }),
       ...(result.totals === undefined ? {} : { estimatedTokens: result.totals.total }),
-      ...(result.totals?.costUsd === undefined ? {} : { estimatedCostUsd: result.totals.costUsd })
+      ...(result.totals?.costUsd === undefined ? {} : { estimatedCostUsd: result.totals.costUsd }),
+      ...(inherited === undefined ? {} : { inherited })
     })
   })
 

package/src/StoryPlan.ts

@@ -44,6 +44,15 @@ export class Story extends Schema.Class<Story>("Story")({
   acceptance: Schema.Array(Schema.String).pipe(
     Schema.withConstructorDefault(Effect.succeed([])),
     Schema.withDecodingDefaultKey(Effect.succeed([]))
+  ),
+  /**
+   * The story may delete, skip or rewrite tests (ADR 0027): the oracle guard
+   * stays silent for it. Absent or false, a deleted test file, an added skip
+   * marker or a passed-count drop is a gate failure.
+   */
+  testsChange: Schema.Boolean.pipe(
+    Schema.withConstructorDefault(Effect.succeed(false)),
+    Schema.withDecodingDefaultKey(Effect.succeed(false))
   )
 }) {}
 
@@ -366,7 +375,8 @@ export const storyHash = (story: Story): string =>
       ...(story.readFirst.length === 0
         ? {}
         : { readFirst: [...story.readFirst].map(normalizePath) }),
-      ...(story.acceptance.length === 0 ? {} : { acceptance: [...story.acceptance] })
+      ...(story.acceptance.length === 0 ? {} : { acceptance: [...story.acceptance] }),
+      ...(story.testsChange ? { testsChange: true } : {})
     })
   )