@llm4ts/flow 0.15.0 → 0.16.0

package/src/FlowError.ts

@@ -124,6 +124,74 @@ export class BudgetExceeded extends Schema.TaggedErrorClass<BudgetExceeded>()("B
   }
 }
 
+/** A story plan that failed deterministic validation — every violation, not the first (ADR 0013). */
+export class StoryPlanInvalid extends Schema.TaggedErrorClass<StoryPlanInvalid>()(
+  "StoryPlanInvalid",
+  {
+    violations: Schema.Array(Schema.String)
+  }
+) {
+  get message(): string {
+    return `story plan invalid:\n${this.violations.map((violation) => `- ${violation}`).join("\n")}`
+  }
+}
+
+/** A story branch changed paths outside the story's declared `owned` set. */
+export class PerimeterViolation extends Schema.TaggedErrorClass<PerimeterViolation>()(
+  "PerimeterViolation",
+  {
+    story: Schema.String,
+    outside: Schema.Array(Schema.String),
+    sharedReadOnly: Schema.Array(Schema.String)
+  }
+) {
+  get message(): string {
+    const lines = [`story '${this.story}' changed paths outside its perimeter:`]
+    for (const path of this.sharedReadOnly) {
+      lines.push(`- ${path} (shared read-only: revert it, or request it as a dedicated story)`)
+    }
+    for (const path of this.outside) {
+      lines.push(`- ${path} (not in the story's owned paths)`)
+    }
+    return lines.join("\n")
+  }
+}
+
+/** The coder ended a story with `BLOCKED_ON:` — unplanned work belongs to another story. */
+export class MissingDependency extends Schema.TaggedErrorClass<MissingDependency>()(
+  "MissingDependency",
+  {
+    story: Schema.String,
+    need: Schema.String
+  }
+) {
+  get message(): string {
+    return `story '${this.story}' is blocked on unplanned work: ${this.need}`
+  }
+}
+
+/** A story branch did not merge cleanly into the epic branch; the merge was aborted. */
+export class MergeConflict extends Schema.TaggedErrorClass<MergeConflict>()("MergeConflict", {
+  branch: Schema.String,
+  into: Schema.String,
+  paths: Schema.Array(Schema.String)
+}) {
+  get message(): string {
+    const where = this.paths.length === 0 ? "" : `: ${this.paths.join(", ")}`
+    return `merging '${this.branch}' into '${this.into}' conflicted${where}`
+  }
+}
+
+/** One story failed; carries the story id so a fail-fast run names its cause. */
+export class StoryFailed extends Schema.TaggedErrorClass<StoryFailed>()("StoryFailed", {
+  story: Schema.String,
+  reason: Schema.String
+}) {
+  get message(): string {
+    return `story '${this.story}' failed: ${this.reason}`
+  }
+}
+
 export const FlowError = Schema.Union([
   PersistenceError,
   PlanParseError,
@@ -136,6 +204,11 @@ export const FlowError = Schema.Union([
   FlowLlmError,
   FlowCapabilityDenied,
   ColumnNotFound,
-  BudgetExceeded
+  BudgetExceeded,
+  StoryPlanInvalid,
+  PerimeterViolation,
+  MissingDependency,
+  MergeConflict,
+  StoryFailed
 ])
 export type FlowError = typeof FlowError.Type

package/src/GitTool.ts

@@ -2,7 +2,7 @@ import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
 import { Capabilities, type Capability } from "@llm4ts/core/Capability"
 import type { ProcessExecutorShape, ProcessResult } from "@llm4ts/core/ProcessExecutor"
-import { ProcessError, type FlowError } from "./FlowError.ts"
+import { MergeConflict, ProcessError, type FlowError } from "./FlowError.ts"
 import type { FlowEventsShape } from "./FlowEvents.ts"
 import { guarded } from "./CapabilityGuard.ts"
 
@@ -56,8 +56,26 @@ export interface GitToolShape {
   readonly push: (remote: string, branch: string) => Effect.Effect<void, FlowError>
   readonly checkpoint: Effect.Effect<string, FlowError>
   readonly rollback: (checkpoint: string) => Effect.Effect<void, FlowError>
+  /** Checks an EXISTING branch out into a new worktree at `path`. */
   readonly addWorktree: (path: string, branch: string) => Effect.Effect<void, FlowError>
-  readonly removeWorktree: (path: string) => Effect.Effect<void, FlowError>
+  /** Creates `branch` at `startPoint` and checks it out into a new worktree at `path`. */
+  readonly addWorktreeNewBranch: (
+    path: string,
+    branch: string,
+    startPoint: string
+  ) => Effect.Effect<void, FlowError>
+  /** `force` also removes a worktree holding untracked or modified files. */
+  readonly removeWorktree: (path: string, force?: boolean) => 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. */
+  readonly isAncestor: (commit: string, of: string) => Effect.Effect<boolean, FlowError>
+  /**
+   * 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.
+   */
+  readonly merge: (branch: string, message: string) => Effect.Effect<void, FlowError>
 }
 
 const nonInteractiveEnvironment = Object.freeze({
@@ -287,7 +305,59 @@ export const makeGitTool = (
       write("git rollback", runOrFail(["reset", "--hard", checkpoint]).pipe(Effect.asVoid)),
     addWorktree: (path, branch) =>
       write("git worktree add", runOrFail(["worktree", "add", path, branch]).pipe(Effect.asVoid)),
-    removeWorktree: (path) =>
-      write("git worktree remove", runOrFail(["worktree", "remove", path]).pipe(Effect.asVoid))
+    addWorktreeNewBranch: (path, branch, startPoint) =>
+      write(
+        "git worktree add -b",
+        runOrFail(["worktree", "add", "-b", branch, path, startPoint]).pipe(Effect.asVoid)
+      ),
+    removeWorktree: (path, force = false) =>
+      write(
+        "git worktree remove",
+        runOrFail(["worktree", "remove", ...(force ? ["--force"] : []), path]).pipe(Effect.asVoid)
+      ),
+    branchExists: (name) =>
+      read(
+        "git branchExists",
+        Effect.map(verifiedRef(`refs/heads/${name}`), (found) => found !== undefined)
+      ),
+    deleteBranch: (name) =>
+      write("git branch -D", runOrFail(["branch", "-D", name]).pipe(Effect.asVoid)),
+    isAncestor: (commit, of) =>
+      read(
+        "git merge-base --is-ancestor",
+        Effect.flatMap(run(["merge-base", "--is-ancestor", commit, of]), (result) =>
+          result.exitCode === 0
+            ? Effect.succeed(true)
+            : result.exitCode === 1
+              ? Effect.succeed(false)
+              : Effect.fail(
+                  ProcessError.make({
+                    message: `git merge-base --is-ancestor ${commit} ${of}`,
+                    detail: problem(result)
+                  })
+                )
+        )
+      ),
+    merge: (branch, message) =>
+      write(
+        "git merge",
+        Effect.gen(function* () {
+          const result = yield* run(["merge", "--no-ff", "-m", message, branch])
+          if (result.exitCode === 0) {
+            return
+          }
+          const into = yield* runOrFail(["rev-parse", "--abbrev-ref", "HEAD"])
+          const unmerged = yield* run(["diff", "--name-only", "--diff-filter=U"])
+          const paths = text(unmerged.stdout)
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+          // Abort regardless of the outcome so the epic tree is clean for the
+          // 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 })
+        })
+      )
   }
 }

package/src/Perimeter.ts

@@ -0,0 +1,49 @@
+// The story perimeter check (ADR 0013): a story branch may only change what
+// the story owns. Enforced after the fact on the branch's changed files —
+// 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"
+
+export interface PerimeterCheck {
+  /** Changed paths under a `sharedReadOnly` prefix — the worse class, reported first. */
+  readonly sharedReadOnly: ReadonlyArray<string>
+  /** Changed paths under neither `owned` nor `sharedReadOnly`. */
+  readonly outside: ReadonlyArray<string>
+}
+
+export const checkPerimeter = (
+  changedPaths: ReadonlyArray<string>,
+  story: Story
+): PerimeterCheck => {
+  const sharedReadOnly: Array<string> = []
+  const outside: Array<string> = []
+  for (const path of changedPaths) {
+    if (story.owned.some((prefix) => pathWithin(path, prefix))) {
+      continue
+    }
+    if (story.sharedReadOnly.some((prefix) => pathWithin(path, prefix))) {
+      sharedReadOnly.push(path)
+    } else {
+      outside.push(path)
+    }
+  }
+  return { sharedReadOnly, outside }
+}
+
+export const isWithinPerimeter = (check: PerimeterCheck): boolean =>
+  check.sharedReadOnly.length === 0 && check.outside.length === 0
+
+export const enforcePerimeter = Effect.fn("@llm4ts/flow/Perimeter.enforce")(function* (
+  changedPaths: ReadonlyArray<string>,
+  story: Story
+): Effect.fn.Return<void, PerimeterViolation> {
+  const check = checkPerimeter(changedPaths, story)
+  if (!isWithinPerimeter(check)) {
+    return yield* PerimeterViolation.make({
+      story: story.id,
+      outside: check.outside,
+      sharedReadOnly: check.sharedReadOnly
+    })
+  }
+})