@llm4ts/flow 2.17.0 → 2.19.0

package/src/EpicBrief.ts

@@ -473,6 +473,24 @@ export const BriefProblem = Schema.Union([
     scenario: Schema.String,
     disposition: Schema.String
   }),
+  Schema.Struct({
+    kind: Schema.Literal("AlreadyOwned"),
+    program: Schema.String,
+    scenario: Schema.String,
+    /** The approved epic that already has the scenario in scope. */
+    epic: Schema.String
+  }),
+  Schema.Struct({
+    kind: Schema.Literal("ContradictsBrief"),
+    program: Schema.String,
+    scenario: Schema.String,
+    /** The approved epic that decided otherwise. */
+    epic: Schema.String,
+    /** This brief's disposition, in words. */
+    here: Schema.String,
+    /** The other epic's disposition, in words. */
+    disposition: Schema.String
+  }),
   Schema.Struct({
     kind: Schema.Literal("ApprovedWithOpenPoints"),
     numbers: Schema.Array(Schema.Int)
@@ -498,11 +516,77 @@ export const renderBriefProblem = (problem: BriefProblem): string => {
       return `${problem.program}${cite}${problem.scenario} has no disposition: put it in scope, or drop, mark provided or defer it`
     case "RefineConflict":
       return `${problem.program}${cite}${problem.scenario} is in scope, but modernize-refine marked it ${problem.disposition}; answer \`keep: <why>\` to keep it in scope, or move it out`
+    case "AlreadyOwned":
+      return `${problem.program}${cite}${problem.scenario} is in scope here and in epic ${problem.epic}; answer \`keep: <why>\` to share it, or move it out`
+    case "ContradictsBrief":
+      return `${problem.program}${cite}${problem.scenario} is ${problem.here} here, but epic ${problem.epic} has it ${problem.disposition}; answer \`keep: <why>\` to keep this brief's decision, or follow the other`
     case "ApprovedWithOpenPoints":
       return `the brief is approved with unanswered open points: ${problem.numbers.join(", ")}`
   }
 }
 
+/** How a brief disposes of a scenario. */
+export type BriefDisposition = "in-scope" | "dropped" | "provided" | "deferred"
+
+export const dispositionWords: Readonly<Record<BriefDisposition, string>> = {
+  "in-scope": "in scope",
+  dropped: "dropped",
+  provided: "provided",
+  deferred: "deferred"
+}
+
+/** What an approved brief of another epic decided about a scenario (the coverage ledger). */
+export interface InheritedDecision {
+  readonly program: string
+  readonly scenario: string
+  readonly epic: string
+  readonly disposition: BriefDisposition
+  readonly note: string
+  /** The epics this decision was kept against on purpose (`keep: <why>` in that brief). */
+  readonly keptAgainst?: ReadonlyArray<string>
+}
+
+/**
+ * The one rule for two briefs on one scenario, read from the side of the
+ * brief that has `here`. A deferred scenario is free on either side; two
+ * briefs that agree are fine; both in scope is ownership shared or disputed;
+ * anything else is a contradiction. The ledger and the per-brief check both
+ * use it, so they cannot disagree about what a conflict is.
+ */
+export const crossProblem = (
+  program: string,
+  scenario: string,
+  here: BriefDisposition,
+  other: { readonly epic: string; readonly disposition: BriefDisposition }
+): BriefProblem | undefined => {
+  if (here === "deferred" || other.disposition === "deferred") return undefined
+  if (here === other.disposition) {
+    return here === "in-scope"
+      ? { kind: "AlreadyOwned", program, scenario, epic: other.epic }
+      : undefined
+  }
+  return {
+    kind: "ContradictsBrief",
+    program,
+    scenario,
+    epic: other.epic,
+    here: dispositionWords[here],
+    disposition: dispositionWords[other.disposition]
+  }
+}
+
+/**
+ * Whether the brief overrides a check on purpose: the check's own `[check]`
+ * question, answered `keep: <why>`. Any other answer, or an answer to
+ * another question, overrides nothing.
+ */
+export const hasOverride = (brief: EpicBrief, problem: BriefProblem): boolean =>
+  brief.openPoints.some(
+    (point) =>
+      point.question === `${checkMark} ${renderBriefProblem(problem)}` &&
+      (point.answer ?? "").trim().toLowerCase().startsWith("keep")
+  )
+
 /** The pointers of the provided entries: what the caller verifies before checking. */
 export const providedPointers = (brief: EpicBrief): ReadonlyArray<string> => [
   ...new Set(brief.provided.map((entry) => entry.note).filter((note) => note.length > 0))
@@ -515,6 +599,14 @@ export interface BriefCheckInputs {
   readonly pack: PackIndex
   /** The provided pointers that were found in the target (or its pack). */
   readonly pointers: ReadonlySet<string>
+  /**
+   * What approved briefs of other epics decided (the coverage ledger). Their
+   * decisions are inherited: they count towards completeness, and deciding
+   * otherwise here is a problem. Absent: the brief is checked on its own.
+   */
+  readonly others?: ReadonlyArray<InheritedDecision>
+  /** This brief's epic, as the other briefs name it. Default: the brief's own id. */
+  readonly epicId?: string
 }
 
 /** Every problem of a brief against the pack, all at once; empty means acceptable. */
@@ -593,6 +685,11 @@ export const checkEpicBrief = (
       problems.push({ kind: "DuplicateDisposition", program, scenario, lists: where })
     }
   }
+  const inherited = new Map<string, Array<InheritedDecision>>()
+  for (const decision of inputs.others ?? []) {
+    const key = slot(decision.program, decision.scenario)
+    inherited.set(key, [...(inherited.get(key) ?? []), decision])
+  }
   // Complete means every program the brief touches: the ones it lists as
   // considered, and any it cites or disposes of without listing.
   const touched = [
@@ -610,20 +707,13 @@ export const checkEpicBrief = (
       continue
     }
     for (const scenario of known.scenarios) {
-      if (!lists.has(slot(known.name, scenario))) {
+      if (!lists.has(slot(known.name, scenario)) && !inherited.has(slot(known.name, scenario))) {
         problems.push({ kind: "Unaccounted", program: known.name, scenario })
       }
     }
   }
 
   // A scenario refine took out of the pack's scope can come back only on purpose.
-  // The override is explicit: the check's own question, answered `keep: <why>`.
-  const justified = (conflict: BriefProblem): boolean =>
-    brief.openPoints.some(
-      (point) =>
-        point.question === `${checkMark} ${renderBriefProblem(conflict)}` &&
-        (point.answer ?? "").trim().toLowerCase().startsWith("keep")
-    )
   for (const item of brief.scope) {
     for (const citation of item.citations) {
       const refined = inputs.pack.refine.find(
@@ -639,11 +729,35 @@ export const checkEpicBrief = (
           scenario: citation.scenario,
           disposition: refined.disposition
         }
-        if (!justified(conflict)) problems.push(conflict)
+        if (!hasOverride(brief, conflict)) problems.push(conflict)
       }
     }
   }
 
+  // Approved briefs of other epics stand; `crossProblem` says when two briefs
+  // clash. A clash one side kept on purpose is settled: shared ownership when
+  // either keeps it, a contradiction when exactly one does.
+  const self = inputs.epicId ?? brief.epicId
+  const byWords = new Map<string, BriefDisposition>([
+    ["in scope", "in-scope"],
+    ["dropped", "dropped"],
+    ["provided", "provided"],
+    ["deferred", "deferred"]
+  ])
+  for (const [key, where] of lists) {
+    const [program = "", scenario = ""] = key.split("\u0000")
+    const here = byWords.get(where[0] ?? "")
+    if (here === undefined) continue
+    for (const other of inherited.get(key) ?? []) {
+      const problem = crossProblem(program, scenario, here, other)
+      if (problem === undefined) continue
+      const theyKept = (other.keptAgainst ?? []).includes(self)
+      const iKept = hasOverride(brief, problem)
+      const settled = problem.kind === "AlreadyOwned" ? theyKept || iKept : theyKept !== iKept
+      if (!settled) problems.push(problem)
+    }
+  }
+
   const pending = unanswered(brief)
   if (brief.status === "approved" && pending.length > 0) {
     problems.push({ kind: "ApprovedWithOpenPoints", numbers: pending.map((point) => point.number) })

package/src/FlowError.ts

@@ -237,6 +237,16 @@ export class LandingFailed extends Schema.TaggedError<LandingFailed>()("LandingF
   }
 }
 
+/** A refine round cannot start, or the epic cannot take one; the reason says what to do next (ADR 0021). */
+export class RefineRefused extends Schema.TaggedError<RefineRefused>()("RefineRefused", {
+  epicId: Schema.String,
+  reason: Schema.String
+}) {
+  get message(): string {
+    return `epic '${this.epicId}' cannot be refined: ${this.reason}`
+  }
+}
+
 /** The start of every `RosterExhausted` message, so it is recognisable once wrapped. */
 export const rosterExhaustedPrefix = "roster exhausted: no executor can ever take the role"
 
@@ -366,6 +376,7 @@ export const FlowError = Schema.Union([
   ContractConflict,
   ExtractPackMissing,
   EpicBriefInvalid,
-  EpicBriefNotApproved
+  EpicBriefNotApproved,
+  RefineRefused
 ])
 export type FlowError = typeof FlowError.Type

package/src/Landing.ts

@@ -15,7 +15,7 @@ import { statusPaths } from "./GitTool.ts"
 import { loadVersioned, saveVersioned, type PlainFileStoreShape } from "./Persistence.ts"
 import type { ReviewResult } from "./Review.ts"
 import { StoryState, StoryStateVersion } from "./Stories.ts"
-import type { StoryPlan } from "./StoryPlan.ts"
+import type { Story, StoryPlan } from "./StoryPlan.ts"
 
 const join = (root: string, path: string): string =>
   `${root.replace(/[\\/]+$/, "")}/${path.replace(/^[\\/]+/, "")}`
@@ -49,6 +49,11 @@ export interface LandOptions {
   readonly maxRounds?: number
   /** Keep the story worktrees and branches after landing. Default false: they go. */
   readonly keepWorktrees?: boolean
+  /**
+   * The epic's refine rounds (ADR 0021), each with its own plan and state
+   * folder: they must be merged too, and their worktrees go with the plan's.
+   */
+  readonly rounds?: ReadonlyArray<{ readonly plan: StoryPlan; readonly stateDir: string }>
 }
 
 export interface LandReport {
@@ -88,11 +93,15 @@ export const landEpic = Effect.fn("@llm4ts/flow/Landing.land")(function* (
   const failed = (reason: string) => LandingFailed.make({ epicBranch, target, reason })
 
   // 1. Only a finished epic lands.
+  // The plan's stories, then each round's, every one against its own state folder.
+  const tracked = [{ plan, stateDir: options.stateDir }, ...(options.rounds ?? [])].flatMap(
+    (part) => part.plan.stories.map((story) => ({ id: story.id, stateDir: part.stateDir }))
+  )
   const unmerged: Array<string> = []
-  for (const story of plan.stories) {
+  for (const story of tracked) {
     const state = yield* loadVersioned(
       files,
-      join(options.stateDir, `stories/${story.id}.json`),
+      join(story.stateDir, `stories/${story.id}.json`),
       StoryStateVersion,
       StoryState
     )
@@ -133,7 +142,16 @@ export const landEpic = Effect.fn("@llm4ts/flow/Landing.land")(function* (
     events,
     agent: "coder"
   })
-  const stories = plan.stories.map((story) => `- ${story.id}: ${story.provides.join("; ")}`)
+  const provided = (story: Story): string => `- ${story.id}: ${story.provides.join("; ")}`
+  // A round changed what the plan's stories built (it may have removed some of
+  // it): the coder must not resolve a conflict back to the older intent.
+  const stories = [
+    ...plan.stories.map(provided),
+    ...(options.rounds ?? []).flatMap((round, index) => [
+      `and later changed on feedback (refine round ${index + 1}, which wins over the above):`,
+      ...round.plan.stories.map(provided)
+    ])
+  ]
   let rounds = 0
   while (true) {
     const withMarkers: Array<string> = []
@@ -211,10 +229,10 @@ export const landEpic = Effect.fn("@llm4ts/flow/Landing.land")(function* (
   let deletedBranches = 0
   if (options.keepWorktrees !== true) {
     const kept: Array<string> = []
-    for (const story of plan.stories) {
+    for (const story of tracked) {
       const state = yield* loadVersioned(
         files,
-        join(options.stateDir, `stories/${story.id}.json`),
+        join(story.stateDir, `stories/${story.id}.json`),
         StoryStateVersion,
         StoryState
       )

package/src/RefineRound.ts

@@ -0,0 +1,227 @@
+// Refine rounds (ADR 0021): follow-up stories on a finished epic, planned
+// from feedback. A round is its own story plan on the epic's branch, so the
+// executor and the ownership rule are the ones a plan has. Pure: reading the
+// round folders and asking the planner belong to the flow.
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { JsonSchema } from "@llm4ts/core/Models"
+import { Story, StoryPlan } from "./StoryPlan.ts"
+
+/** A feedback item the planner left out, with the reason or the question to answer. */
+export class NotPlanned extends Schema.Class<NotPlanned>("NotPlanned")({
+  item: Schema.String,
+  reason: Schema.String
+}) {}
+
+/** What the planner returns for a round: the stories it can place, and the rest. */
+export class RefineProposal extends Schema.Class<RefineProposal>("RefineProposal")({
+  stories: Schema.Array(Story),
+  notPlanned: Schema.Array(NotPlanned).pipe(
+    Schema.withConstructorDefault(Effect.succeed([])),
+    Schema.withDecodingDefaultKey(Effect.succeed([]))
+  )
+}) {}
+
+const strings: JsonSchema = { type: "array", items: { type: "string" } }
+
+export const refineProposalJsonSchema: JsonSchema = {
+  type: "object",
+  properties: {
+    stories: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          title: { type: "string" },
+          description: { type: "string" },
+          dependsOn: strings,
+          owned: strings,
+          sharedReadOnly: strings,
+          provides: strings
+        },
+        required: ["id", "title", "description", "dependsOn", "owned", "sharedReadOnly", "provides"]
+      }
+    },
+    notPlanned: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: { item: { type: "string" }, reason: { type: "string" } },
+        required: ["item", "reason"]
+      }
+    }
+  },
+  required: ["stories", "notPlanned"]
+}
+
+/** Round stories are `r<n>-…`: unique across the epic, whatever the planner called them. */
+export const roundPrefix = (round: number): string => `r${round}-`
+
+/**
+ * The round's story plan from a proposal. Ids get the round's prefix (once),
+ * dependencies follow, and a dependency on a story merged before the round
+ * (`earlier`) is dropped: a round only starts once those are in the branch.
+ */
+export const assembleRound = (inputs: {
+  readonly epicId: string
+  readonly round: number
+  readonly feedback: string
+  readonly proposal: RefineProposal
+  /** Ids of every story of the epic's plan and of the earlier rounds. */
+  readonly earlier: ReadonlyArray<string>
+}): StoryPlan => {
+  const prefix = roundPrefix(inputs.round)
+  const prefixed = (id: string): string => (id.startsWith(prefix) ? id : `${prefix}${id}`)
+  const own = new Set(inputs.proposal.stories.map((story) => story.id))
+  const earlier = new Set(inputs.earlier)
+  return StoryPlan.make({
+    epicId: inputs.epicId,
+    epic: inputs.feedback,
+    stories: inputs.proposal.stories.map((story) =>
+      Story.make({
+        ...story,
+        id: prefixed(story.id),
+        dependsOn: story.dependsOn
+          .filter((dependency) => own.has(dependency) || !earlier.has(dependency))
+          .map(prefixed)
+      })
+    )
+  })
+}
+
+/** What to do about a round whose plan cannot be read: a plan alone is never deleted. */
+export const roundRepair = (round: number): string =>
+  `fix the plan, or delete the folder rounds/${round} and every later round`
+
+/** A round as the run decision sees it. */
+export interface RoundProgress {
+  readonly round: number
+  readonly stories: number
+  readonly merged: number
+  /** Why its plan cannot be read, naming the file. */
+  readonly unreadable?: string
+}
+
+export type RunAction =
+  | { readonly _tag: "RunPlan" }
+  | { readonly _tag: "RunRound"; readonly round: number }
+  | { readonly _tag: "PlanRound"; readonly round: number }
+  | { readonly _tag: "Land" }
+  | { readonly _tag: "Refused"; readonly reason: string }
+  | { readonly _tag: "Usage"; readonly message: string }
+
+export interface RunInputs {
+  /** The epic has a story plan. */
+  readonly planned: boolean
+  readonly stories: number
+  readonly merged: number
+  /** The branch the epic landed on, once it has. */
+  readonly landed: string | undefined
+  readonly rounds: ReadonlyArray<RoundProgress>
+  /** `--refine` was given. */
+  readonly refine: boolean
+  /** The text given with `--refine`. */
+  readonly feedback: string
+  /** `--land` was given. */
+  readonly land: boolean
+}
+
+/**
+ * What a run of the epic does: its plan's stories, the open round, a new
+ * round, or the landing. A round starts only when everything before it is
+ * merged, and an open round is finished before another is planned.
+ */
+export const runAction = (inputs: RunInputs): RunAction => {
+  if (inputs.land) {
+    // Landing with feedback in hand would drop the feedback for good.
+    return inputs.refine && inputs.feedback.trim().length > 0
+      ? {
+          _tag: "Usage",
+          message:
+            "--refine with feedback and --land do not go together: run the round first, then land"
+        }
+      : { _tag: "Land" }
+  }
+  const planOpen = inputs.merged < inputs.stories
+  const unreadable = inputs.rounds.find((round) => round.unreadable !== undefined)
+  const open = inputs.rounds.find((round) => round.merged < round.stories)
+  const broken = (round: RoundProgress): RunAction => ({
+    _tag: "Refused",
+    reason: `round ${round.round}'s plan cannot be read (${round.unreadable ?? ""}); ${roundRepair(round.round)}`
+  })
+  if (!inputs.refine) {
+    if (planOpen) {
+      return { _tag: "RunPlan" }
+    }
+    if (unreadable !== undefined) {
+      return broken(unreadable)
+    }
+    return open === undefined ? { _tag: "RunPlan" } : { _tag: "RunRound", round: open.round }
+  }
+  if (!inputs.planned) {
+    return { _tag: "Refused", reason: "it has no story plan yet: run the epic first" }
+  }
+  if (inputs.landed !== undefined) {
+    return {
+      _tag: "Refused",
+      reason: `it has landed on ${inputs.landed}; give the changes as a new epic`
+    }
+  }
+  if (unreadable !== undefined) {
+    return broken(unreadable)
+  }
+  if (planOpen) {
+    return {
+      _tag: "Refused",
+      reason: `${inputs.merged} of ${inputs.stories} stories merged: rerun the epic until every story merges`
+    }
+  }
+  const feedback = inputs.feedback.trim()
+  if (open !== undefined) {
+    return feedback.length === 0
+      ? { _tag: "RunRound", round: open.round }
+      : {
+          _tag: "Refused",
+          reason: `round ${open.round} is open (${open.merged} of ${open.stories} stories merged): rerun without --refine text to finish it, or edit its plan`
+        }
+  }
+  if (feedback.length === 0) {
+    return { _tag: "Usage", message: "--refine needs the feedback to plan a round from" }
+  }
+  return { _tag: "PlanRound", round: inputs.rounds.length + 1 }
+}
+
+const oneLine = (text: string): string => text.replace(/\s+/g, " ").trim()
+
+/** `not-planned.md`: one line per item left out, for the person and for the next round's planner. */
+export const renderNotPlanned = (round: number, items: ReadonlyArray<NotPlanned>): string =>
+  [
+    `# Not planned in round ${round}`,
+    "",
+    ...(items.length === 0
+      ? ["Every feedback item was planned."]
+      : items.map((entry) => `- **${oneLine(entry.item)}** — ${oneLine(entry.reason)}`)),
+    ""
+  ].join("\n")
+
+export const countNotPlanned = (markdown: string): number =>
+  markdown.split("\n").filter((line) => line.startsWith("- **")).length
+
+/** An earlier story as a round's planner is shown it: what was built, and where. */
+export interface EarlierStory {
+  readonly id: string
+  readonly title: string
+  readonly owned: ReadonlyArray<string>
+  readonly provides: ReadonlyArray<string>
+}
+
+export const earlierStories = (plans: ReadonlyArray<StoryPlan>): ReadonlyArray<EarlierStory> =>
+  plans.flatMap((plan) =>
+    plan.stories.map((story) => ({
+      id: story.id,
+      title: story.title,
+      owned: story.owned,
+      provides: story.provides
+    }))
+  )