@llm4ts/flow 2.26.0 → 2.27.0

package/dist/Retro.d.ts

@@ -0,0 +1,185 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { JsonSchema } from "@llm4ts/core/Models";
+import { Board } from "./BoardSync.ts";
+import { PersistenceError, type StoryPlanInvalid } from "./FlowError.ts";
+import { type FlowEventsShape } from "./FlowEvents.ts";
+import type { TraceLine } from "./FlowRecorder.ts";
+import { Plan } from "./Plan.ts";
+import { type PlainFileStoreShape } from "./Persistence.ts";
+import { ReviewResult } from "./Review.ts";
+import { EpicReport, StoryState } from "./Stories.ts";
+import { Story, StoryPlan } from "./StoryPlan.ts";
+import type { TranscriptEntry } from "./Transcript.ts";
+export interface RetroPaths {
+    readonly dir: string;
+    readonly digest: string;
+    readonly report: string;
+    readonly proposal: string;
+    readonly library: string;
+    readonly index: string;
+}
+/** Where a run's retro lives: `<state>/retro/<runId>.*`, indexed in `retro/retros.jsonl`. */
+export declare const retroPaths: (stateDir: string, runId: string) => RetroPaths;
+export declare const appendRetroIndex: (files: PlainFileStoreShape, stateDir: string, runId: string, at: number) => Effect.Effect<void, PersistenceError>;
+/** The retros written for this state folder, oldest first. */
+export declare const readRetroIndex: (files: PlainFileStoreShape, stateDir: string) => Effect.Effect<ReadonlyArray<{
+    readonly runId: string;
+    readonly at: number;
+}>>;
+/** What the run left behind for one story, as files on disk. */
+export interface StoryFiles {
+    readonly story: Story;
+    readonly state: StoryState | undefined;
+    readonly plan: Plan | undefined;
+    readonly findings: string | undefined;
+    readonly verdict: ReviewResult | undefined;
+}
+export interface RetroInputs {
+    readonly runId: string;
+    readonly plan: StoryPlan;
+    readonly trace: ReadonlyArray<TraceLine>;
+    /** Per story lane; `undefined` when the run kept no transcript at all. */
+    readonly transcripts: ReadonlyMap<string, ReadonlyArray<TranscriptEntry>> | undefined;
+    readonly report: EpicReport | undefined;
+    readonly board: Board | undefined;
+    readonly stories: ReadonlyArray<StoryFiles>;
+    /** Characters the whole digest may hold (`LLM4TS_RETRO_CHARS`, default 60 000). */
+    readonly budget?: number;
+}
+export declare const defaultRetroChars = 60000;
+/** Reads the per-story files the executor keeps under `<state>/stories/`. */
+export declare const loadStoryFiles: (files: PlainFileStoreShape, stateDir: string, story: Story) => Effect.Effect<StoryFiles, PersistenceError | import("./FlowError.ts").PlanParseError | import("./FlowError.ts").UnsupportedSchemaVersion | import("./FlowError.ts").WorkspacePathError | import("./FlowError.ts").WorkspaceLimitError | import("./FlowError.ts").WorkspaceIoError | import("./FlowError.ts").FlowAborted | import("./FlowError.ts").ProcessError | import("./FlowError.ts").FlowLlmError | import("./FlowError.ts").FlowCapabilityDenied | import("./FlowError.ts").ColumnNotFound | import("./FlowError.ts").BudgetExceeded | StoryPlanInvalid | import("./FlowError.ts").PerimeterViolation | import("./FlowError.ts").MissingDependency | import("./FlowError.ts").MergeConflict | import("./FlowError.ts").EpicCheckoutDirty | import("./FlowError.ts").RosterInvalid | import("./FlowError.ts").EpicIncomplete | import("./FlowError.ts").LandingFailed | import("./FlowError.ts").RefineRefused | import("./FlowError.ts").RosterExhausted | import("./FlowError.ts").StoryFailed | import("./FlowError.ts").DecisionsInvalid | import("./FlowError.ts").OpenPointsPending | import("./FlowError.ts").ExtractPackMissing | import("./FlowError.ts").EpicBriefInvalid | import("./FlowError.ts").EpicBriefNotApproved | import("./FlowError.ts").ContractConflict, never>;
+/** The epic's report and board, when the run wrote them. */
+export declare const loadEpicFiles: (files: PlainFileStoreShape, stateDir: string) => Effect.Effect<{
+    readonly report: EpicReport | undefined;
+    readonly board: Board | undefined;
+}, never, never>;
+/** The stories worth a retro: failed, waiting, or still active when the run ended. */
+export declare const retroCandidates: (inputs: RetroInputs) => ReadonlyArray<StoryFiles>;
+/** The digest a retro seat is given: code-built, deterministic, capped. */
+export declare const renderRetroDigest: (inputs: RetroInputs) => string;
+export declare const RetroFixKind: Schema.Literals<readonly ["tasks", "story", "refine", "none"]>;
+export type RetroFixKind = typeof RetroFixKind.Type;
+export declare const RetroTask: Schema.Struct<{
+    readonly title: Schema.String;
+    readonly description: Schema.String;
+}>;
+export type RetroTask = typeof RetroTask.Type;
+export declare const RetroStoryChanges: Schema.Struct<{
+    readonly description: Schema.optionalKey<Schema.String>;
+    readonly owned: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly sharedReadOnly: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly dependsOn: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly provides: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+export type RetroStoryChanges = typeof RetroStoryChanges.Type;
+/** One story's diagnosis and exactly one fix, discriminated by `kind`. */
+export declare const RetroStory: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly diagnosis: Schema.String;
+    readonly kind: Schema.Literals<readonly ["tasks", "story", "refine", "none"]>;
+    /** `tasks`: appended to the story's plan. */
+    readonly tasks: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly title: Schema.String;
+        readonly description: Schema.String;
+    }>>>;
+    /** `story`: the fields to change on the plan entry. */
+    readonly changes: Schema.optionalKey<Schema.Struct<{
+        readonly description: Schema.optionalKey<Schema.String>;
+        readonly owned: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly sharedReadOnly: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly dependsOn: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly provides: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+    /** `story`: why the entry itself is wrong. `none`: why nothing changes. */
+    readonly why: Schema.optionalKey<Schema.String>;
+    /** `refine`: the feedback a new round should take. */
+    readonly feedback: Schema.optionalKey<Schema.String>;
+}>;
+export type RetroStory = typeof RetroStory.Type;
+declare const RetroProposal_base: Schema.Class<RetroProposal, Schema.Struct<{
+    readonly summary: Schema.String;
+    readonly stories: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly diagnosis: Schema.String;
+        readonly kind: Schema.Literals<readonly ["tasks", "story", "refine", "none"]>;
+        /** `tasks`: appended to the story's plan. */
+        readonly tasks: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly title: Schema.String;
+            readonly description: Schema.String;
+        }>>>;
+        /** `story`: the fields to change on the plan entry. */
+        readonly changes: Schema.optionalKey<Schema.Struct<{
+            readonly description: Schema.optionalKey<Schema.String>;
+            readonly owned: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly sharedReadOnly: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly dependsOn: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly provides: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        }>>;
+        /** `story`: why the entry itself is wrong. `none`: why nothing changes. */
+        readonly why: Schema.optionalKey<Schema.String>;
+        /** `refine`: the feedback a new round should take. */
+        readonly feedback: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly runAdvice: Schema.$Array<Schema.Struct<{
+        readonly finding: Schema.String;
+        readonly evidence: Schema.String;
+    }>>;
+    readonly libraryAdvice: Schema.$Array<Schema.Struct<{
+        readonly title: Schema.String;
+        readonly evidence: Schema.String;
+        readonly suggestion: Schema.String;
+    }>>;
+}>, {}>;
+export declare class RetroProposal extends RetroProposal_base {
+}
+export declare const retroProposalJsonSchema: JsonSchema;
+/** The seat's instructions: the digest is the whole subject. */
+export declare const retroPrompt: (digest: string, storiesWithPlan: ReadonlyArray<string>) => string;
+export interface ValidatedRetro {
+    readonly proposal: RetroProposal;
+    /** What was dropped and why, for the report. */
+    readonly dropped: ReadonlyArray<string>;
+}
+/** Applies the story changes a proposal names; `undefined` when nothing would change. */
+export declare const storyWithChanges: (story: Story, changes: RetroStoryChanges) => Story | undefined;
+/** Code checks the seat's answer before anything is written; bad items are dropped, not fatal. */
+export declare const validateRetroProposal: (proposal: RetroProposal, plan: StoryPlan, storiesWithPlan: ReadonlySet<string>) => ValidatedRetro;
+export declare const AppliedMarkerPrefix = "- [x] Applied";
+export interface RetroApproval {
+    readonly approved: boolean;
+    readonly applied: boolean;
+}
+export declare const retroApprovalOf: (markdown: string) => RetroApproval;
+export interface RetroReportInputs {
+    readonly runId: string;
+    readonly plan: StoryPlan;
+    readonly validated: ValidatedRetro;
+    readonly workDir: string;
+    readonly epicDir: string;
+}
+/** The report a person reads and ticks. */
+export declare const renderRetroReport: (inputs: RetroReportInputs) => string;
+/** The note for llm4ts itself; `undefined` when the seat had nothing to say. */
+export declare const renderLibraryAdvice: (runId: string, epicId: string, proposal: RetroProposal) => string | undefined;
+/** Writes the four files of a retro and indexes it. */
+export declare const writeRetro: (files: PlainFileStoreShape, stateDir: string, inputs: RetroReportInputs & {
+    readonly digest: string;
+    readonly at: number;
+}) => Effect.Effect<RetroPaths, PersistenceError | import("./FlowError.ts").PlanParseError | import("./FlowError.ts").UnsupportedSchemaVersion | import("./FlowError.ts").WorkspacePathError | import("./FlowError.ts").WorkspaceLimitError | import("./FlowError.ts").WorkspaceIoError | import("./FlowError.ts").FlowAborted | import("./FlowError.ts").ProcessError | import("./FlowError.ts").FlowLlmError | import("./FlowError.ts").FlowCapabilityDenied | import("./FlowError.ts").ColumnNotFound | import("./FlowError.ts").BudgetExceeded | StoryPlanInvalid | import("./FlowError.ts").PerimeterViolation | import("./FlowError.ts").MissingDependency | import("./FlowError.ts").MergeConflict | import("./FlowError.ts").EpicCheckoutDirty | import("./FlowError.ts").RosterInvalid | import("./FlowError.ts").EpicIncomplete | import("./FlowError.ts").LandingFailed | import("./FlowError.ts").RefineRefused | import("./FlowError.ts").RosterExhausted | import("./FlowError.ts").StoryFailed | import("./FlowError.ts").DecisionsInvalid | import("./FlowError.ts").OpenPointsPending | import("./FlowError.ts").ExtractPackMissing | import("./FlowError.ts").EpicBriefInvalid | import("./FlowError.ts").EpicBriefNotApproved | import("./FlowError.ts").ContractConflict, never>;
+export interface AppliedRetros {
+    /** The plan after story edits, to run with. */
+    readonly plan: StoryPlan;
+    /** One line per thing done or skipped, already published. */
+    readonly notes: ReadonlyArray<string>;
+}
+/**
+ * Applies every approved, not yet applied retro of this state folder, oldest
+ * first: tasks go onto story plans, story edits onto the epic plan (saved,
+ * so the executor's hash check restarts them). Says what it did on the
+ * events. Nothing here fails the run: a retro that no longer fits is skipped.
+ */
+export declare const applyApprovedRetros: (files: PlainFileStoreShape, stateDir: string, plan: StoryPlan, events: FlowEventsShape, now: number) => Effect.Effect<AppliedRetros, PersistenceError | import("./FlowError.ts").PlanParseError | import("./FlowError.ts").UnsupportedSchemaVersion | import("./FlowError.ts").WorkspacePathError | import("./FlowError.ts").WorkspaceLimitError | import("./FlowError.ts").WorkspaceIoError | import("./FlowError.ts").FlowAborted | import("./FlowError.ts").ProcessError | import("./FlowError.ts").FlowLlmError | import("./FlowError.ts").FlowCapabilityDenied | import("./FlowError.ts").ColumnNotFound | import("./FlowError.ts").BudgetExceeded | StoryPlanInvalid | import("./FlowError.ts").PerimeterViolation | import("./FlowError.ts").MissingDependency | import("./FlowError.ts").MergeConflict | import("./FlowError.ts").EpicCheckoutDirty | import("./FlowError.ts").RosterInvalid | import("./FlowError.ts").EpicIncomplete | import("./FlowError.ts").LandingFailed | import("./FlowError.ts").RefineRefused | import("./FlowError.ts").RosterExhausted | import("./FlowError.ts").StoryFailed | import("./FlowError.ts").DecisionsInvalid | import("./FlowError.ts").OpenPointsPending | import("./FlowError.ts").ExtractPackMissing | import("./FlowError.ts").EpicBriefInvalid | import("./FlowError.ts").EpicBriefNotApproved | import("./FlowError.ts").ContractConflict, never>;
+export {};
+//# sourceMappingURL=Retro.d.ts.map

package/dist/Retro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Retro.d.ts","sourceRoot":"","sources":["../src/Retro.ts"],"names":[],"mappings":"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"}