@turri-dev/cli 0.1.8 → 0.1.9

package/dist/regenerate/chunk-plan.d.ts

@@ -82,7 +82,10 @@ export declare const MAX_SPECS_PER_JOB = 3;
 /** The most a pulse's title is - in words, and in characters - however it was made: a host shows it as its heading. */
 export declare const TITLE_WORDS = 10;
 export declare const TITLE_CHARS = 70;
-/** A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. */
+/**
+ * A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. Text
+ * cut already is cut again without stacking a second: several first lines joined, each cut, end on one ellipsis.
+ */
 export declare function shortTitle(text: string, chars?: number, words?: number): string;
 export declare const MAX_LINES_PER_JOB = 120;
 /**
@@ -140,22 +143,39 @@ export interface PlaceAnswer {
     /** What of the person's wishes it did not follow, and why. */
     notes?: string;
 }
+/** A group to title: the number the agent answers with, and its functional specs' text. */
+export interface TitleGroup {
+    number: number;
+    specs: string[];
+}
+export interface TitleAnswer {
+    titles: Array<{
+        group: number;
+        title: string;
+    }>;
+}
 /**
- * The two judgements, each asked again with what was wrong with its answer - the last answer given, whether it holds
- * or not: the plan checks it again. Injectable, so the plan is testable without a model.
+ * The judgements, each asked again with what was wrong with its answer - the last answer given, whether it holds
+ * or not: the plan checks it again. Injectable, so the plan is testable without a model. `title` titles the groups no
+ * agent titled - the conformance tests', and a grouping that fell back - for what each pulse does, rather than its
+ * first functional spec's first line; without it, they keep that.
  */
 export interface ChunkAgents {
     group(specs: NewSpec[], check: (answer: GroupAnswer) => string[], steering?: Steering[], maxSpecs?: number): Promise<GroupAnswer | undefined>;
     place(input: PlaceInput, check: (answer: PlaceAnswer) => string[]): Promise<PlaceAnswer | undefined>;
+    title?(groups: TitleGroup[], check: (answer: TitleAnswer) => string[], track: "code" | "conformance"): Promise<TitleAnswer | undefined>;
 }
 /** What is wrong with a grouping: every new functional spec once, in order, next to each other, none too big. */
 export declare function groupProblems(specs: NewSpec[], answer: GroupAnswer, maxSpecs?: number): string[];
+/** What is wrong with a titling: every group titled once, by its number, none empty, none too long. */
+export declare function titleProblems(groups: TitleGroup[], answer: TitleAnswer): string[];
 /** What is wrong with a placement: every new req once, each where there is such a job. */
 export declare function placeProblems(input: PlaceInput, answer: PlaceAnswer): string[];
 export declare function planChunks(input: PlanInput, agents?: ChunkAgents, notes?: string[]): Promise<DraftJob[]>;
 export declare function groupPrompt(specs: NewSpec[], steering?: Steering[], maxSpecs?: number): string;
 export declare function placePrompt(input: PlaceInput): string;
-/** The chunking's two agents, on a model - fresh for every plan. */
+export declare function titlePrompt(groups: TitleGroup[], track: "code" | "conformance"): string;
+/** The chunking's agents, on a model - fresh for every plan. */
 export declare function llmChunkAgents(options: {
     cwd: string;
     model?: string;

package/dist/regenerate/chunk-plan.js

@@ -74,15 +74,23 @@ export const MAX_SPECS_PER_JOB = 3;
 /** The most a pulse's title is - in words, and in characters - however it was made: a host shows it as its heading. */
 export const TITLE_WORDS = 10;
 export const TITLE_CHARS = 70;
-/** A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. */
+/** Whether a title is within `TITLE_WORDS` and `TITLE_CHARS`. */
+function fitsTitle(title) {
+    return title.trim().split(/\s+/).length <= TITLE_WORDS && title.trim().length <= TITLE_CHARS;
+}
+/**
+ * A title held to `TITLE_WORDS` and `TITLE_CHARS` - or less, for room beside it - cut at a word, with an ellipsis. Text
+ * cut already is cut again without stacking a second: several first lines joined, each cut, end on one ellipsis.
+ */
 export function shortTitle(text, chars = TITLE_CHARS, words = TITLE_WORDS) {
     const all = text.trim().split(/\s+/).filter((word) => word !== "");
     let cut = all.slice(0, words).join(" ");
     if (all.length <= words && cut.length <= chars)
         return cut;
+    cut = cut.replace(/[\s,.;:…-]+$/, "");
     if (cut.length > chars - 1)
         cut = cut.slice(0, chars - 1).replace(/\s+\S*$/, "") || cut.slice(0, chars - 1);
-    return `${cut.replace(/[\s,.;:-]+$/, "")}…`;
+    return `${cut.replace(/[\s,.;:…-]+$/, "")}…`;
 }
 export const MAX_LINES_PER_JOB = 120;
 /** How often an answer that does not hold goes back to its agent before the plan falls back. */
@@ -137,9 +145,31 @@ export function groupProblems(specs, answer, maxSpecs = MAX_SPECS_PER_JOB) {
         }
         if (group.title.trim() === "")
             problems.push("Every group needs a title.");
-        else if (group.title.trim().split(/\s+/).length > TITLE_WORDS || group.title.trim().length > TITLE_CHARS) {
+        else if (!fitsTitle(group.title))
             problems.push(`"${group.title}" is too long for a title: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`);
-        }
+    }
+    return problems;
+}
+/** What is wrong with a titling: every group titled once, by its number, none empty, none too long. */
+export function titleProblems(groups, answer) {
+    const problems = [];
+    const numbers = groups.map((group) => group.number);
+    const seen = new Map();
+    for (const entry of answer.titles) {
+        if (!numbers.includes(entry.group))
+            problems.push(`There is no group ${entry.group}.`);
+        seen.set(entry.group, (seen.get(entry.group) ?? 0) + 1);
+        if (entry.title.trim() === "")
+            problems.push(`Group ${entry.group} needs a title.`);
+        else if (!fitsTitle(entry.title))
+            problems.push(`"${entry.title}" is too long for a title: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.`);
+    }
+    for (const number of numbers) {
+        const times = seen.get(number) ?? 0;
+        if (times === 0)
+            problems.push(`Group ${number} has no title: every group is titled.`);
+        if (times > 1)
+            problems.push(`Group ${number} is titled ${times} times: once.`);
     }
     return problems;
 }
@@ -271,8 +301,8 @@ function plannerFailed(step, error) {
 export async function planChunks(input, agents, notes) {
     if (input.track !== "conformance")
         return cut(input, agents, notes);
-    // The conformance tests are grouped by the harness, as one job as far as the guardrail lets: no agent is asked.
-    return anchored(await cut(input), netChanges(input.base, input.current));
+    // The conformance tests are grouped by the harness, as one job as far as the guardrail lets: an agent only titles them.
+    return anchored(await cut(input, agents, notes), netChanges(input.base, input.current));
 }
 /**
  * A conformance plan, every job of it testing a functional spec: a job that touches none - reqs or definitions alone -
@@ -393,8 +423,29 @@ async function cut(input, agents, notes) {
         ...list.map((group) => ({ title: group.title, specs: group.specs.map((number) => bySpec.get(number)), definitions: [], reqs: [] })),
     ];
     const conformance = input.track === "conformance";
+    // The conformance tests are grouped and their reqs placed by the harness: their agents are only asked for titles.
+    const planners = conformance ? undefined : agents;
+    /**
+     * Groups titled for what their pulses do, by the title agent: those no agent titled - the conformance tests', a
+     * grouping that fell back. When it fails, or its answer does not hold, they keep their first lines.
+     */
+    const titled = async (list) => {
+        if (agents?.title === undefined || list.length === 0)
+            return list;
+        const track = conformance ? "conformance" : "code";
+        reportStage(`planning the queue: a title for each of the ${list.length} pulse${list.length === 1 ? "" : "s"}`);
+        const toTitle = list.map((group, index) => ({ number: index + 1, specs: group.specs.map((number) => textOf(bySpec.get(number))) }));
+        const answer = (await agents.title(toTitle, (given) => titleProblems(toTitle, given), track).catch((error) => plannerFailed("title", error))) ?? undefined;
+        const problems = answer === undefined ? [] : titleProblems(toTitle, answer);
+        if (answer !== undefined && problems.length === 0)
+            return list.map((group, index) => ({ ...group, title: answer.titles.find((entry) => entry.group === index + 1).title.trim() }));
+        record({ kind: "planner.fellBack", step: "title", why: answer === undefined ? "no titles were given" : firstLine(problems.join(" "), 300) });
+        say(answer === undefined ? "the titles were not given - each pulse titled by its functional specs' first lines" : `the titles did not hold (${problems.join(" ")}) - each pulse titled by its functional specs' first lines`);
+        return list;
+    };
     const grouped = conformance ? undefined : ((await agents?.group(numbered, (answer) => groupProblems(numbered, answer, maxSpecs), input.steering, maxSpecs).catch((error) => plannerFailed("group", error))) ?? undefined);
-    const groups = conformance
+    const holds = grouped !== undefined && groupProblems(numbered, grouped, maxSpecs).length === 0;
+    const made = conformance
         ? conformanceGroups(numbered, input.separately === true, maxLines, (list) => {
             const trial = chunksFor(list);
             placeDefinitions(trial, definitions);
@@ -403,7 +454,7 @@ async function cut(input, agents, notes) {
             const frid = fridOf(bySpec.get(spec.number));
             return frid === undefined ? -1 : (input.groups ?? []).findIndex((group) => group.includes(frid));
         })
-        : grouped !== undefined && groupProblems(numbered, grouped, maxSpecs).length === 0
+        : grouped !== undefined && holds
             ? grouped.groups
             : numbered.map((spec, index) => ({ specs: [spec.number], title: titleOf(specs[index]) }));
     if (grouped?.notes !== undefined && grouped.notes.trim() !== "")
@@ -418,6 +469,8 @@ async function cut(input, agents, notes) {
             say(`the grouping did not hold (${groupProblems(numbered, grouped, maxSpecs).join(" ")}) - a functional spec a pulse`);
         }
     }
+    // Titled before the chunks are made of them: a group split for its size keeps its title, numbered.
+    const groups = holds ? made : await titled(made);
     let chunks = chunksFor(groups);
     // 2. The definitions each group uses.
     placeDefinitions(chunks, definitions);
@@ -434,13 +487,13 @@ async function cut(input, agents, notes) {
             implementationReqs: implementationReqs.map((change, index) => ({ number: index + 1, text: textOf(change) })),
             testReqs: testReqs.map((change, index) => ({ number: index + 1, text: textOf(change) })),
         };
-        const answer = (await agents?.place(placeInput, (given) => placeProblems(placeInput, given)).catch((error) => plannerFailed("place", error))) ?? undefined;
+        const answer = (await planners?.place(placeInput, (given) => placeProblems(placeInput, given)).catch((error) => plannerFailed("place", error))) ?? undefined;
         if (answer?.notes !== undefined && answer.notes.trim() !== "")
             say(`the placement: ${answer.notes.trim()}`);
         placement = answer !== undefined && placeProblems(placeInput, answer).length === 0 ? answer : undefined;
-        if (placement === undefined && agents !== undefined)
+        if (placement === undefined && planners !== undefined)
             record({ kind: "planner.fellBack", step: "place", why: answer === undefined ? "no placement was given" : firstLine(placeProblems(placeInput, answer).join(" "), 300) });
-        if (placement === undefined && agents !== undefined)
+        if (placement === undefined && planners !== undefined)
             say("the placement did not hold - every implementation req with the first pulse, every test req with the first conformance pulse");
     }
     /** A req's chunk: its group, the built job, or the first job of the new work for "all". */
@@ -489,7 +542,7 @@ async function cut(input, agents, notes) {
             say(`"${group.title}" is past ${maxLines} lines with its definitions and reqs - split into ${runs.length} pulses`);
             runs.forEach((specs, index) => split.push({
                 specs,
-                title: specs.length === 1 ? titleOf(bySpec.get(specs[0])) : `${shortTitle(group.title, TITLE_CHARS - 9, TITLE_WORDS - 3)} (${index + 1} of ${runs.length})`,
+                title: `${shortTitle(group.title, TITLE_CHARS - 9, TITLE_WORDS - 3)} (${index + 1} of ${runs.length})`,
             }));
         });
         const before = placement;
@@ -517,7 +570,7 @@ async function cut(input, agents, notes) {
     // It does not hold together: a functional spec a job, every req with the first.
     say(`the plan did not hold together (${checkDraft(input, draft)[0]?.slice(0, 120)}) - a functional spec a pulse`);
     placement = undefined;
-    groups.splice(0, groups.length, ...numbered.map((spec, index) => ({ specs: [spec.number], title: titleOf(specs[index]) })));
+    groups.splice(0, groups.length, ...(await titled(numbered.map((spec, index) => ({ specs: [spec.number], title: titleOf(specs[index]) })))));
     chunks = chunksFor(groups);
     place();
     const simple = draftOf(chunks, net);
@@ -586,6 +639,22 @@ export function placePrompt(input) {
         "Call submit_placement once, with every one of them placed once.",
     ].join("\n");
 }
+export function titlePrompt(groups, track) {
+    return [
+        track === "conformance"
+            ? "You title the pulses that test a codebase. Each group below is a pulse: it writes and runs the conformance tests for its functional specs - black-box tests of the code as built."
+            : "You title the pulses that build a codebase. Each group below is a pulse: a coding agent builds its functional specs into the code.",
+        "",
+        track === "conformance"
+            ? "Give each group a title that says what its pulse tests - the behaviour, not the spec's wording."
+            : "Give each group a title that says what its pulse builds - the feature, not the spec's wording.",
+        `At most ${TITLE_WORDS} words and ${TITLE_CHARS} characters: it heads the pulse where the person watches the work, and a longer one is cut short there.`,
+        "",
+        ...groups.map((group) => [`<group number="${group.number}">`, ...group.specs.map((spec) => `<functional spec>\n${spec.trim()}\n</functional spec>`), "</group>"].join("\n")),
+        "",
+        "Call submit_titles once, with a title for every group, by its number.",
+    ].join("\n");
+}
 const TargetSchema = Type.Union([Type.Number(), Type.Literal("all"), Type.Literal("built")]);
 const NOTES = "Each of the person's wishes for how the queue is planned that you did not follow, and why - a limit it would break, say. Leave it out when you followed them all, or there are none.";
 /** Ask one step of an agent, and ask again with what was wrong, until it holds or the retries are spent. */
@@ -608,7 +677,7 @@ async function askStep(options) {
         session.dispose();
     }
 }
-/** The chunking's two agents, on a model - fresh for every plan. */
+/** The chunking's agents, on a model - fresh for every plan. */
 export function llmChunkAgents(options) {
     const label = options.label ?? "queue planner";
     return {
@@ -654,5 +723,27 @@ export function llmChunkAgents(options) {
                 },
             }),
         }),
+        title: (groups, check, track) => askStep({
+            cwd: options.cwd,
+            model: options.model,
+            label: `${label} titles`,
+            task: titlePrompt(groups, track),
+            check,
+            tool: (take) => defineTool({
+                name: "submit_titles",
+                label: "Submit the titles",
+                description: `A title for every group, by its number: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters each.`,
+                parameters: Type.Object({
+                    titles: Type.Array(Type.Object({
+                        group: Type.Number(),
+                        title: Type.String({ description: `What the group's pulse ${track === "conformance" ? "tests" : "builds"}: at most ${TITLE_WORDS} words and ${TITLE_CHARS} characters.` }),
+                    })),
+                }),
+                async execute(_id, params) {
+                    take(params);
+                    return { content: [{ type: "text", text: "Recorded." }], details: {}, terminate: true };
+                },
+            }),
+        }),
     };
 }

package/dist/regenerate/ledger.d.ts

@@ -88,11 +88,11 @@ export type LedgerEvent = {
     why: string;
 } | {
     kind: "planner.failed";
-    step: "group" | "place";
+    step: "group" | "place" | "title";
     error: string;
 } | {
     kind: "planner.fellBack";
-    step: "group" | "place";
+    step: "group" | "place" | "title";
     why: string;
 } | {
     kind: "model.call";

package/docs/regenerating.md

@@ -174,7 +174,9 @@ A job that renders the whole of a new spec is too big to build well, and a rende
 2. **The definitions each group uses**, in code: the concepts its functional specs name, and the concepts those definitions name in turn. A definition goes with the first group that uses it; later groups have it built. One nothing uses goes with the last.
 3. **Where each new implementation req goes.** An agent places each with the group it is about - or with the first, when it is about everything (the language, the framework).
 
-Changes to what is built - an item edited or taken out, a functional spec built worded differently - go first, in a job of their own. Every answer is checked: every new functional spec once, in order, next to each other, at most `max-specs-per-pulse`; every req placed once. One that does not hold goes back to its agent, twice at most, and then the plan is a functional spec a job with every req in the first. A group whose functional specs and the definitions they bring pass `max-lines-per-pulse` (120 unset) is split into as few pulses as fit - its functional specs kept together in runs, in order, as long as each run stays within it, `Comments (1 of 2)`, `Comments (2 of 2)` - not a functional spec a job; its reqs do not count, as a split leaves them with its first job whatever happens. The planner runs on the chat's model in a conversation, and on the harness model under `turri regenerate`. No agent reviews its plan: the harness checks it - every change in exactly one job, the spec holding together after each, the last ending on the spec as it is.
+Each pulse's title says what it does - at most 10 words and 70 characters, as it heads the pulse where the person watches the work. The grouping agent titles its groups; groups no agent made - the conformance tests', and a grouping that fell back - are titled by a third agent, told what each pulse does: what it builds, or, for the conformance tests, what they test. Without it, or when it fails, a pulse is titled by its functional specs' first lines, cut short.
+
+Changes to what is built - an item edited or taken out, a functional spec built worded differently - go first, in a job of their own. Every answer is checked: every new functional spec once, in order, next to each other, at most `max-specs-per-pulse`; every req placed once; every group titled once, within the limit. One that does not hold goes back to its agent, twice at most, and then the plan is a functional spec a job with every req in the first. A group whose functional specs and the definitions they bring pass `max-lines-per-pulse` (120 unset) is split into as few pulses as fit - its functional specs kept together in runs, in order, as long as each run stays within it, `Comments (1 of 2)`, `Comments (2 of 2)` - not a functional spec a job; its reqs do not count, as a split leaves them with its first job whatever happens. The planner runs on the chat's model in a conversation, and on the harness model under `turri regenerate`. No agent reviews its plan: the harness checks it - every change in exactly one job, the spec holding together after each, the last ending on the spec as it is.
 
 Each planned job knows its cases - which functional specs it adds, changes (their text, or a concept they use) and takes out, or none: reqs and definitions only - and the loop says them, with each job's title, where the person looks (`drift`, `pulses`, and what `regenerate` returns).
 
@@ -312,7 +314,7 @@ They follow the code: a functional spec gets conformance tests once its code is
 
 ### Conformance tests in the work loop
 
-In the work loop, conformance is a track beside the code's. What the conformance tests are written for is recorded apart - `tests/.turri.json`: the functional specs they test, as built, with their acceptance tests, the definitions and implementation reqs they were written against, and the test reqs they follow - and the work is from that record to what they are to be: of the functional specs the code is built from, those chosen - every one, or those `conform` names - as the spec has them, with its test reqs. A functional spec whose code is behind the spec - built from other text, or not in the code record at all, as while `regenerate` regenerates it again by name - keeps its tests until the code lands; they are taken out only once the spec and the code have both dropped it. The harness cuts the work into jobs, and no agent is asked: every functional spec tested - added or changed, asked for by `conform`, chosen, or left by the code jobs - is in one conformance job, a module's own together, as far as a guardrail lets: a new job begins only where the next functional spec would take the job's functional specs and the definitions they bring past 120 lines. The reqs they are written against go with the first job, and do not count. When the person asks for it - one at a time, separately - `conform`'s `one_by_one` (`turri conform --one-by-one`) makes it a job a functional spec instead, until conformance tests are asked for again without it. And when the person asks for them in pulses of their own grouping - 1-3 and 4-6 - `conform`'s `groups` gives each group a job of its own: a job never takes functional specs of two groups, and within a group the guardrail still cuts. Only work that touches no functional spec at all, the test reqs changed say, is a job without one. A module's conformance jobs run on its lane once its code is built - every code job of it landed - so the module is tested once, as built: one explorer, one run of the whole suite, rather than a conformance cycle after each code job; and they pass before anything is built on it. Until then they are not planned, but what is planned lists them last - `conformance tests - planned once the code is built` - wherever they are on for the whole module, so asking for them is seen to have worked; `conform` asked again for a module they are on for already says so, and changes nothing.
+In the work loop, conformance is a track beside the code's. What the conformance tests are written for is recorded apart - `tests/.turri.json`: the functional specs they test, as built, with their acceptance tests, the definitions and implementation reqs they were written against, and the test reqs they follow - and the work is from that record to what they are to be: of the functional specs the code is built from, those chosen - every one, or those `conform` names - as the spec has them, with its test reqs. A functional spec whose code is behind the spec - built from other text, or not in the code record at all, as while `regenerate` regenerates it again by name - keeps its tests until the code lands; they are taken out only once the spec and the code have both dropped it. The harness cuts the work into jobs - an agent only titles them: every functional spec tested - added or changed, asked for by `conform`, chosen, or left by the code jobs - is in one conformance job, a module's own together, as far as a guardrail lets: a new job begins only where the next functional spec would take the job's functional specs and the definitions they bring past 120 lines. The reqs they are written against go with the first job, and do not count. When the person asks for it - one at a time, separately - `conform`'s `one_by_one` (`turri conform --one-by-one`) makes it a job a functional spec instead, until conformance tests are asked for again without it. And when the person asks for them in pulses of their own grouping - 1-3 and 4-6 - `conform`'s `groups` gives each group a job of its own: a job never takes functional specs of two groups, and within a group the guardrail still cuts. Only work that touches no functional spec at all, the test reqs changed say, is a job without one. A module's conformance jobs run on its lane once its code is built - every code job of it landed - so the module is tested once, as built: one explorer, one run of the whole suite, rather than a conformance cycle after each code job; and they pass before anything is built on it. Until then they are not planned, but what is planned lists them last - `conformance tests - planned once the code is built` - wherever they are on for the whole module, so asking for them is seen to have worked; `conform` asked again for a module they are on for already says so, and changes nothing.
 
 A conformance job is a spec diff's conformance run: the tests of its change written, changed or taken out, a failure judged - the test or the code wrong - and fixed, then the whole suite with the unit tests, the tests the module inherits with them. The run that passed already was of the whole suite - the module's tests folder holds the chain's, copied up - so the suite is run once more only when the code or the tests changed after it passed with the unit tests; otherwise it is not run again. Passing, the tests record is written and committed with the tests; otherwise all of it - code fixes included - is rolled back, and the module halts until the spec or the code changes, or `conform` asks again: its conformance tests, its code - nothing more is built on code whose conformance tests did not pass - and every module built on it, which waits.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "license": "MIT",
   "type": "module",
   "repository": {