@stringsync/splates 0.0.0-stage → 0.0.45

package/needs.d.ts

@@ -0,0 +1,115 @@
+import { Duration } from "webappwiz/time";
+import type { ConversationState } from "./conversations.js";
+import { type Question } from "./plan.js";
+import type { Details } from "./show.js";
+/**
+ * What an agent needs from the person, by how much it costs to leave it:
+ * `waiting` has stopped on them, `assuming` goes ahead on a guess an answer
+ * may overturn, `working` needs nothing yet, and `idle` is not doing anything.
+ */
+export type Need = {
+    kind: "waiting";
+    why: Why;
+    /**
+     * What to act on: the ask, what a review asks you to look at, the
+     * first open question, or the failure.
+     */
+    subject: string;
+    /** When it stopped, where that is known. */
+    since: string | null;
+    /** The task's open questions, none for a task-less conversation. */
+    questions: Question[];
+    /** The agent handed out by this one it waits for, lifted onto it. */
+    via?: string;
+} | {
+    kind: "assuming";
+    /** The first open question. */
+    subject: string;
+    questions: Question[];
+    /** The agent handed out by this one whose questions it relays. */
+    via?: string;
+} | {
+    kind: "working";
+    /** The next step under `## Next`, else the Goal's first line. */
+    subject: string | null;
+} | {
+    kind: "idle";
+};
+/** One agent the page shows: a conversation, its task, or both. */
+export interface Needing {
+    conversation: ConversationState | null;
+    task: Details | null;
+    need: Need;
+}
+/**
+ * Every listed conversation, and every live task no listed conversation runs
+ * in (an external agent, run outside the page) and none is about to, with
+ * what each needs: those waiting first,
+ * oldest stop first, then those assuming, most open questions first, then the
+ * rest in the order given.
+ */
+export declare function needs({ tasks, conversations, }: {
+    tasks: Details[];
+    conversations: ConversationState[];
+}): Needing[];
+/**
+ * Why an agent waits: a live ACP ask (a permission or a form), a review it
+ * escalated for, any other escalation, open questions it ended its turn on,
+ * a failure, or for a task, no agent left on it (see `abandoned`).
+ */
+export type Why = "ask" | "review" | "escalated" | "questions" | "failed" | "abandoned";
+/**
+ * Every live task no listed conversation runs in, an external agent's, with
+ * what it needs, before `answeredThrough`. One handed to an agent shows once
+ * its conversation starts.
+ */
+export declare function externals(tasks: Details[], conversations: ConversationState[]): Needing[];
+/** What a task no listed conversation runs in needs: see `externals`. */
+export declare function needOfExternal(task: Details, conversations: ConversationState[]): Need;
+/**
+ * Whether no agent is left on an external task, for certain: the page
+ * conversation whose agent last took it is archived, or gone with the oldest
+ * archived ones, and no agent outside the page has taken it since. What it
+ * says of it, and since when; null while an agent may yet be on it. A
+ * conversation listed on another task may still have a subagent on this
+ * one, so only going quiet tells of it.
+ */
+export declare function abandoned(task: Details, conversations: ConversationState[]): {
+    subject: string;
+    since: string | null;
+} | null;
+/**
+ * How long an external agent's task goes without a sign of it at work before
+ * it shows as quiet: long enough for a test run or a long think.
+ */
+export declare const QUIET_AFTER: Duration;
+/**
+ * When an external agent's task last showed a sign of its agent at work, once
+ * that is `QUIET_AFTER` ago at `now`; null while it has lately, or nothing
+ * says. Only an agent taken to be at work goes quiet: one that waits on the
+ * person is still for a reason.
+ */
+export declare function quietSince({ task, need }: Pick<Needing, "task" | "need">, now: number): string | null;
+/**
+ * What one agent needs, from its conversation (null for an agent the page
+ * does not run) and the task it is in (null for the main tree).
+ */
+export declare function need(task: Details | null, conversation: ConversationState | null): Need;
+/**
+ * `found` with each agent that answers to another conversation waiting on
+ * that one rather than on the person: only the person answers its asks, so
+ * one waits on that one's row, where they show, whatever it is doing; its
+ * escalations reach the person through that one's reports, so one waits on
+ * that one's row once it is idle, having relayed it, naming the agent, and
+ * while it works on regardless, that one goes ahead with them owed, as an
+ * assuming agent does. A failure stays the agent's own, since nothing tells
+ * that one of it.
+ */
+export declare function answeredThrough(found: Needing[], conversations: ConversationState[]): Needing[];
+/**
+ * The conversation an agent answers to, rather than to the person, while the
+ * page holds it: the one that handed its conversation the task, or for an
+ * external agent, such as a subagent its harness started, the listed one
+ * whose agent added its task.
+ */
+export declare function answersTo({ conversation, task }: Pick<Needing, "conversation" | "task">, conversations: readonly ConversationState[]): ConversationState | null;

package/notices.d.ts

@@ -0,0 +1,39 @@
+import type { Needing } from "./needs.js";
+/** Something a row did worth telling the person about, away from the page. */
+export interface Notice {
+    row: Needing;
+    title: string;
+    body: string;
+}
+/** Which notices the person asked for, as the page's Notifications settings say. */
+export interface Wants {
+    waiting: boolean;
+    finished: boolean;
+    quiet: boolean;
+    /** Minutes a running agent goes without a word before it counts as quiet. */
+    quietAfter: number;
+}
+/**
+ * Tells what changed in the rows since the last look worth notifying of,
+ * the same on the page and on the server, which pushes it to a phone the
+ * page cannot run on once it leaves the front.
+ */
+export declare class Notices {
+    /** By row, what the last look saw; null before the first. */
+    private seen;
+    /**
+     * Compares `rows`, named by `name`, with the last look at `now`, and
+     * returns what changed worth telling, of the kinds `wants` asks for: a
+     * row that came to wait, a conversation that finished its turn, and one
+     * running with no word for the quiet time. The first look tells nothing,
+     * since it has nothing to compare.
+     */
+    look(rows: Needing[], name: (row: Needing) => string, now: number, wants: Wants): Notice[];
+}
+/** What tells `row` apart from the others, in a notification and its click. */
+export declare function keyOf(row: Needing): string;
+/**
+ * The first line of `markdown` with its marks taken out, cut to `length`:
+ * a notification shows plain text, and a phone only a line or so of it.
+ */
+export declare function plain(markdown: string, length: number): string;

package/offered.d.ts

@@ -0,0 +1,39 @@
+import type { Fs } from "webappwiz/system";
+import type { Conversation } from "./conversation.js";
+import type { Setting } from "./conversations.js";
+/**
+ * The agent settings offered across projects, with defaults changed only by
+ * user selections. Session reports can refresh available options without
+ * replacing the values the person picked.
+ */
+export declare class Offered {
+    /** `~/.splates/offered.json`, or a test's own. */
+    readonly path: string;
+    private readonly deps;
+    /** Read once, then kept: this process is the one writing it. */
+    private known;
+    /** Set when a newer splates wrote the file, which this one leaves alone. */
+    private newer;
+    /** Writes one after another, so none is lost to another. */
+    private writing;
+    constructor(
+    /** `~/.splates/offered.json`, or a test's own. */
+    path: string, deps: {
+        fs: Fs;
+    });
+    /** Every agent's settings, by its id; none for one never started. */
+    all(): Promise<Record<string, Setting[]>>;
+    /**
+     * Keeps `settings` as what `agent`'s sessions offer from now on, or, with
+     * `preserveChoices`, refreshes options while keeping existing default values.
+     */
+    remember(agent: string, settings: Setting[], { preserveChoices }?: {
+        preserveChoices?: boolean;
+    }): Promise<void>;
+    /** Saves only settings the person selected, leaving other defaults alone. */
+    choose(agent: string, settings: Setting[], ids: string[]): Promise<void>;
+    /** Tracks capabilities separately from explicit choices, including the opening form. */
+    track(conversation: Conversation, changed: () => void, picks?: Record<string, string>): void;
+    private read;
+    private write;
+}

package/opencode-usage.d.ts

@@ -0,0 +1,37 @@
+import type * as acp from "@agentclientprotocol/sdk";
+import type { ConversationState } from "./conversation-state.js";
+/** Observations, never a quota estimate or evidence of an invoice. */
+export interface OpenCodeUsage {
+    turns: ObservedTurn[];
+    costAt: string | null;
+    retry: {
+        attempt: number | null;
+        nextRetryAt: string | null;
+        message: string;
+        type: string | null;
+        status: number | null;
+    } | null;
+}
+/** Null means absent or invalid, including in logs predating instrumentation. */
+export interface ObservedTurn {
+    at: string;
+    until: string | null;
+    firstText: string | null;
+    requested: string | null;
+    confirmed: string | null;
+    cwd: string | null;
+    /** ACP prompt response; per turn, parent session only. */
+    tokens: {
+        input: number | null;
+        output: number | null;
+        cachedRead: number | null;
+        cachedWrite: number | null;
+    } | null;
+}
+export declare function metric(value: unknown): number | null;
+/** End exactly once, including cancellation, failure and worker reattachment. */
+export declare function finishObservation(state: ConversationState, at: string | null): void;
+/** Keep only documented retry fields; provider response bodies are not diagnostics. */
+export declare function safeOpenCodeUpdate(update: acp.SessionUpdate): acp.SessionUpdate;
+/** Snapshot fields independently; optional cache data is not evidence of zero. */
+export declare function observeTokens(state: ConversationState, usage: acp.Usage): void;

package/outcomes.d.ts

@@ -0,0 +1,114 @@
+import type { Fs } from "webappwiz/system";
+import type { Device } from "./conversation-state.js";
+import type { Finding } from "./findings.js";
+import type { Decision } from "./plan.js";
+import { type TaskUsage } from "./task-log.js";
+import type { DiffSize, MergeFailure, RemoveReason } from "./worktree.js";
+/**
+ * Every task that has ended on this machine, across projects, in
+ * `~/.splates/outcomes.jsonl`, oldest first. Unlike the journal it is never
+ * trimmed: a trend needs months of it, and a line per task stays small.
+ */
+export declare class Outcomes {
+    /** `~/.splates/outcomes.jsonl`, or a test's own. */
+    readonly path: string;
+    private readonly fs;
+    constructor(
+    /** `~/.splates/outcomes.jsonl`, or a test's own. */
+    path: string, fs: Fs);
+    /**
+     * Beside `path`, the usage of the turns tasks ended in, which `splates
+     * merge` writes its line too early to see. Apart from `path`, so splates
+     * versions that read only that never mistake one for a task.
+     */
+    get turnsPath(): string;
+    record(outcome: Outcome): Promise<void>;
+    list(): Promise<Outcome[]>;
+    /**
+     * Credits the task that `conversation`, logged at `log`, ended last in
+     * its turn from `since` to `until` with what the rest of that turn used,
+     * once the turn has ended and said it. Several ended in one turn: the
+     * last one's is what the turn finished on.
+     */
+    creditTurn(conversation: string, log: string, since: string, until: string): Promise<void>;
+    private get dir();
+}
+/**
+ * How one task ended, written as it goes. Its record goes with it, so this is
+ * what is left to tell whether tasks are getting easier to land over time.
+ */
+export interface Outcome {
+    /** The main tree of the repository the task was in. */
+    project: string;
+    task: string;
+    /** Where it landed or would have: trunk, or `task/<parent>` for a part. */
+    base: string;
+    ended: "merged" | "removed";
+    /** When it was added, as an ISO timestamp. */
+    startedAt: string;
+    /** When it was merged or removed, as an ISO timestamp. */
+    endedAt: string;
+    /** How many times it was handed to a person with questions. */
+    questionRounds: number;
+    /** How many times it was handed to a person to approve. */
+    reviewRounds: number;
+    /** Merges that failed on a conflict, the gate, or a base that would not move. */
+    failedMerges: number;
+    /** `failedMerges` by why each failed. Absent from lines written before it was kept. */
+    failedMergesBy?: Partial<Record<MergeFailure, number>>;
+    /** The questions its plan asked under `## Blocked`. Absent from older lines. */
+    questionsAsked?: number;
+    /** Of those, the ones that offered a `(chosen)` pick and were answered with a choice. */
+    picksAsked?: number;
+    /** Of `picksAsked`, those answered with another choice than the agent's. */
+    picksOverturned?: number;
+    /** Of `picksAsked`, those answered with the agent's choice but with words added. */
+    picksAmended?: number;
+    /** The calls its plan made without asking, under `## Assumptions` or challenged out of it. Absent from older lines. */
+    assumptionsMade?: number;
+    /** Of `assumptionsMade`, those the person challenged. */
+    assumptionsChallenged?: number;
+    /**
+     * Each call its plan made, asked or assumed, with its size and what became
+     * of it. Absent from older lines, whose calls the counts above alone keep.
+     */
+    decisions?: Decision[];
+    /** The systems its changed files fall in, by name. Absent from older lines. */
+    systems?: string[];
+    /** How long it waited on a person, escalated, in milliseconds. Absent from older lines. */
+    waitedMs?: number;
+    /** Why it was removed, when `splates remove --reason` said; null when merged or unsaid. */
+    removedFor?: RemoveReason | null;
+    /** For a merge, each commit's message it landed, oldest first. Absent from older lines. */
+    commits?: string[];
+    /**
+     * How many times the person spoke to its conversation from each layout of
+     * the page while it ran. Absent from older lines.
+     */
+    promptsFrom?: Partial<Record<Device, number>>;
+    /**
+     * What its own turns used, not the rest of its conversation's, the turn it
+     * ended in added from `turnsPath` once `splates server` saw it end. Absent from
+     * older lines, for a task with no conversation log to read, and, as read,
+     * for one with no tokens out, which never kept the turns that did its work.
+     */
+    usage?: TaskUsage;
+    /** How long its agent worked, its turns summed, in milliseconds. Absent as `usage` is. */
+    workedMs?: number;
+    /** What it landed, or for a removed task, what its branch held. Absent from older lines. */
+    size?: DiffSize;
+    /** What went worse than it could have. Absent from older lines, never read as none. */
+    findings?: Finding[];
+    /** The `splates server` conversation that ended it; null for an external agent. */
+    conversation: string | null;
+    /** The agent `splates add --agent` handed it to, if any. */
+    agent: string | null;
+    /** The model it was handed over with, if any. */
+    model: string | null;
+}
+/**
+ * How many prompts the person said from each layout in the conversation
+ * logged at `log`, from `since` to `until`: a conversation can outlive the
+ * task, or come to it already under way.
+ */
+export declare function promptsFrom(log: string, fs: Fs, since: string, until: string): Promise<Partial<Record<Device, number>>>;

package/package.json

@@ -1,6 +1,75 @@
 {
-  "name": "@stringsync/splates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@stringsync/splates",
+	"version": "0.0.45",
+	"description": "Runs several AI coding agents on one repository at once, each in its own git worktree",
+	"license": "MIT",
+	"author": "stringsync LLC",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/stringsync/splates.git",
+		"directory": "packages/splates"
+	},
+	"type": "module",
+	"imports": {
+		"#dev/*": "./dev/*"
+	},
+	"engines": {
+		"bun": ">=1.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@agentclientprotocol/sdk": "^1.7.0",
+		"webappwiz": "^0.0.45",
+		"zod": "^4.4.3"
+	},
+	"main": "./index.js",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		},
+		"./asked": {
+			"types": "./asked.d.ts",
+			"default": "./asked.js"
+		},
+		"./probe-runtime": {
+			"types": "./probe-runtime.d.ts",
+			"default": "./probe-runtime.js"
+		},
+		"./testing/agent": {
+			"types": "./fake-agent.d.ts",
+			"default": "./fake-agent.js"
+		},
+		"./config": {
+			"types": "./config.d.ts",
+			"default": "./config.js"
+		},
+		"./heavy": {
+			"types": "./heavy.d.ts",
+			"default": "./heavy.js"
+		},
+		"./skill-checks": {
+			"types": "./skill-checks.d.ts",
+			"default": "./skill-checks.js"
+		},
+		"./systems": {
+			"types": "./systems.d.ts",
+			"default": "./systems.js"
+		},
+		"./tunnel-provider": {
+			"types": "./tunnel-provider.d.ts",
+			"default": "./tunnel-provider.js"
+		},
+		"./update": {
+			"types": "./update.d.ts",
+			"default": "./update.js"
+		}
+	},
+	"bin": {
+		"splates": "./index.js",
+		"arbor": "./index.js"
+	}
+}

package/path.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from "webappwiz/log";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * Where a task lives, or (with no task) the main tree. Nothing but the path
+ * on stdout, so it composes: `cd "$(splates path)"`, `zed -a "$(splates path x)"`.
+ * Moving between trees is `cd` and nothing else, and the main tree is the one
+ * path a process standing in a worktree cannot otherwise name: git's
+ * `--show-toplevel` hands back the worktree it is already in.
+ */
+export declare function path({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, task?: string): Promise<void>;

package/plan.d.ts

@@ -0,0 +1,236 @@
+import type { Fs } from "webappwiz/system";
+/** The plan each task keeps at its worktree root, excluded from git. */
+export declare const PLAN_FILE = "SPLATES.md";
+/** Where tasks keep their plans: each worktree's `SPLATES.md`, read through `fs`. */
+export declare class Plans {
+    private readonly fs;
+    constructor(fs: Fs);
+    /**
+     * The plan in worktree `tree`, or null for none: an agent still on arbor's
+     * skill keeps it as `ARBOR.md`, read when there is no `SPLATES.md`.
+     */
+    read(tree: string): Promise<string | null>;
+    /**
+     * Keeps plans out of git in every worktree of the repository whose shared
+     * `.git` is `gitDir`, leaving the repo's own .gitignore alone.
+     */
+    exclude(gitDir: string): Promise<void>;
+}
+/**
+ * The one step under `## Next` a fresh task's `SPLATES.md` starts with, asking
+ * its agent to plan, which no one should read as the work under way.
+ */
+export declare const STUB_STEP = "fill in Goal and list the steps here as `- [ ]` items";
+/**
+ * What an `SPLATES.md` says its task is for: the first line under `## Goal`, or
+ * null when it says nothing yet. One line, since it sits beside other tasks'
+ * in `splates list --files`.
+ */
+export declare function goalLine(text: string): string | null;
+/**
+ * What an `SPLATES.md` says done means: all of `## Goal`, as markdown, or ""
+ * when it says nothing yet.
+ */
+export declare function goalOf(text: string): string;
+/**
+ * One `- [ ] 9.` item under `## Blocked`: something only a person can do.
+ * The item's line is its subject; lines indented under it are its body, and
+ * `- (a) ...`, `- [a] ...` or `- a. ...` lines among them are the answers it
+ * offers.
+ */
+export interface Question {
+    /** As the plan numbers it, `9`: the name a reply goes by. */
+    number: string;
+    /** Checked off, which the agent does once it has acted on the reply. */
+    done: boolean;
+    /** The item's own line, without its checkbox, number, size or reply. */
+    text: string;
+    /**
+     * How far the call reaches, from the `(large)` that leads its line, one of
+     * `SIZES` as the skill writes it; null when it has none.
+     */
+    size: string | null;
+    /**
+     * The markdown indented under it, dedented, choices left out: detail,
+     * code blocks, `![shot](/abs/path.png)` images. Empty when there is none.
+     */
+    body: string;
+    /** Whatever follows ` → `, or null when nobody has answered yet. */
+    reply: string | null;
+    /**
+     * What a person added once the reply was read, oldest first: each an
+     * indented `→ ` line under the question.
+     */
+    followUps: string[];
+    /**
+     * The answers it offers, in order. Empty for a question answered in words
+     * alone. A reply can always add words to its picks, or answer in words
+     * instead.
+     */
+    choices: Choice[];
+    /**
+     * `one` for `- (a)` choices, at most one of which a reply picks; `any` for
+     * `- [a]` choices, where it picks all that apply; `order` for `- a.`
+     * choices, which a reply puts in order, every one of them, as `b, a, c`.
+     * Null without choices.
+     */
+    pick: "one" | "any" | "order" | null;
+}
+/** One answer a question offers: `- (b) Migrate on next login`. */
+export interface Choice {
+    /** The letter it goes by: `b`. */
+    key: string;
+    /** What it says, without the `(chosen)` that may end it. */
+    text: string;
+    /**
+     * The markdown indented under it, dedented: most often the screenshot of
+     * what it would look like. Empty when there is none.
+     */
+    body: string;
+    /**
+     * Why the agent would go with it, or not: a `Why:` line under it, without
+     * the label, kept out of `body`. The page folds
+     * it away until asked. Empty when there is none.
+     */
+    why: string;
+    /**
+     * Marked `(chosen)`: what the agent went with while it waits for the reply,
+     * which picks nothing for the person.
+     */
+    chosen: boolean;
+}
+/**
+ * How far a call reaches, smallest first, as the skill defines each: small
+ * stays local and is cheap to redo, medium shapes a feature or spans
+ * systems, large is hard to undo or outward-facing. The one place the scheme
+ * lives: outcomes keep each call's size as the word it was written with, so
+ * a word dropped from here still reads back from older outcomes.
+ */
+export declare const SIZES: readonly ["small", "medium", "large"];
+/** `text` without the size that leads it, and that size, or null. */
+export declare function sized(text: string): {
+    text: string;
+    size: string | null;
+};
+/**
+ * Every numbered item under `## Blocked`, open or checked off, each with the
+ * indented lines under it. The reply is read off the item's own line: an
+ * answer is one line after the arrow, which the agent writes in from the
+ * user's reply in chat.
+ */
+export declare function questions(text: string): Question[];
+/**
+ * Every numbered item under `## Assumptions`: a call the agent made without
+ * asking, written as a question is, its `(chosen)` choice the one it took.
+ * Numbered in the same sequence as `## Blocked`, since a challenged one moves
+ * there under its number. None of them hold up a merge.
+ */
+export declare function assumptions(text: string): Question[];
+/**
+ * Adds what `line` offers to `asked`, saying whether it did: an indented
+ * `- (a) text` picks one, `- [a] text` picks any, and `- a. text` is put in
+ * order, and a line indented past a choice's dash, such as its screenshot,
+ * belongs to that choice. The first choice says which for the question. The
+ * same in a plan and in a conversation, which `asked.ts` reads with this.
+ */
+export declare function offers(asked: Pick<Question, "choices" | "pick">, line: string): boolean;
+/** `asked` with `body` as its own, and each choice's dedented. */
+export declare function settled(asked: Question, body: string[]): Question;
+/** Lines with the indent they all share taken off, blank ends trimmed. */
+export declare function dedent(lines: string[]): string;
+/**
+ * How the person met the agent's picks under `## Blocked`: the questions
+ * asked, those that offered a `(chosen)` choice and were answered with a
+ * choice, and of those, the ones answered with another, and the ones answered
+ * with the agent's choice but with words added, in the reply or a follow-up.
+ * A moot question, or one answered in words alone, is asked but picks nothing.
+ */
+export declare function picks(text: string): {
+    asked: number;
+    picked: number;
+    overturned: number;
+    amended: number;
+};
+/**
+ * One call a plan made, as an outcome keeps it: enough to count how the
+ * agent's recommendations fare by size, and to size it again by its line if
+ * the scheme changes.
+ */
+export interface Decision {
+    /** As the plan numbers it. */
+    number: string;
+    /** The item's line, without its size. */
+    text: string;
+    /** The word its line was sized with, or null for none. */
+    size: string | null;
+    /** Put to the person under `## Blocked`, or made without asking. */
+    how: "asked" | "assumed";
+    /**
+     * What became of the agent's recommendation: an assumption left alone is
+     * kept; a pick taken as it was, kept; taken with words added, amended;
+     * answered with another choice, overturned; an assumption the person
+     * challenged, challenged. Null for a question with no pick to meet, or
+     * one never answered with a choice.
+     */
+    ended: "kept" | "amended" | "overturned" | "challenged" | null;
+}
+/** Every call in the plan `text`, asked and assumed, in the order numbered. */
+export declare function decisions(text: string): Decision[];
+/**
+ * How many calls the agent made without asking, and how many of them the
+ * person challenged. A challenged one moves to `## Blocked` under its number
+ * with a reply starting `challenged:`, so it counts in both.
+ */
+export declare function assumptionCounts(text: string): {
+    made: number;
+    challenged: number;
+};
+/** What still stands between a task and trunk, as its plan tells it. */
+export interface Unfinished {
+    /** Each unchecked question under `## Blocked`, by number: `["2", "4"]`. */
+    questions: string[];
+    /** Each unchecked step under `## Next`, as written. */
+    steps: string[];
+}
+/**
+ * The questions and steps a plan leaves unchecked. Nothing in either means the
+ * task is ready to merge: `splates merge` lands it, and `splates escalate --review`
+ * asks a person to look first. A task with no plan has nothing left.
+ */
+export declare function unfinished(text: string): Unfinished;
+/** Whether {@link unfinished} found nothing left. */
+export declare function ready({ questions, steps }: Unfinished): boolean;
+/** What {@link unfinished} found, as a clause: `questions 1, 2 unchecked under ## Blocked`. */
+export declare function whatIsLeft({ questions, steps }: Unfinished): string;
+/**
+ * The plan with a new open question at the end of `## Blocked`, the section
+ * made if missing, numbered after the highest there or under
+ * `## Assumptions`. Returns the plan and the number it went by.
+ */
+export declare function withQuestion(text: string, subject: string, body?: string): {
+    plan: string;
+    number: string;
+};
+/**
+ * A question's number however a person typed it: `9`, `9.`, `Q9` and `q9:`
+ * all mean `9`. Null for anything that is not a number at all.
+ */
+export declare function questionNumber(raw: string): string | null;
+export interface PlanOptions {
+    /** The task name the title is expected to match. */
+    task: string;
+    /**
+     * Whether the task has escalated, which makes `## Blocked` required unless
+     * it escalated for a review.
+     */
+    escalated?: boolean;
+    /** Whether the escalation asks only to approve merging. */
+    review?: boolean;
+}
+/**
+ * Every way a task's `SPLATES.md` departs from the shape the agent skill
+ * prescribes, phrased for the agent that wrote it. Advisory only: a resumable
+ * plan is the point, and a malformed one still beats none, so nothing here
+ * blocks a merge.
+ */
+export declare function checkPlan(text: string, { task, escalated, review }: PlanOptions): string[];