@turri-dev/cli 0.1.16-next.b861614 → 0.1.16-next.ce2cd46

package/.pi/themes/turri-dark.json

@@ -33,7 +33,7 @@
     "searchMatchBg": "neon",
     "searchMatchText": "abyss",
     "userMessageBg": "",
-    "userMessageText": "white",
+    "userMessageText": "neon",
     "customMessageBg": "",
     "customMessageText": "grauzone",
     "customMessageLabel": "neon",

package/dist/extension.js

@@ -1995,7 +1995,8 @@ export const JOB_FINISHED_REACTION = [
     "someone), do that, as it says. Otherwise say in a line or two what finished and what it means for the person - the",
     "report is theirs to read in full; do not repeat it - and, when it failed, what they can do. Start no other work.",
     "A report that says \"Released after the pulse\" was released by turri itself, as the pulse's last stage: do not call",
-    "release for it - say in a line what was released, or why nothing was.",
+    "release for it. Say in a line what was released, or why nothing was - then, when it was released, do what you were",
+    "told to do once something is released (opening it where the person can watch it, saying what to test), if anything.",
     "A pulse that stopped on its environment - \"stopped: turri's sandbox kept its agents from…\" or \"stopped: the",
     "environment lacks…\" - stops the same way again until that is fixed: never regenerate it before. Heal it, then regenerate the",
     "module to resume:",

package/dist/init-config.d.ts

@@ -112,7 +112,7 @@ export declare const DEFAULTS: {
     readonly review: false;
     readonly mutationTesting: true;
     readonly allowToStopJobs: true;
-    readonly releaseAfterPulse: false;
+    readonly releaseAfterPulse: true;
     readonly testingScriptsRunOn: "in-place";
     readonly turnLimit: 120;
     readonly compactAt: 100000;

package/dist/init-config.js

@@ -219,7 +219,7 @@ export const DEFAULTS = {
     review: false,
     mutationTesting: true,
     allowToStopJobs: true,
-    releaseAfterPulse: false,
+    releaseAfterPulse: true,
     testingScriptsRunOn: "in-place",
     turnLimit: 120,
     compactAt: 100000,

package/dist/loop-tools.js

@@ -165,7 +165,7 @@ export function regenerateTool(options) {
             "editor. It takes no diff: what is left to regenerate - from what each module's code was regenerated from to its spec now - is " +
             "worked out and planned into pulses, and a pulse running that regenerates something the spec no longer wants is stopped and " +
             "rolled back. Nothing to do where the code is regenerated from the spec as it is. With functionalities named, those are " +
-            "regenerated though their spec did not change - rewritten or started over, better made, what they replace taken out - " +
+            "regenerated though their spec did not change - their code taken out and built anew, better made, never left as it was - " +
             "planned into pulses as any change is, the ones next to each other together; their conformance tests stay as they are.",
         promptSnippet: "regenerate a module's code from its spec as it is now - after any change to the spec",
         promptGuidelines: [

package/dist/regenerate/cases.js

@@ -19,7 +19,7 @@ export function codeCasesBlock(cases) {
         lines.push(`- Changed - its text, or a concept it uses: ${named(cases.patch)}.`, "  Its code and unit tests exist: change them to match what it says now. Do not build it again from scratch.");
     }
     if (cases.again.length > 0) {
-        lines.push(`- Regenerated again - its code and unit tests are built, and are to be regenerated again: ${named(cases.again)}.`, "  Replace its implementation: rewrite it, or take it out and build it anew - made better, and doing exactly what", "  the specification says now. Take out what the new code replaces: no second implementation beside the old one,", "  nothing of the old left unused. What the rest of the code uses from it keeps working. Its unit tests may be", "  rewritten, to test what the specification says.");
+        lines.push(`- Regenerated again - its code and unit tests are built, and are to be regenerated again: ${named(cases.again)}.`, "  Take its implementation out and build it anew from the specification - made better, and doing exactly what", "  the specification says now. Its text being unchanged, or the old code already doing what it says, is no reason", "  to keep it: the person asked for it to be built again, and work that leaves it as it was has not done that.", "  Take out what the new code replaces: no second implementation beside the old one, nothing of the old left", "  unused. What the rest of the code uses from it keeps working. Write its unit tests anew too, to test what the", "  specification says.");
     }
     if (cases.delete.length > 0) {
         lines.push(`- Taken out - remove its code, and the unit tests only it had, where nothing that remains needs them: ${named(cases.delete)}.`);
@@ -45,7 +45,7 @@ export function codeReviewCasesBlock(cases) {
         ...(cases.patch.length > 0 ? [`- Changed: ${named(cases.patch)} - the code and its tests changed to match it now, not left as they were.`] : []),
         ...(cases.again.length > 0
             ? [
-                `- Regenerated again: ${named(cases.again)} - its implementation replaced, not patched beside the old one: nothing of what it`,
+                `- Regenerated again: ${named(cases.again)} - its implementation built anew, not kept or patched beside the old one: nothing of what it`,
                 "  replaced left behind or duplicated, it does what the specification says, what the rest of the code uses from it",
                 "  still works, and its unit tests test the specification.",
             ]

package/dist/regenerate/change-view.js

@@ -1,4 +1,4 @@
-import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS } from "../plain/spec.js";
+import { ACCEPTANCE_TESTS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, TEST_REQUIREMENTS } from "../plain/spec.js";
 import { resourceDiff } from "./spec-steps.js";
 /**
  * A job's change as its agent is given it, for the panels: the same items `describeSpecChange` writes into
@@ -10,7 +10,9 @@ import { resourceDiff } from "./spec-steps.js";
  * things - the lines around a change, the items no job takes yet - and leave out what an import adds.
  */
 /** The sections in the order the agent is given them, then any other. */
-const ORDER = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, FUNCTIONAL_REQUIREMENTS];
+const ORDER = [DEFINITIONS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, REQUIRED_FUNCTIONAL_SPECS, FUNCTIONAL_REQUIREMENTS];
+/** A section's header as a .plain file writes it: a required module's functional specs are under its own `***functional specs***`. */
+const heading = (section) => `***${section === REQUIRED_FUNCTIONAL_SPECS ? FUNCTIONAL_REQUIREMENTS : section}***`;
 /** An item's lines as a .plain file writes them: its markdown, then its acceptance tests indented under it. */
 function itemLines(serialized) {
     if (serialized === undefined)
@@ -92,7 +94,7 @@ function laidOut(changes, file, asGiven = false) {
         }
         if (body.length === 0)
             continue;
-        lines.push("@@ @@", ` ***${section}***`, ...body);
+        lines.push("@@ @@", ` ${heading(section)}`, ...body);
     }
     return { diff: `${lines.join("\n")}\n${resourceDiff(changes, file)}`, starts };
 }

package/dist/regenerate/conform.js

@@ -124,9 +124,7 @@ export function describeSpecDiffConformance(result) {
             : "",
         ...specGapsText(result.specGaps),
         "",
-        "<agent report>",
         result.conformance.response,
-        "</agent report>",
     ]
         .filter((line) => line !== "")
         .join("\n");

package/dist/regenerate/delivery.d.ts

@@ -1,6 +1,2 @@
-/** What every job that lands code ends with: the person can try it now, by asking. */
-export declare const TRY_IT_LINE = "Want to try it? Just ask me - I'll set it up from what's built so far.";
-/** The same for a command-line run, which has no one to ask: the command that does it. */
+/** A command-line run has no one to ask: the command that releases what it built. */
 export declare function tryItCommand(plainFile: string): string;
-/** A job's report, ending with how to try what it built when it landed. */
-export declare function withTryItLine(report: string, landed: boolean): string;

package/dist/regenerate/delivery.js

@@ -1,19 +1,12 @@
 import { relative } from "node:path";
 /**
- * How a job that lands code ends: the person can try what is built, by asking - `deploy` sets it up
- * from what is built.
+ * How a command-line run that landed code ends: the command that releases it to try.
  */
 function shortPath(buildDir) {
     const fromHere = relative(process.cwd(), buildDir);
     return fromHere === "" || fromHere.startsWith("..") ? buildDir : fromHere;
 }
-/** What every job that lands code ends with: the person can try it now, by asking. */
-export const TRY_IT_LINE = "Want to try it? Just ask me - I'll set it up from what's built so far.";
-/** The same for a command-line run, which has no one to ask: the command that does it. */
+/** A command-line run has no one to ask: the command that releases what it built. */
 export function tryItCommand(plainFile) {
     return `To try it: turri release ${shortPath(plainFile)}`;
 }
-/** A job's report, ending with how to try what it built when it landed. */
-export function withTryItLine(report, landed) {
-    return landed ? `${report}\n\n${TRY_IT_LINE}` : report;
-}

package/dist/regenerate/loop.js

@@ -18,7 +18,6 @@ import { budgetFor, choosingWhen, configForSpec, conformanceSwitchedOn, stackFor
 import { describeSpecChange } from "./prompt.js";
 import { resolveTemplateDirs } from "./paths.js";
 import { builtTips, copyRequiredCode, importingModules, isImportModule, newlyRequired, resolveRequiresChain, startFromScratch } from "./requires.js";
-import { withTryItLine } from "./delivery.js";
 import { describeSpecDiff, renderSpecDiff, specFilesOf } from "./regenerate.js";
 import { locateDiffLines } from "./diff-view.js";
 import { agentChanges, changeDiffInFiles } from "./change-view.js";
@@ -1644,7 +1643,7 @@ const defaultRunner = async (job, onDelta) => {
         onDelta,
     });
     // Landed code can be tried.
-    return { landed: result.passed, report: withTryItLine(describeSpecDiff(result), result.passed && result.restructured !== true), story: codeStory(result),
+    return { landed: result.passed, report: describeSpecDiff(result), story: codeStory(result),
         ...(result.specGaps !== undefined ? { specGaps: result.specGaps } : {}),
     };
 };

package/dist/regenerate/regenerate.js

@@ -36,7 +36,7 @@ import { inheritedRecord, readRecord, withResourceDigests, writeCodeRecord } fro
 import { changesBetween, sameSpec, serializeTree } from "./spec-steps.js";
 import { untilUnitTestsReviewed } from "./unit-review.js";
 import { configForSpec, inheritModel, modelOnly, modelSpec } from "../config.js";
-import { findTestRemovals, inventoryTests, listFiles, removalChallengePrompt, draftPrompt, DRAFT_ASKS, } from "./testing.js";
+import { findTestRemovals, inventoryTests, listFiles, removalChallengePrompt, AGAIN_ASKS, againPrompt, draftPrompt, DRAFT_ASKS, } from "./testing.js";
 /**
  * Render a change to the specs, given as a git diff of the .plain files.
  *
@@ -335,6 +335,10 @@ export async function renderSpecDiff(options) {
     let attempts = 0;
     /** How many times the agent, having written nothing, was asked for a draft. */
     let draftAsks = 0;
+    /** The functional specs this job regenerates again: their code is to be built anew, never left as it was. */
+    const again = options.cases?.again ?? [];
+    /** Regenerating again, the agent wrote nothing however it was asked. */
+    let unchanged = false;
     /** What the unit testing script needs and does not find, last run. */
     let missing;
     /** The unit testing script needs more time than a test run may take - the debugger's finding: the pulse stops on it. */
@@ -398,6 +402,19 @@ export async function renderSpecDiff(options) {
                     response = await ask(executor, misplacedTestsPrompt(misplaced, buildDir), options.onDelta);
                     continue;
                 }
+                // Regenerating functional specs again, nothing written is never the answer: sent back to build them anew, and
+                // still nothing, the work does not land.
+                if (again.length > 0 && wroteNothing(buildDir, digestsBefore)) {
+                    if (draftAsks >= AGAIN_ASKS) {
+                        unchanged = true;
+                        stage("the coding agent regenerated nothing again - undoing the change");
+                        return false;
+                    }
+                    draftAsks += 1;
+                    stage("the coding agent has changed nothing yet - sending it back to build what it regenerates again anew");
+                    response = await ask(executor, againPrompt(again), options.onDelta);
+                    continue;
+                }
                 // Nothing written - a turn spent planning - leaves nothing to test or review: ask for a best-guess draft, or why none.
                 if (draftAsks < DRAFT_ASKS && wroteNothing(buildDir, digestsBefore)) {
                     draftAsks += 1;
@@ -559,14 +576,17 @@ export async function renderSpecDiff(options) {
         landWork(buildDir, `spec diff: ${summarizeDiff(options.diff)}`, options.diff);
     };
     if (!unitPassed) {
-        stage(unitReviewStopped ? "the unit tests pass but still leave the change untested - undoing the change" : "unit tests NOT passing - undoing the change");
+        if (!unchanged)
+            stage(unitReviewStopped ? "the unit tests pass but still leave the change untested - undoing the change" : "unit tests NOT passing - undoing the change");
         abandonWork(unit, moduleName, missing !== undefined
             ? "the unit testing script could not run"
-            : slow !== undefined
-                ? "the unit testing script needs more time than a test run may take"
-                : staticOnly
-                    ? "the spec change did not pass its static checks"
-                    : "the spec change did not pass its unit tests");
+            : unchanged
+                ? "regenerating again, the coding agent built nothing anew"
+                : slow !== undefined
+                    ? "the unit testing script needs more time than a test run may take"
+                    : staticOnly
+                        ? "the spec change did not pass its static checks"
+                        : "the spec change did not pass its unit tests");
         // The environment lacks what the testing script needs: the pulse stops, rolled back, and the person is told.
         if (missing !== undefined) {
             throw toolchainError(missing, { moduleName, script: scripts.unit, kind: "unit" });
@@ -614,9 +634,7 @@ export function describeSpecDiff(result) {
         ...(result.steered !== undefined ? [`Steered while it ran - the spec changed inside what it was regenerating, and its agent was told: ${result.steered.join("; ")}.`] : []),
         ...specGapsText(result.specGaps),
         "",
-        "<agent report>",
         result.response,
-        "</agent report>",
     ]
         .filter((line) => line !== "")
         .join("\n");

package/dist/regenerate/release.d.ts

@@ -105,13 +105,8 @@ export interface StartResult {
     process?: DeployedProcess;
 }
 /**
- * Start something that keeps running - a server, a frontend's dev server - in `dir`, on this machine,
- * in its own process group, its output to a log. One already running under the name is stopped first.
- *
- * With a URL, it is ready once something answers there - any answer - and not when it exits first or
- * nothing answers in time. A port something else holds already is said, with what holds it, and
- * nothing is started: an app moved to a port of the harness's choosing would not be the one the
- * person was told about. With no URL, it only has to still be running a few seconds on.
+ * Start what keeps running, in `dir` - the deployed folder `root`, or one inside it. A folder that is not there starts
+ * nothing: said, with what the deployed folder holds, so the agent can name the right one.
  */
 export declare function startDeployed(input: {
     name: string;
@@ -120,4 +115,5 @@ export declare function startDeployed(input: {
     moduleName: string;
     logDir: string;
     url?: string;
+    root?: string;
 }): Promise<StartResult>;

package/dist/regenerate/release.js

@@ -1,5 +1,5 @@
 import { spawn, spawnSync } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { connect } from "node:net";
 import { dirname, join, relative } from "node:path";
 import { HISTORY_DIR } from "./lineage.js";
@@ -206,7 +206,39 @@ const ALIVE_AFTER_MS = 4000;
  * nothing is started: an app moved to a port of the harness's choosing would not be the one the
  * person was told about. With no URL, it only has to still be running a few seconds on.
  */
+/** A folder's entries as a listing says them - folders with a slash - or that it is empty. */
+function listing(dir) {
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true }).map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name)).sort();
+        if (entries.length === 0)
+            return "nothing";
+        return entries.length > 40 ? `${entries.slice(0, 40).join(", ")} and ${entries.length - 40} more` : entries.join(", ");
+    }
+    catch {
+        return "nothing turri can read";
+    }
+}
+/**
+ * Start what keeps running, in `dir` - the deployed folder `root`, or one inside it. A folder that is not there starts
+ * nothing: said, with what the deployed folder holds, so the agent can name the right one.
+ */
 export async function startDeployed(input) {
+    let isFolder = false;
+    try {
+        isFolder = statSync(input.dir).isDirectory();
+    }
+    catch {
+        /* not there */
+    }
+    if (!isFolder) {
+        const why = existsSync(input.dir) ? "is not a folder" : "does not exist";
+        return {
+            ok: false,
+            text: input.root !== undefined
+                ? `${input.name} was not started: ${shortPath(input.dir)} ${why}. \`dir\` is relative to the deployed folder, ${shortPath(input.root)} - a folder inside it, e.g. frontend, or none for the deployed folder itself; never the project's path to it. ${shortPath(input.root)} holds: ${listing(input.root)}.`
+                : `${input.name} was not started: ${shortPath(input.dir)} ${why}.`,
+        };
+    }
     await stopDeployed({ name: input.name });
     let url;
     if (input.url !== undefined) {
@@ -229,35 +261,47 @@ export async function startDeployed(input) {
     const log = join(input.logDir, `${input.moduleName}-${input.name.replace(/[^\w.-]+/g, "-")}.log`);
     const fd = openSync(log, "w");
     const child = spawn("bash", ["-c", input.command], { cwd: input.dir, detached: true, stdio: ["ignore", fd, fd], env: process.env });
+    // Listened to at once: a child's 'error' with no listener is thrown, and takes the whole process down with it.
+    let info;
+    let spawnError;
+    const spawned = new Promise((done) => {
+        child.once("spawn", () => done());
+        child.once("error", () => done());
+    });
+    child.on("error", (error) => {
+        spawnError ??= error;
+        if (info !== undefined)
+            info.exited ??= { code: null, signal: null };
+    });
     closeSync(fd);
-    if (child.pid === undefined)
-        return { ok: false, text: `${input.name} could not be started.` };
-    const info = { name: input.name, moduleName: input.moduleName, command: input.command, dir: input.dir, log, pid: child.pid, startedAt: Date.now(), ...(input.url !== undefined ? { url: input.url } : {}) };
+    if (child.pid === undefined) {
+        await spawned;
+        return { ok: false, text: `${input.name} could not be started in ${shortPath(input.dir)}: ${spawnError?.message ?? "no process was made"}.` };
+    }
+    const started = { name: input.name, moduleName: input.moduleName, command: input.command, dir: input.dir, log, pid: child.pid, startedAt: Date.now(), ...(input.url !== undefined ? { url: input.url } : {}) };
+    info = started;
     child.on("exit", (code, signal) => {
-        info.exited = { code, signal };
-    });
-    child.on("error", () => {
-        info.exited ??= { code: null, signal: null };
+        started.exited = { code, signal };
     });
-    processes.set(input.name, { info, child });
+    processes.set(input.name, { info: started, child });
     stopOnExit();
     const failed = (why) => {
         const tail = logTail(log);
-        return { ok: false, text: `${input.name} ${why}.${tail !== "" ? `\nThe end of its output (${shortPath(log)}):\n${tail}` : ""}`, process: info };
+        return { ok: false, text: `${input.name} ${why}.${tail !== "" ? `\nThe end of its output (${shortPath(log)}):\n${tail}` : ""}`, process: started };
     };
-    const ended = () => `exited${info.exited?.code !== null && info.exited?.code !== undefined ? ` with ${info.exited.code}` : ""} before it was ready`;
+    const ended = () => `exited${started.exited?.code !== null && started.exited?.code !== undefined ? ` with ${started.exited.code}` : ""} before it was ready`;
     if (url === undefined) {
         await sleep(ALIVE_AFTER_MS);
-        if (info.exited !== undefined)
+        if (started.exited !== undefined)
             return failed(ended());
-        return { ok: true, text: `${input.name} is running (pid ${info.pid}); its output is in ${shortPath(log)}.`, process: info };
+        return { ok: true, text: `${input.name} is running (pid ${started.pid}); its output is in ${shortPath(log)}.`, process: started };
     }
     const deadline = Date.now() + READY_TIMEOUT_MS;
     while (Date.now() < deadline) {
-        if (info.exited !== undefined)
+        if (started.exited !== undefined)
             return failed(ended());
         if (await answers(url.href))
-            return { ok: true, text: `${input.name} is up at ${url.href} (pid ${info.pid}); its output is in ${shortPath(log)}.`, process: info };
+            return { ok: true, text: `${input.name} is up at ${url.href} (pid ${started.pid}); its output is in ${shortPath(log)}.`, process: started };
         await sleep(1000);
     }
     return failed(`is running, but nothing answered at ${url.href} in ${Math.round(READY_TIMEOUT_MS / 1000)}s`);

package/dist/regenerate/testing.d.ts

@@ -89,6 +89,13 @@ export declare function removalChallengePrompt(removals: TestRemoval[], subject:
 export declare const DRAFT_ASKS = 1;
 /** For a coding agent that has written nothing yet: write a best-guess draft now, or say why no code is needed. */
 export declare function draftPrompt(): string;
+/** How many times a coding agent regenerating functional specs again, having written nothing, is sent back to build them anew. */
+export declare const AGAIN_ASKS = 2;
+/** For a coding agent regenerating functional specs again that has written nothing: no change is no answer. */
+export declare function againPrompt(again: Array<{
+    frid: string;
+    module?: string;
+}>): string;
 export type UnitVerdict = {
     ok: true;
     command: string;

package/dist/regenerate/testing.js

@@ -313,6 +313,20 @@ export function draftPrompt() {
         "with update_notes. Then run the unit tests.",
     ].join("\n");
 }
+/** How many times a coding agent regenerating functional specs again, having written nothing, is sent back to build them anew. */
+export const AGAIN_ASKS = 2;
+/** For a coding agent regenerating functional specs again that has written nothing: no change is no answer. */
+export function againPrompt(again) {
+    const named = again.map((spec) => `fs ${spec.frid}${spec.module !== undefined ? ` of module \`${spec.module}\`` : ""}`).join(", ");
+    return [
+        "You have not written anything yet: the code folder is as it was when you started.",
+        "",
+        `${named} ${again.length === 1 ? "is" : "are"} to be regenerated again: the person asked for ${again.length === 1 ? "its" : "their"} code to be built anew. That the`,
+        "text did not change, or that the old code already does what it says, is no reason to leave it: take its",
+        "implementation and its unit tests out and build them anew from the specification, then run the unit tests.",
+        "Work that changes nothing does not land.",
+    ].join("\n");
+}
 /**
  * The harness's own run of the unit tests, which is what "the tests pass" rests on.
  *

package/dist/regenerate-cli.js

@@ -8,7 +8,7 @@ the chat does: what is left to regenerate - from what each module's code was reg
 spec now - is planned into jobs, and they run one after the other until the code is regenerated from
 the spec, each followed by the conformance tests of what it regenerated when they are on. Then it says
 how each went. With functional specs named, those are regenerated though their spec did not change - as regenerate
-does in the chat with functionalities named: their code rewritten or started over, doing what the spec says.
+does in the chat with functionalities named: their code taken out and built anew, doing what the spec says.
 
 The project's config.turri.yaml, in the current directory, gives the defaults: module (the file to
 build when none is given), coding-model (the agents that build), harness-model (the planner), and

package/dist/release-agent.d.ts

@@ -15,7 +15,7 @@ export interface ReleaseAgentInput {
     inModule?: string;
     /** What the person said of how to release it. */
     guidance?: string;
-    /** Released as a pulse's last stage: what the pulse landed. The agent releases only when the guidance says to. */
+    /** Released as a pulse's last stage: what the pulse landed. The setting has said to release it; the guidance says how. */
     afterPulse?: {
         moduleName: string;
         subject: string;

package/dist/release-agent.js

@@ -84,7 +84,7 @@ export async function runReleaseAgent(input) {
         ].join("\n"),
         task: [
             input.afterPulse !== undefined
-                ? `A pulse of module ${input.afterPulse.moduleName} just landed: ${input.afterPulse.subject}. You release it now, before the module's next pulse starts - if the project's release guidance says to release after a build or a pulse.`
+                ? `A pulse of module ${input.afterPulse.moduleName} just landed: ${input.afterPulse.subject}. Release it now, before the module's next pulse starts: the project releases after every pulse.`
                 : `Release ${shortPath(plainFile)} for the person to try, with the release tool, then do what it says.`,
             "",
             "First ask yourself: is there guidance for how this project releases it - what the person said below, the project's",
@@ -94,8 +94,8 @@ export async function runReleaseAgent(input) {
             ...(input.afterPulse !== undefined
                 ? [
                     "",
-                    "Released after a pulse: when nothing in the guidance says to release after a build, call nothing and say so in a line.",
-                    "When release says it is already released, leave it at that.",
+                    "Release it whether or not the guidance speaks of releasing after a build - the project's setting has said to. What",
+                    "the guidance says is how. When release says it is already released, leave it at that.",
                 ]
                 : []),
             ...(input.inModule !== undefined ? ["", `Release the codebase of module ${input.inModule}: pass in_module.`] : []),

package/dist/release-tools.js

@@ -126,7 +126,7 @@ export function createDeployTools(options) {
             name: Type.String({ description: "A short name for it: backend, frontend, app" }),
             command: Type.String({ description: "The command that starts it, as run from its folder" }),
             url: Type.Optional(Type.String({ description: "Where it serves, e.g. http://localhost:5173 - it is ready once this answers" })),
-            dir: Type.Optional(Type.String({ description: "A folder inside the deployed one to run it in, e.g. frontend. Default: the deployed folder." })),
+            dir: Type.Optional(Type.String({ description: "The folder to run it in, relative to the deployed folder - e.g. frontend - never the project's path to the deployed folder (dist/<module>). Default: the deployed folder itself." })),
         }),
         async execute(_id, params) {
             const current = needsDeploy();
@@ -134,6 +134,7 @@ export function createDeployTools(options) {
                 name: params.name,
                 command: params.command,
                 dir: inside(current, params.dir),
+                root: current.hostDir ?? current.dir,
                 moduleName: current.moduleName,
                 logDir: deployLogDir(projectDirOf(current.plainFile)),
                 ...(params.url !== undefined ? { url: params.url } : {}),

package/dist/skill-progress.d.ts

@@ -11,7 +11,7 @@
  *
  * A skill of one phase, or none, has nothing to be partway through: its line is the spinner and its name alone.
  *
- *   ⠋ add-test-requirement
+ *   ⠋ analyze-func-specs
  */
 export interface SkillProgress {
     /** The skill's name. */

package/docs/authoring-plain.md

@@ -100,7 +100,7 @@ A requirement beyond the stack - storage, an outside service - is added on top o
 | --- | --- |
 | `module-structure.md` | the file skeleton, frontmatter fields, section order, module kinds, section ownership |
 | `definitions.md` | concept syntax, predefined concepts, define before use, no circular definitions, granularity |
-| `func-specs.md` | voice, the complexity limit, chronological order, no conflicts, language agnosticism, testability, acceptance tests |
+| `func-specs.md` | voice, the complexity limit, chronological order, no conflicts, how a functional spec is added - checked for size and conflicts before it is written in - and where it goes, language agnosticism, testability, acceptance tests |
 | `impl-reqs.md` | HOW not WHAT, unit tests live here, what belongs and what does not |
 | `test-reqs.md` | conformance tests only, what belongs, test types |
 | `concise-specs.md` (+ two example banks) | keeping \*\*\*plain short enough for a person to review: no obvious lines, plain words, no uncheckable adjectives, no hedging |
@@ -147,7 +147,7 @@ Every skill in `genome/skills/` can be run from a conversation; most are also us
 | --- | --- |
 | start a project | `brood`, `spawn` - or ask, and choose `Just do it` for no skill |
 | make rough \*\*\*plain build | `mature` |
-| add to \*\*\*plain | `bud`, `add-functional-spec`, `add-functional-specs`, `add-concept`, `add-implementation-requirement`, `add-test-requirement`, `add-acceptance-test`, `add-resource`, `add-template` |
+| add to \*\*\*plain | `bud` - or ask in the conversation: it writes a concept, a functional spec, a req, an acceptance test or a linked resource itself, by the rules in its prompt, as a \*\*\*plain diff |
 | check what is written | `analyze-if-func-spec-too-complex`, `analyze-2-func-specs`, `analyze-func-specs`, `resolve-section-ownership` |
 | fix what is written | `break-down-func-spec`, `resolve-spec-conflict`, `debug-specs` |
 | restructure modules | `refactor-module`, `consolidate-concepts` |

package/docs/config.md

@@ -89,7 +89,7 @@ models:                              # each agent role's model, thinking and tur
 | `mutation-testing` | `true` or `false`: whether the coding agent and the reviewer have `can_it_fail` - one change put in the code for one run of the unit testing script, to see that a test catches it; on a copy of the code, or in place and put back after the run (see [regenerating the code](regenerating.md#checking-its-own-work)). `turri regenerate --mutation-testing false` for one run | `true` |
 | `rules-off` | a list of rule names - `integrations`, `concise-specs`, the files of `genome/rules/` without `.md` - left out of the conversation's prompt and every \*\*\*plain-writing agent's: a rule this project's own skills or AGENTS.md replace, such as one that says to probe a live API before any \*\*\*plain is written. `turri init-config` writes it with `integration-embedded`, `integration-embedded-testing` and `integration-standalone` - take them out when the project writes an integration against a REST API. The project's alone | none |
 | `allow-to-stop-jobs` | `true` or `false`: whether turri stops a running job \*\*\*plain has moved on from - a functional spec it regenerates changed, or a file one links was edited - rolls it back and regenerates \*\*\*plain as it now is. `false`: the job runs to its end and lands, and what changed since is regenerated on top of it by the next job - see [regenerating the code](regenerating.md). Your own `halt` stops a job either way | `true` |
-| `release-after-pulse` | `true` or `false`: whether every pulse that lands code releases it, in the chat, as its last stage - before the module's next pulse starts, whatever the chat is doing: an agent on the coding model looks for the project's release guidance as the chat does (what was passed to `release` this conversation, AGENTS.md, the project's skills) and, when it says to release after a build, does what it says - see [deploy](deploy.md#after-every-pulse). One release a pulse that lands; a release that fails is said in the pulse's report, and what it landed stays | `false` |
+| `release-after-pulse` | `true` or `false`: whether every pulse that lands code releases it, in the chat, as its last stage - before the module's next pulse starts, whatever the chat is doing: an agent on the coding model releases it, following the project's release guidance as the chat finds it (what was passed to `release` this conversation, AGENTS.md, the project's skills) for how, or to `dist/<module>` without any - see [deploy](deploy.md#after-every-pulse). One release a pulse that lands; a release that fails is said in the pulse's report, and what it landed stays. `turri init-config` writes `true` | `false` |
 | `unittests-script` | the unit testing script, by path from the project root - it runs the code's static checks too, exiting 80 when only they fail (see [the static checks](regenerating.md#the-static-checks)) | looked for - see below |
 | `conformance-tests-script` | the conformance testing script, by path from the project root | looked for - see below |
 | `prepare-environment-script` | optional: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |

package/docs/deploy.md

@@ -2,13 +2,11 @@
 
 Ask to try it - "let me try it", "run the app" - at any time, even while a regeneration is running. The chat calls `deploy`: it puts the module's code, as it was last built, in `dist/<module>` in the project, and starts it on your machine. An app with a backend and a frontend is started whole, and you are told where to open your browser. For a command-line tool or a library you get a few commands to paste, run from `dist/<module>`, and what they print.
 
-Every pulse that lands code - a regeneration, a \*\*\*plain diff, a conformance run, a functionality regenerated - ends with "Want to try it? Just ask me - I'll set it up from what's built so far." When a regeneration's conformance tests follow as a pulse of their own, the conformance pulse says it, once they pass too.
-
 ## When the project says how it is released
 
 Every release starts the same way: the module's last commit - what last landed whole - goes in `dist/<module>`, as below. Not everything is tried from there, though. An integration that a host application loads goes on into the host's own tree, with the host's own scripts, and then the host is started. So the model asks itself whether there is guidance for how this project is released - in what you said, the project's AGENTS.md, a skill, anything it was given - and passes it to `release` whole:
 
-- **There is guidance.** The code goes on from `dist/<module>` as the guidance says, on your machine, from the host codebase - the git repository the project is in, or else where **turri** runs: the scripts it names, in their order, and any change it says the host needs. The code is taken from `dist`, never from `plain_modules`, where a pulse may be writing; where the host's tooling reads `plain_modules` itself, the model points it at `dist`, or does by hand from `dist` what it does. When to release - after every pulse, say - is the guidance's to say too. The rules below hold as they do for `dist`: the model runs the project's scripts and installs what they need itself, and what keeps running - a start script, a server - is started with `activate`. Nothing built is changed.
+- **There is guidance.** The code goes on from `dist/<module>` as the guidance says, on your machine, from the host codebase - the git repository the project is in, or else where **turri** runs: the scripts it names, in their order, and any change it says the host needs. The code is taken from `dist`, never from `plain_modules`, where a pulse may be writing; where the host's tooling reads `plain_modules` itself, the model points it at `dist`, or does by hand from `dist` what it does. Whether to release after every pulse is `release-after-pulse`'s to say - see [after every pulse](#after-every-pulse). The rules below hold as they do for `dist`: the model runs the project's scripts and installs what they need itself, and what keeps running - a start script, a server - is started with `activate`. Nothing built is changed.
 - **There is none.** The default: it is started from `dist/<module>`, as below, as best it can be.
 
 Guidance is whatever says it, in any words - a line in AGENTS.md such as *integrations are released with `scripts/deploy_integrations.sh`, then the app is started with `scripts/start.sh`*, or the same said in the chat.
@@ -27,7 +25,7 @@ It runs on your machine, outside the [sandbox](sandbox.md) - with your toolchain
 
 1. **Checks the toolchains** it needs (`node`, `python3`, `go`, ...). One is missing: it installs it with the machine's package manager (`brew` on macOS, `apt` or `dnf` on Linux).
 2. **Installs what it needs itself.** Dependencies into a virtual environment or `node_modules`, a build that downloads packages, an image pull, a guided release's project scripts: it runs them in its own shell, as any agent with a shell would, and fixes what fails. Nothing is put to you - there is no dialog to answer.
-3. **Starts what serves** with `activate`: in the background, in its own process group, its output in `.turri/deploy/<module>-<name>.log`. It waits until something answers at the server's URL - up to a minute - so the URL you are given has answered once; one that exits first comes back with the end of its output. A port something else holds is said, with what holds it, and nothing is started there: the app is not moved to a port you were not told about.
+3. **Starts what serves** with `activate`: in the background, in its own process group, its output in `.turri/deploy/<module>-<name>.log`. It waits until something answers at the server's URL - up to a minute - so the URL you are given has answered once; one that exits first comes back with the end of its output. A port something else holds is said, with what holds it, and nothing is started there: the app is not moved to a port you were not told about. It runs in the deployed folder, or a folder inside it the model names relative to it (`frontend`); a folder that is not there starts nothing, and the model is told so with what the deployed folder holds, to name the right one.
 
 What it started is listed by the `pulses` tool and by **`/halt`**, and stopped by **`/halt activated <name>`**, by `halt`, by the next deploy of the module, and when the chat exits.
 
@@ -35,9 +33,9 @@ What it started is listed by the `pulses` tool and by **`/halt`**, and stopped b
 
 With `release-after-pulse: true` in `config.turri.yaml`, turri releases what each pulse lands itself, as the pulse's last stage (`releasing what this pulse landed`): the pulse ends once it is released, so the module's next pulse starts on what is out, and the chat - waiting on your answer to a question, say - has no part in it. One release a pulse that lands, in order.
 
-The release is done by an agent on the coding model, thinking low - it follows steps, and a small model does that well - the same one `turri release` runs, and it finds the guidance as the chat would: what was passed to `release` earlier in the conversation, the project's AGENTS.md and its skills. When nothing there says to release after a build, it releases nothing and says so. Its last words go in the pulse's report - "Released after the pulse: ..." - and the chat, seeing them, does not release it again. A release that fails is said there too; what the pulse landed stays.
+The release is done by an agent on the coding model, thinking low - it follows steps, and a small model does that well - the same one `turri release` runs, and it finds the guidance as the chat would: what was passed to `release` earlier in the conversation, the project's AGENTS.md and its skills. The setting is the word to release; the guidance says only how - without any, the code goes to `dist/<module>` and is started from there. Its last words go in the pulse's report - "Released after the pulse: ..." - and the chat, seeing them, does not release it again: it says in a line what was released, then does what it was told to do once something is released - a host such as a desktop app tells it, in its `surface`, to open it where the person can watch and say what to test. A release that fails is said there too; what the pulse landed stays.
 
-Off by default: without the key, releasing after a pulse is the chat's, when its guidance says so.
+Off without the key: releasing after a pulse is then the chat's, when its guidance says so. `turri init-config` writes `release-after-pulse: true`.
 
 ## On the command line
 

package/docs/hosting.md

@@ -94,7 +94,7 @@ await session.bindExtensions({ uiContext, mode: "tui" });
 
 - **The jobs.** The pulses the conversation starts - its tools, `/regenerate`, a \*\*\*plain change - run in its own job registry and work loop, the project's one. The host is handed both as they are made, and told of each job as it changes, so it shows the very jobs the conversation runs. Its buttons are best the conversation's commands - `session.prompt("/regenerate app.plain")` - so there is never a second loop on the same project.
 - **The questions.** `dialogs` is `ask_user`'s two dialogs: `select(title, options, context, at)` and `input(title, context)`, each resolving with the answer, or undefined when the person dismissed it. Given, the conversation's questions and a skill's interview are put in them; without it, in the terminal's own dialog.
-- **The surface.** What turri tells the model of where the person watches the work is the terminal's by default: regen, the side panel on `ctrl+h`, `/pulses`. In a host none of that is there, and the model would send the person to keys and panels that do not exist. `surface` is the host's own description of its UI - the views it has in place of the terminal's, what its marks and buttons mean, where questions appear - in its own words. Given, turri leaves every terminal instruction out of what the model is told and puts the surface in turri's identity, as a `<surface>` block, where the identity speaks of regen. It reaches the side questions and the tools' own words too: a pulse not found says the `pulses` tool lists them, not `/pulses`. Text only the person sees in the terminal - the job panel, the side panel - is the terminal's and stays as it is. Without `surface`, the prompt is the terminal's, byte for byte.
+- **The surface.** What turri tells the model of where the person watches the work is the terminal's by default: regen, the side panel on `ctrl+h`, `/pulses`. In a host none of that is there, and the model would send the person to keys and panels that do not exist. `surface` is the host's own description of its UI - the views it has in place of the terminal's, what its marks and buttons mean, where questions appear - in its own words. Given, turri leaves every terminal instruction out of what the model is told and puts the surface in turri's identity, as a `<surface>` block, where the identity speaks of regen. It reaches the side questions and the tools' own words too: a pulse not found says the `pulses` tool lists them, not `/pulses`. Text only the person sees in the terminal - the job panel, the side panel - is the terminal's and stays as it is. Without `surface`, the prompt is the terminal's, byte for byte. What the conversation is to do once something is released belongs there too - open it in the host's preview, say what to test: after a pulse released under `release-after-pulse`, the conversation does what it was told to do once something is released.
 - **The system prompt.** `systemPrompt(prompt)` gets the whole system prompt for the turn - [pi](https://pi.dev)'s, turri's identity and blocks, the rules - after turri's own `before_agent_start` work, and returns what is sent. It is for what `surface` does not cover; to describe the UI, use `surface`, rather than words appended after turri's that contradict them.
 - **The mode.** `mode: "tui"` runs the work in the background and keeps the conversation free, as the terminal does; `rpc`, `json` and `print` wait for each job. The extension's other UI calls - its notices, its working line, a confirm - come to the host's `uiContext`, as [pi](https://pi.dev)'s [SDK](https://github.com/earendil-works/pi) describes it.