@llm4ts/flow 1.0.0 → 2.1.0

package/src/BoardSync.ts

@@ -7,7 +7,7 @@ import { FlowAborted, type FlowError } from "./FlowError.ts"
 import { loadVersioned, saveVersioned, type PlainFileStoreShape } from "./Persistence.ts"
 
 // The progress board of the conversion scenario: a port with the work-item
-// lifecycle (plan → start → complete/fail/skip) and two adapters — a local
+// lifecycle (plan → start → complete/fail/wait/skip) and two adapters — a local
 // file board (the default, fully offline: board.json + rendered board.md)
 // and an Azure DevOps adapter (the stretch goal) mapping the same lifecycle
 // onto work items. Flows depend only on the port; which board the client
@@ -15,7 +15,14 @@ import { loadVersioned, saveVersioned, type PlainFileStoreShape } from "./Persis
 
 export const BoardVersion = 1
 
-export const BoardStatus = Schema.Literals(["planned", "active", "done", "failed", "skipped"])
+export const BoardStatus = Schema.Literals([
+  "planned",
+  "active",
+  "waiting",
+  "done",
+  "failed",
+  "skipped"
+])
 export type BoardStatus = typeof BoardStatus.Type
 
 export class BoardItem extends Schema.Class<BoardItem>("BoardItem")({
@@ -25,7 +32,7 @@ export class BoardItem extends Schema.Class<BoardItem>("BoardItem")({
   status: BoardStatus,
   branch: Schema.optionalKey(Schema.String),
   reportPath: Schema.optionalKey(Schema.String),
-  /** Free-form note: a failure reason, a skip rationale, a triage disposition. */
+  /** Free-form note: a failure reason, what an item waits for, a triage disposition. */
   detail: Schema.optionalKey(Schema.String),
   /** ESTIMATES, never measurements — see EstimatedUsage (ADR 0012). */
   estimatedTokens: Schema.optionalKey(Schema.Int),
@@ -51,13 +58,20 @@ export interface BoardSyncShape {
   readonly start: (id: string) => Effect.Effect<void, FlowError>
   readonly complete: (id: string, result: BoardItemResult) => Effect.Effect<void, FlowError>
   readonly fail: (id: string, reason: string) => Effect.Effect<void, FlowError>
+  /** Final: the item is deliberately left out (a page triaged as dead, say). */
   readonly skip: (id: string, reason: string) => Effect.Effect<void, FlowError>
+  /**
+   * On hold: the item waits for something that failed (a predecessor story)
+   * and runs once that is fixed — unlike `skip`, it is not final.
+   */
+  readonly wait: (id: string, reason: string) => Effect.Effect<void, FlowError>
   readonly snapshot: Effect.Effect<Board, FlowError>
 }
 
 const sectionOrder: ReadonlyArray<readonly [BoardStatus, string]> = [
   ["active", "Active"],
   ["planned", "Planned"],
+  ["waiting", "Waiting"],
   ["done", "Done"],
   ["failed", "Failed"],
   ["skipped", "Skipped"]
@@ -193,6 +207,8 @@ export const makeLocalBoardSync = (
       update(id, (item) => BoardItem.make({ ...item, status: "failed", detail: reason })),
     skip: (id, reason) =>
       update(id, (item) => BoardItem.make({ ...item, status: "skipped", detail: reason })),
+    wait: (id, reason) =>
+      update(id, (item) => BoardItem.make({ ...item, status: "waiting", detail: reason })),
     snapshot: load
   }
 }
@@ -213,6 +229,7 @@ export const composeBoardSync = (boards: ReadonlyArray<BoardSyncShape>): BoardSy
     complete: (id, result) => each((board) => board.complete(id, result)),
     fail: (id, reason) => each((board) => board.fail(id, reason)),
     skip: (id, reason) => each((board) => board.skip(id, reason)),
+    wait: (id, reason) => each((board) => board.wait(id, reason)),
     snapshot:
       first === undefined
         ? Effect.succeed(Board.make({ title: "empty", items: [] }))
@@ -242,8 +259,9 @@ const markerQuery = (tag: string, id: string): string =>
  * The stretch adapter (ADR 0012): the same lifecycle mapped onto Azure DevOps
  * work items through the az-CLI AzureDevOpsTool (ADR 0011). Idempotent by
  * title marker — `[<id>]` plus the board tag — so a re-run finds its items
- * instead of duplicating them. Failure and skip are tags plus a comment,
- * never invented states.
+ * instead of duplicating them. Failure, waiting and skip are tags plus a
+ * comment, never invented states; a waiting tag is lifted when the item is
+ * started again.
  */
 export const makeAdoBoardSync = Effect.fn("@llm4ts/flow/BoardSync.makeAdo")(function* (
   ado: AzureDevOpsToolShape,
@@ -334,6 +352,12 @@ export const makeAdoBoardSync = Effect.fn("@llm4ts/flow/BoardSync.makeAdo")(func
         yield* ado.editTags(workItem, [`${tag}-skipped`], [])
         yield* ado.writeComment(workItem, `SKIPPED: ${reason}`)
       }),
+    wait: (id, reason) =>
+      Effect.gen(function* () {
+        const workItem = yield* lookup(id)
+        yield* ado.editTags(workItem, [`${tag}-waiting`], [])
+        yield* ado.writeComment(workItem, `WAITING: ${reason}`)
+      }),
     snapshot: Effect.gen(function* () {
       const found = yield* ado.wiqlIds(
         `SELECT [System.Id] FROM WorkItems WHERE [System.Tags] CONTAINS ${quoteWiql(tag)}`
@@ -344,6 +368,9 @@ export const makeAdoBoardSync = Effect.fn("@llm4ts/flow/BoardSync.makeAdo")(func
         const match = /^\[([^\]]+)\] (.*)$/.exec(workItem.title)
         const failed = workItem.tags.includes(`${tag}-failed`)
         const skipped = workItem.tags.includes(`${tag}-skipped`)
+        const waiting = workItem.tags.includes(`${tag}-waiting`)
+        // A live state outranks a waiting tag: an item started again after
+        // its predecessor was fixed is active, whatever tag it still carries.
         const status: BoardStatus = failed
           ? "failed"
           : skipped
@@ -352,7 +379,9 @@ export const makeAdoBoardSync = Effect.fn("@llm4ts/flow/BoardSync.makeAdo")(func
               ? "done"
               : workItem.state === states.active
                 ? "active"
-                : "planned"
+                : waiting
+                  ? "waiting"
+                  : "planned"
         items.push(
           BoardItem.make({
             id: match?.[1] ?? String(workItemId),

package/src/Context.ts

@@ -44,14 +44,11 @@ export const cap = (text: string, limit: number): CappedText => {
 
 export const defaultContextBudget = 400_000
 
-/**
- * The default character budget: `LLM4TS_CONTEXT_BUDGET`, else the deprecated
- * `LLM4TS_JUDGE_SOURCES_LIMIT`, else 400_000.
- */
+/** The default character budget: `LLM4TS_CONTEXT_BUDGET`, else 400_000. */
 export const budget = (
   environment: Readonly<Record<string, string | undefined>> = process.env
 ): number => {
-  const raw = environment["LLM4TS_CONTEXT_BUDGET"] ?? environment["LLM4TS_JUDGE_SOURCES_LIMIT"]
+  const raw = environment["LLM4TS_CONTEXT_BUDGET"]
   if (raw === undefined) {
     return defaultContextBudget
   }

package/src/FlowError.ts

@@ -2,16 +2,16 @@ import * as Schema from "effect/Schema"
 import { Capability } from "@llm4ts/core/Capability"
 import { LlmError } from "@llm4ts/core/Errors"
 
-export class PersistenceError extends Schema.TaggedErrorClass<PersistenceError>()("Persistence", {
+export class PersistenceError extends Schema.TaggedError<PersistenceError>()("Persistence", {
   message: Schema.String,
   cause: Schema.optionalKey(Schema.Defect())
 }) {}
 
-export class PlanParseError extends Schema.TaggedErrorClass<PlanParseError>()("PlanParse", {
+export class PlanParseError extends Schema.TaggedError<PlanParseError>()("PlanParse", {
   message: Schema.String
 }) {}
 
-export class UnsupportedSchemaVersion extends Schema.TaggedErrorClass<UnsupportedSchemaVersion>()(
+export class UnsupportedSchemaVersion extends Schema.TaggedError<UnsupportedSchemaVersion>()(
   "UnsupportedSchemaVersion",
   {
     path: Schema.String,
@@ -24,15 +24,12 @@ export class UnsupportedSchemaVersion extends Schema.TaggedErrorClass<Unsupporte
   }
 }
 
-export class WorkspacePathError extends Schema.TaggedErrorClass<WorkspacePathError>()(
-  "WorkspacePath",
-  {
-    path: Schema.String,
-    message: Schema.String
-  }
-) {}
+export class WorkspacePathError extends Schema.TaggedError<WorkspacePathError>()("WorkspacePath", {
+  path: Schema.String,
+  message: Schema.String
+}) {}
 
-export class WorkspaceLimitError extends Schema.TaggedErrorClass<WorkspaceLimitError>()(
+export class WorkspaceLimitError extends Schema.TaggedError<WorkspaceLimitError>()(
   "WorkspaceLimit",
   {
     operation: Schema.String,
@@ -47,18 +44,18 @@ export class WorkspaceLimitError extends Schema.TaggedErrorClass<WorkspaceLimitE
   }
 }
 
-export class WorkspaceIoError extends Schema.TaggedErrorClass<WorkspaceIoError>()("WorkspaceIo", {
+export class WorkspaceIoError extends Schema.TaggedError<WorkspaceIoError>()("WorkspaceIo", {
   operation: Schema.String,
   path: Schema.String,
   message: Schema.String,
   cause: Schema.optionalKey(Schema.Defect())
 }) {}
 
-export class FlowAborted extends Schema.TaggedErrorClass<FlowAborted>()("Aborted", {
+export class FlowAborted extends Schema.TaggedError<FlowAborted>()("Aborted", {
   message: Schema.String
 }) {}
 
-export class ProcessError extends Schema.TaggedErrorClass<ProcessError>()("Process", {
+export class ProcessError extends Schema.TaggedError<ProcessError>()("Process", {
   message: Schema.String,
   detail: Schema.String
 }) {}
@@ -80,7 +77,7 @@ export const describeFlowError = (error: unknown): string => {
   return detail.length === 0 || base.includes(detail) ? base : `${base}: ${detail}`
 }
 
-export class FlowLlmError extends Schema.TaggedErrorClass<FlowLlmError>()("Llm", {
+export class FlowLlmError extends Schema.TaggedError<FlowLlmError>()("Llm", {
   message: Schema.String,
   cause: Schema.optionalKey(LlmError)
 }) {
@@ -91,7 +88,7 @@ export class FlowLlmError extends Schema.TaggedErrorClass<FlowLlmError>()("Llm",
     })
 }
 
-export class FlowCapabilityDenied extends Schema.TaggedErrorClass<FlowCapabilityDenied>()(
+export class FlowCapabilityDenied extends Schema.TaggedError<FlowCapabilityDenied>()(
   "CapabilityDenied",
   {
     capability: Capability,
@@ -105,7 +102,7 @@ export class FlowCapabilityDenied extends Schema.TaggedErrorClass<FlowCapability
   }
 }
 
-export class ColumnNotFound extends Schema.TaggedErrorClass<ColumnNotFound>()("ColumnNotFound", {
+export class ColumnNotFound extends Schema.TaggedError<ColumnNotFound>()("ColumnNotFound", {
   title: Schema.String,
   available: Schema.Array(Schema.String)
 }) {
@@ -114,7 +111,7 @@ export class ColumnNotFound extends Schema.TaggedErrorClass<ColumnNotFound>()("C
   }
 }
 
-export class BudgetExceeded extends Schema.TaggedErrorClass<BudgetExceeded>()("BudgetExceeded", {
+export class BudgetExceeded extends Schema.TaggedError<BudgetExceeded>()("BudgetExceeded", {
   metric: Schema.Literals(["tokens", "costUsd"]),
   limit: Schema.Number,
   actual: Schema.Number
@@ -125,19 +122,16 @@ 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)
-  }
-) {
+export class StoryPlanInvalid extends Schema.TaggedError<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>()(
+export class PerimeterViolation extends Schema.TaggedError<PerimeterViolation>()(
   "PerimeterViolation",
   {
     story: Schema.String,
@@ -158,7 +152,7 @@ export class PerimeterViolation extends Schema.TaggedErrorClass<PerimeterViolati
 }
 
 /** The coder ended a story with `BLOCKED_ON:` — unplanned work belongs to another story. */
-export class MissingDependency extends Schema.TaggedErrorClass<MissingDependency>()(
+export class MissingDependency extends Schema.TaggedError<MissingDependency>()(
   "MissingDependency",
   {
     story: Schema.String,
@@ -171,7 +165,7 @@ export class MissingDependency extends Schema.TaggedErrorClass<MissingDependency
 }
 
 /** A story branch did not merge cleanly into the epic branch; the merge was aborted. */
-export class MergeConflict extends Schema.TaggedErrorClass<MergeConflict>()("MergeConflict", {
+export class MergeConflict extends Schema.TaggedError<MergeConflict>()("MergeConflict", {
   branch: Schema.String,
   into: Schema.String,
   paths: Schema.Array(Schema.String)
@@ -183,7 +177,7 @@ export class MergeConflict extends Schema.TaggedErrorClass<MergeConflict>()("Mer
 }
 
 /** One story failed; carries the story id so a fail-fast run names its cause. */
-export class StoryFailed extends Schema.TaggedErrorClass<StoryFailed>()("StoryFailed", {
+export class StoryFailed extends Schema.TaggedError<StoryFailed>()("StoryFailed", {
   story: Schema.String,
   reason: Schema.String
 }) {

package/src/Pack.ts

@@ -202,7 +202,14 @@ export const loadPack = Effect.fn("@llm4ts/flow/Pack.load")(function* (
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([name, text]) => parseReviewer(name, text))
   const fields = manifest.fields
-  const programFiles = fields["programFiles"]
+  if (fields["programFiles"] !== undefined) {
+    return yield* PlanParseError.make({
+      message:
+        "pack manifest 'programFiles:' was renamed 'program-files:' in llm4ts 2.0 — " +
+        "rename the field (the value is unchanged)"
+    })
+  }
+  const programFiles = fields["program-files"]
   // Validated at load so a mis-typed template fails the pack, not a later
   // phase; substitution cannot introduce invalid syntax because the fallback
   // probe uses an alphanumeric stand-in and real substitutions are escaped

package/src/PageSpec.ts

@@ -68,7 +68,8 @@ export class PageApiCall extends Schema.Class<PageApiCall>("PageApiCall")({
   method: Schema.String,
   path: Schema.String,
   /** The ESB service behind the legacy endpoint, when known. */
-  esbService: Schema.optionalKey(Schema.String),
+  /** An ESB service identifier (`ESB_ACCT_LIST`), never prose: unknown means omit. */
+  esbService: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_.:/-]+$/))),
   request: Schema.Array(FieldMapping).pipe(
     Schema.withConstructorDefault(Effect.succeed(emptyMappings)),
     Schema.withDecodingDefaultKey(Effect.succeed(emptyMappings))
@@ -154,7 +155,7 @@ export const pageSpecShapeHint =
   "The block must be exactly: { page, route, title, complexity: low|medium|high, " +
   "forms: [{ name, action, fields: [{ name, label, type, required?, validations: [{ rule, message?, enforcedAt: client|server|both }] }] }], " +
   "dtos: [{ legacyName, domainName, fields: [{ legacyName, domainName, type }] }], " +
-  "apiCalls: [{ operation, method, path, esbService (the ESB service the legacy call goes through — omit only when there is none), request: [{ legacyName, domainName, type }], response: [{ legacyName, domainName, type }] for an ad-hoc object, or responseDto: <domainName of one of the dtos> with responseShape: single|list when the endpoint returns that DTO or a list of it (a table screen is a list) }], " +
+  "apiCalls: [{ operation, method, path, esbService (the identifier of the ESB service the legacy call goes through, such as ESB_ACCT_LIST — omit it when unknown or absent; never a sentence), request: [{ legacyName, domainName, type }], response: [{ legacyName, domainName, type }] for an ad-hoc object, or responseDto: <domainName of one of the dtos> with responseShape: single|list when the endpoint returns that DTO or a list of it (a table screen is a list) }], " +
   "navigation: { inbound: [string], outbound: [string], steps: [string] }, sessionState: [string], openQuestions: [string] }. " +
   "No other keys (no id, url, queryParams, esbCall, trigger, serverController); every apiCalls entry is an object with operation/method/path; " +
   "put anything that does not fit into the prose sections or openQuestions."

package/src/ProgramJudge.ts

@@ -101,7 +101,7 @@ const issues = (
  * A spec'd program with NO matching changed file is a deterministic gate
  * failure, not a silent pass. Skipping it would let the branch clear a bar the
  * old whole-branch judge would have failed. It also surfaces a mis-set
- * `programFiles:` immediately — the top documented risk of the per-program
+ * `program-files:` immediately — the top documented risk of the per-program
  * design — instead of quietly degrading coverage.
  */
 export const unimplemented = (programs: ReadonlyArray<string>): ReviewResult =>
@@ -112,8 +112,8 @@ export const unimplemented = (programs: ReadonlyArray<string>): ReviewResult =>
         title: `judge[${program}]: spec'd but no implementation files changed`,
         description:
           `${program} has a committed spec but no file on this branch matches the pack's ` +
-          "programFiles regex for it. Either the program is unimplemented, or the pack's " +
-          "`programFiles:` template does not match this repo's layout — check that before " +
+          "program-files regex for it. Either the program is unimplemented, or the pack's " +
+          "`program-files:` template does not match this repo's layout — check that before " +
           "assuming the former."
       })
     ),

package/src/Stories.ts

@@ -73,7 +73,8 @@ export class StoryState extends Schema.Class<StoryState>("StoryState")({
 
 export const EpicReportVersion = 1
 
-export const OutcomeStatus = Schema.Literals(["done", "failed", "skipped"])
+/** `waiting`: on hold behind a failed predecessor, runs once that is fixed. */
+export const OutcomeStatus = Schema.Literals(["done", "failed", "waiting"])
 export type OutcomeStatus = typeof OutcomeStatus.Type
 
 export class StoryOutcome extends Schema.Class<StoryOutcome>("StoryOutcome")({
@@ -81,7 +82,7 @@ export class StoryOutcome extends Schema.Class<StoryOutcome>("StoryOutcome")({
   title: Schema.String,
   status: OutcomeStatus,
   branch: Schema.optionalKey(Schema.String),
-  /** Failure or skip reason. */
+  /** Failure reason, or what a waiting story waits for. */
   reason: Schema.optionalKey(Schema.String),
   judge: Schema.optionalKey(Schema.String),
   /** ESTIMATES, never measurements (ADR 0012). */
@@ -111,7 +112,7 @@ export const renderEpicReport = (report: EpicReport): string => {
     "> the CLI seats report no usage. They are not measurements.",
     "",
     `- Epic branch: \`${report.epicBranch}\``,
-    `- Stories: ${report.stories.length} (done ${report.count("done")}, failed ${report.count("failed")}, skipped ${report.count("skipped")})`,
+    `- Stories: ${report.stories.length} (done ${report.count("done")}, failed ${report.count("failed")}, waiting ${report.count("waiting")})`,
     "",
     "| Story | Status | Branch | Est. tokens | Est. cost | Note |",
     "| --- | --- | --- | --- | --- | --- |"
@@ -393,6 +394,9 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       if (yield* context.git.branchExists(stored.branch)) {
         yield* context.git.deleteBranch(stored.branch)
       }
+      // The task checkpoint belongs to the old branch: left in place, the
+      // fresh branch would inherit "every task complete" and skip the coder.
+      yield* files.remove(planPath(story))
       stored = undefined
     }
     if (stored !== undefined && stored.status === "merged") {
@@ -477,6 +481,11 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       const judge = options.judge
       for (let round = 1; round <= judgeRounds; round += 1) {
         const diff = yield* storyContext.git.diffVsBase(epicBranch)
+        if (diff.trim().length === 0) {
+          // Nothing to judge is a deterministic failure, not a model call:
+          // a model asked to score an empty diff scores the prompt instead.
+          return yield* failed(story, "the story branch has no changes against the epic branch")
+        }
         const verdict = yield* judge(story, diff)
         if (verdict.isClean) {
           judgeNote = `judge cleared (round ${round})`
@@ -602,7 +611,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
     return {
       done: byStatus("done"),
       failed: byStatus("failed"),
-      skipped: byStatus("skipped"),
+      waiting: byStatus("waiting"),
       running: yield* Ref.get(running)
     }
   })
@@ -610,7 +619,8 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   const record = (outcome: StoryOutcome): Effect.Effect<void> =>
     Ref.update(outcomes, (current) => [...current, outcome])
 
-  const skipDependents = (story: Story): Effect.Effect<void, FlowError> =>
+  /** Dependents of a failed story go on hold: they run once it is fixed and rerun. */
+  const holdDependents = (story: Story): Effect.Effect<void, FlowError> =>
     Effect.gen(function* () {
       const current = yield* progress
       for (const id of dependentsOf(plan, story.id)) {
@@ -619,13 +629,13 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
           dependent === undefined ||
           current.done.has(id) ||
           current.failed.has(id) ||
-          current.skipped.has(id)
+          current.waiting.has(id)
         ) {
           continue
         }
-        const reason = `blocked by ${story.id}`
-        yield* record(StoryOutcome.make({ id, title: dependent.title, status: "skipped", reason }))
-        yield* board.skip(id, reason)
+        const reason = `waiting for ${story.id}`
+        yield* record(StoryOutcome.make({ id, title: dependent.title, status: "waiting", reason }))
+        yield* board.wait(id, reason)
       }
     })
 
@@ -673,7 +683,7 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
               reason: outcome.reason ?? "failed"
             })
           }
-          yield* skipDependents(completion.story)
+          yield* holdDependents(completion.story)
         }
       }
     })

package/src/StoryPlan.ts

@@ -182,7 +182,8 @@ export const topologicalWaves = (plan: StoryPlan): ReadonlyArray<ReadonlyArray<s
 export interface StoryProgress {
   readonly done: ReadonlySet<string>
   readonly failed: ReadonlySet<string>
-  readonly skipped: ReadonlySet<string>
+  /** On hold behind a failed predecessor. */
+  readonly waiting: ReadonlySet<string>
   readonly running: ReadonlySet<string>
 }
 
@@ -192,7 +193,7 @@ export const readyStories = (plan: StoryPlan, progress: StoryProgress): Readonly
     (story) =>
       !progress.done.has(story.id) &&
       !progress.failed.has(story.id) &&
-      !progress.skipped.has(story.id) &&
+      !progress.waiting.has(story.id) &&
       !progress.running.has(story.id) &&
       story.dependsOn.every((dependency) => progress.done.has(dependency))
   )