@llm4ts/flow 2.7.2 → 2.9.0

package/src/FlowContext.ts

@@ -8,6 +8,15 @@ import type { FlowError } from "./FlowError.ts"
 import type { FlowEventsShape } from "./FlowEvents.ts"
 import type { GitToolShape } from "./GitTool.ts"
 import type { GitHubToolShape } from "./GitHubTool.ts"
+import type { RosterView } from "./RosterSeats.ts"
+
+/** How a rebound context wants its coder (ADR 0019); ignored without a roster. */
+export interface ContextOptions {
+  /** The executor this context held before (a resumed story), taken first while free. */
+  readonly prefer?: string
+  /** Who the context is for, in the roster's events ("story conto-overview"). */
+  readonly label?: string
+}
 
 export interface FlowContextShape {
   readonly reasoning: LlmServiceShape
@@ -32,7 +41,16 @@ export interface FlowContextShape {
    * events and cost tracking shared. Absent when the runner cannot rebind
    * (an embedded context built by hand).
    */
-  readonly contextFor?: (workDir: string) => Effect.Effect<FlowContextShape, FlowError, Scope.Scope>
+  readonly contextFor?: (
+    workDir: string,
+    options?: ContextOptions
+  ) => Effect.Effect<FlowContextShape, FlowError, Scope.Scope>
+  /**
+   * The executor roster behind the seats (ADR 0019), when the run has one:
+   * a seat per role, free and configured slots, and the executor holding
+   * this context's coder. Absent on a run with one executor per seat.
+   */
+  readonly roster?: RosterView
 }
 
 export class FlowContext extends Context.Service<FlowContext, FlowContextShape>()(

package/src/FlowError.ts

@@ -168,11 +168,70 @@ export class MissingDependency extends Schema.TaggedError<MissingDependency>()(
 export class MergeConflict extends Schema.TaggedError<MergeConflict>()("MergeConflict", {
   branch: Schema.String,
   into: Schema.String,
-  paths: Schema.Array(Schema.String)
+  paths: Schema.Array(Schema.String),
+  /** What git said when no path is in conflict — a merge refused before it started. */
+  detail: Schema.optionalKey(Schema.String)
 }) {
   get message(): string {
-    const where = this.paths.length === 0 ? "" : `: ${this.paths.join(", ")}`
-    return `merging '${this.branch}' into '${this.into}' conflicted${where}`
+    if (this.paths.length > 0) {
+      return `merging '${this.branch}' into '${this.into}' conflicted: ${this.paths.join(", ")}`
+    }
+    const why = this.detail === undefined || this.detail.length === 0 ? "" : `: ${this.detail}`
+    return `merging '${this.branch}' into '${this.into}' failed${why}`
+  }
+}
+
+/**
+ * The epic checkout holds changes no story may make there — a coder worked
+ * outside its worktree. Every later merge and epic gate would inherit them,
+ * so the executor stops launching stories until an operator cleans it.
+ */
+export class EpicCheckoutDirty extends Schema.TaggedError<EpicCheckoutDirty>()(
+  "EpicCheckoutDirty",
+  {
+    checkout: Schema.String,
+    paths: Schema.Array(Schema.String),
+    /** The story that had just finished when the change was found. */
+    story: Schema.optionalKey(Schema.String)
+  }
+) {
+  get message(): string {
+    const suspect = this.story === undefined ? "" : ` (found after story '${this.story}' finished)`
+    return [
+      `the epic checkout ${this.checkout} has uncommitted changes${suspect} — a coder worked outside its worktree:`,
+      ...this.paths.map((path) => `- ${path}`),
+      "Move each change into the owning story's worktree or discard it, then rerun."
+    ].join("\n")
+  }
+}
+
+/** A roster file that failed to load or validate — every violation, not the first (ADR 0019). */
+export class RosterInvalid extends Schema.TaggedError<RosterInvalid>()("RosterInvalid", {
+  path: Schema.optionalKey(Schema.String),
+  violations: Schema.Array(Schema.String)
+}) {
+  get message(): string {
+    const where = this.path === undefined ? "" : ` (${this.path})`
+    return `roster invalid${where}:\n${this.violations.map((violation) => `- ${violation}`).join("\n")}`
+  }
+}
+
+/** The start of every `RosterExhausted` message, so it is recognisable once wrapped. */
+export const rosterExhaustedPrefix = "roster exhausted: no executor can ever take the role"
+
+/**
+ * No executor of the roster can ever take `role` in this run: none has the
+ * role, or every one that has it is excluded for the run (ADR 0019). A
+ * roster waits for an executor that will come back; this is the case where
+ * none will.
+ */
+export class RosterExhausted extends Schema.TaggedError<RosterExhausted>()("RosterExhausted", {
+  role: Schema.String,
+  reasons: Schema.Array(Schema.String)
+}) {
+  get message(): string {
+    const why = this.reasons.length === 0 ? "" : `: ${this.reasons.join("; ")}`
+    return `${rosterExhaustedPrefix} '${this.role}'${why}`
   }
 }
 
@@ -240,6 +299,9 @@ export const FlowError = Schema.Union([
   PerimeterViolation,
   MissingDependency,
   MergeConflict,
+  EpicCheckoutDirty,
+  RosterExhausted,
+  RosterInvalid,
   StoryFailed,
   DecisionsInvalid,
   OpenPointsPending,

package/src/GitTool.ts

@@ -24,6 +24,11 @@ export interface GitToolShape {
   readonly initBare: Effect.Effect<void, FlowError>
   readonly config: (key: string, value: string) => Effect.Effect<void, FlowError>
   readonly status: Effect.Effect<string, FlowError>
+  /**
+   * Every path with uncommitted changes, untracked files listed one by one
+   * (not collapsed into their directory), minus the runner's `.llm4ts/`.
+   */
+  readonly uncommittedFiles: Effect.Effect<ReadonlyArray<string>, FlowError>
   readonly currentBranch: Effect.Effect<string, FlowError>
   readonly diff: Effect.Effect<string, FlowError>
   readonly diffAll: Effect.Effect<string, FlowError>
@@ -66,6 +71,16 @@ export interface GitToolShape {
   ) => Effect.Effect<void, FlowError>
   /** `force` also removes a worktree holding untracked or modified files. */
   readonly removeWorktree: (path: string, force?: boolean) => Effect.Effect<void, FlowError>
+  /** Moves an existing worktree to `to`, keeping its branch and uncommitted work. */
+  readonly moveWorktree: (from: string, to: string) => Effect.Effect<void, FlowError>
+  /**
+   * Puts `paths` back as they are on `source`: a path `source` has is checked
+   * out from it, a path it lacks is deleted (tracked or not). Uncommitted.
+   */
+  readonly restorePaths: (
+    source: string,
+    paths: ReadonlyArray<string>
+  ) => Effect.Effect<void, FlowError>
   readonly branchExists: (name: string) => Effect.Effect<boolean, FlowError>
   readonly deleteBranch: (name: string) => Effect.Effect<void, FlowError>
   /** Whether `commit` is reachable from `of` — a merged story branch is an ancestor of the epic head. */
@@ -73,11 +88,41 @@ export interface GitToolShape {
   /**
    * Merges `branch` into the checked-out branch with a merge commit. A
    * conflict fails typed with the conflicting paths and leaves the tree as it
-   * was (the merge is aborted), so the next merge can proceed.
+   * was (the merge is aborted), so the next merge can proceed. A merge git
+   * refuses before it starts (a dirty tree) fails typed with git's words.
+   * `preferIncoming` resolves conflicting hunks to `branch`'s side
+   * (`-X theirs`): the catch-up of a story branch with its epic, where the
+   * epic side is authoritative for every path the story does not own.
    */
-  readonly merge: (branch: string, message: string) => Effect.Effect<void, FlowError>
+  readonly merge: (
+    branch: string,
+    message: string,
+    options?: MergeOptions
+  ) => Effect.Effect<void, FlowError>
+}
+
+export interface MergeOptions {
+  readonly preferIncoming?: boolean
 }
 
+/**
+ * The paths `git status --short` reports, minus the runner's own state under
+ * `.llm4ts/`. A rename reports its destination.
+ */
+export const statusPaths = (status: string): ReadonlyArray<string> =>
+  status
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      // `status` trims its output, so the first line may have lost the
+      // leading blank of its two-letter code: match the code, not a column.
+      const path = (/^[ MADRCTU?!]{1,2}\s+(.+)$/.exec(line)?.[1] ?? "").trim()
+      const arrow = path.indexOf(" -> ")
+      const target = arrow < 0 ? path : path.slice(arrow + 4)
+      return target.replace(/^"|"$/g, "")
+    })
+    .filter((path) => path.length > 0 && !path.startsWith(".llm4ts/") && path !== ".llm4ts")
+
 const nonInteractiveEnvironment = Object.freeze({
   GIT_TERMINAL_PROMPT: "0",
   GIT_SSH_COMMAND: "ssh -o BatchMode=yes"
@@ -265,6 +310,10 @@ export const makeGitTool = (
     config: (key, value) =>
       write("git config", runOrFail(["config", key, value]).pipe(Effect.asVoid)),
     status: read("git status", runOrFail(["status", "--short"])),
+    uncommittedFiles: read(
+      "git uncommittedFiles",
+      runOrFail(["status", "--porcelain", "--untracked-files=all"]).pipe(Effect.map(statusPaths))
+    ),
     currentBranch: read("git currentBranch", runOrFail(["rev-parse", "--abbrev-ref", "HEAD"])),
     diff: read("git diff", runOrFail(["diff"])),
     diffAll: read(
@@ -328,6 +377,39 @@ export const makeGitTool = (
         "git worktree add -b",
         runOrFail(["worktree", "add", "-b", branch, path, startPoint]).pipe(Effect.asVoid)
       ),
+    moveWorktree: (from, to) =>
+      write(
+        "git worktree move",
+        Effect.gen(function* () {
+          // git creates a new worktree's parents but not a moved one's.
+          const parent = to.replace(/[\\/]+$/, "").replace(/[\\/][^\\/]*$/, "")
+          if (parent.length > 0 && parent !== to) {
+            yield* process
+              .run(["mkdir", "-p", parent], workDir, nonInteractiveEnvironment)
+              .pipe(
+                Effect.mapError((error) =>
+                  ProcessError.make({ message: `mkdir -p ${parent}`, detail: error.message })
+                )
+              )
+          }
+          yield* runOrFail(["worktree", "move", from, to])
+        })
+      ),
+    restorePaths: (source, paths) =>
+      write(
+        "git restorePaths",
+        Effect.gen(function* () {
+          for (const path of paths) {
+            const known = yield* run(["cat-file", "-e", `${source}:${path}`])
+            if (known.exitCode === 0) {
+              yield* runOrFail(["checkout", source, "--", path])
+            } else {
+              yield* runOrFail(["rm", "-r", "-f", "-q", "--ignore-unmatch", "--", path])
+              yield* runOrFail(["clean", "-f", "-d", "-q", "--", path])
+            }
+          }
+        })
+      ),
     removeWorktree: (path, force = false) =>
       write(
         "git worktree remove",
@@ -356,11 +438,18 @@ export const makeGitTool = (
                 )
         )
       ),
-    merge: (branch, message) =>
+    merge: (branch, message, options = {}) =>
       write(
         "git merge",
         Effect.gen(function* () {
-          const result = yield* run(["merge", "--no-ff", "-m", message, branch])
+          const result = yield* run([
+            "merge",
+            "--no-ff",
+            ...(options.preferIncoming === true ? ["-X", "theirs"] : []),
+            "-m",
+            message,
+            branch
+          ])
           if (result.exitCode === 0) {
             return
           }
@@ -374,7 +463,12 @@ export const makeGitTool = (
           // next story; a merge that failed before starting has nothing to
           // abort and git says so, which is not a second failure.
           yield* run(["merge", "--abort"])
-          return yield* MergeConflict.make({ branch, into, paths })
+          return yield* MergeConflict.make({
+            branch,
+            into,
+            paths,
+            ...(paths.length === 0 ? { detail: problem(result) } : {})
+          })
         })
       )
   }

package/src/Perimeter.ts

@@ -3,7 +3,16 @@
 // the prompt states the rule, this is what makes it true.
 import * as Effect from "effect/Effect"
 import { PerimeterViolation } from "./FlowError.ts"
-import { pathWithin, type Story } from "./StoryPlan.ts"
+import type { Task } from "./Plan.ts"
+import { ReviewIssue, ReviewResult } from "./Review.ts"
+import {
+  normalizePath,
+  ownerOf,
+  pathWithin,
+  pathsNamedIn,
+  type Story,
+  type StoryPlan
+} from "./StoryPlan.ts"
 
 export interface PerimeterCheck {
   /** Changed paths under a `sharedReadOnly` prefix — the worse class, reported first. */
@@ -47,3 +56,78 @@ export const enforcePerimeter = Effect.fn("@llm4ts/flow/Perimeter.enforce")(func
     })
   }
 })
+
+/**
+ * The perimeter as a gate result: a violation is one Critical issue whose
+ * text names every stray path, so the task review loop hands it back to the
+ * coder to revert before anything is committed.
+ */
+export const perimeterGate = (changedPaths: ReadonlyArray<string>, story: Story): ReviewResult => {
+  const check = checkPerimeter(changedPaths, story)
+  if (isWithinPerimeter(check)) {
+    return ReviewResult.make({ issues: [], summary: "perimeter: clean" })
+  }
+  const violation = PerimeterViolation.make({
+    story: story.id,
+    outside: check.outside,
+    sharedReadOnly: check.sharedReadOnly
+  })
+  return ReviewResult.make({
+    issues: [
+      ReviewIssue.make({
+        severity: "Critical",
+        title: "perimeter",
+        description: [
+          violation.message,
+          "Revert these paths (restore a changed file from the epic branch, delete a file you",
+          "created there) and keep the work inside your owned paths."
+        ].join("\n")
+      })
+    ],
+    summary: "perimeter: violated"
+  })
+}
+
+/** A planned task that names paths outside its story's perimeter. */
+export interface StrayTask {
+  readonly task: Task
+  readonly paths: ReadonlyArray<string>
+  /** Some of `paths` are owned by another story — the task is that story's work. */
+  readonly foreign: boolean
+}
+
+const fileLike = /\.[A-Za-z0-9]{1,5}$/
+
+const allowed = (story: Story, path: string): boolean =>
+  story.owned.some((prefix) => pathWithin(path, prefix)) ||
+  story.sharedReadOnly.some((prefix) => pathWithin(path, prefix)) ||
+  // A bare directory above an owned path ("inside src/features/conto") is a
+  // location, not a target.
+  (!fileLike.test(normalizePath(path)) && story.owned.some((prefix) => pathWithin(prefix, path)))
+
+/**
+ * The incomplete tasks of a story's plan that name paths the story may not
+ * touch. Checked before any coder turn is spent on them: a task such as
+ * "register the screen in src/App.tsx" is another story's job.
+ */
+export const strayTasks = (
+  plan: StoryPlan,
+  story: Story,
+  tasks: ReadonlyArray<Task>
+): ReadonlyArray<StrayTask> =>
+  tasks.flatMap((task) => {
+    if (task.completed) {
+      return []
+    }
+    const paths = pathsNamedIn(plan, `${task.title}\n${task.description}`).filter(
+      (path) => !allowed(story, path)
+    )
+    if (paths.length === 0) {
+      return []
+    }
+    const foreign = paths.some((path) => {
+      const owner = ownerOf(plan, path)
+      return owner !== undefined && owner.id !== story.id
+    })
+    return [{ task, paths, foreign }]
+  })