kritya 0.8.45-beta → 0.8.47-beta

package/dist/agent/workflow.js

@@ -7,7 +7,44 @@ export const PHASE_ORDER = [
     "build",
     "review",
     "fix",
+    "ship",
 ];
+/**
+ * Phases the workflow stops after, unless the user overrides it.
+ *
+ * Everything up to `plan` is cheap to redo and expensive to get wrong, so each
+ * one hands back to the user. From `build` on the money is already spent —
+ * stopping to ask "shall I now review what I just built?" adds a round trip
+ * without adding a decision, so those run through.
+ */
+export const DEFAULT_GATES = ["brainstorm", "spec", "plan"];
+/** 1-based position of `phase` in the workflow, for progress display. */
+export function phaseIndex(phase) {
+    return PHASE_ORDER.indexOf(phase) + 1;
+}
+/** Whether a run should hand back to the user after `phase`. */
+export function shouldStopAfter(phase, opts = {}) {
+    if (opts.until)
+        return phase === opts.until;
+    if (opts.auto)
+        return false;
+    return (opts.gates ?? DEFAULT_GATES).includes(phase);
+}
+/**
+ * The phases a run starting at `from` will actually execute, in order.
+ *
+ * Pure, so the gate policy is testable without running anything: this is the
+ * list the command layer walks.
+ */
+export function planRun(from, opts = {}) {
+    const run = [];
+    for (let phase = from; phase; phase = nextPhase(phase)) {
+        run.push(phase);
+        if (shouldStopAfter(phase, opts))
+            break;
+    }
+    return run;
+}
 /** The slash command that runs each phase, for user-facing guidance. */
 export const PHASE_COMMAND = {
     brainstorm: "/flow-brainstorm",
@@ -16,7 +53,40 @@ export const PHASE_COMMAND = {
     build: "/flow-build",
     review: "/flow-review",
     fix: "/flow-fix",
+    ship: "/flow-ship",
 };
+/**
+ * Rewind to a phase and re-run everything after it, for when a later phase
+ * turns out to be fixing the wrong requirement. Not a phase, so it is not in
+ * PHASE_ORDER — it is the loop back over it.
+ */
+export const BACK_COMMAND = "/flow-back";
+/** Runs whatever phase comes next, wherever the project stands. */
+export const CONTINUE_COMMAND = "/flow";
+/**
+ * The line that ends a phase, and the command that carries on from it.
+ *
+ * Two callers print this, and they must not disagree: the turn's own teardown,
+ * which covers a single-phase command, and `runFlow`, which has to cover the
+ * last phase of a chain — a chain's teardown runs while the chain flag is still
+ * set, so it deliberately stays quiet, and without the second caller the last
+ * phase of every chain went unannounced.
+ */
+export function phaseDoneMessage(phase) {
+    const next = nextPhase(phase);
+    return next
+        ? `✓ ${phase} phase done — next: ${PHASE_COMMAND[next]} or ${CONTINUE_COMMAND} ` +
+            `(or /project to review where you are)`
+        : `✓ ${phase} phase done — the workflow is complete. /project clear ends it.`;
+}
+/**
+ * What to drop into the input line once a phase ends, or null when the workflow
+ * is finished. Prefilling the continuation is what makes a gate one keypress
+ * instead of a retyped command; nothing runs until it is submitted.
+ */
+export function prefillAfter(phase) {
+    return nextPhase(phase) ? CONTINUE_COMMAND : null;
+}
 /** One-line summary of what each phase produces, for help text and the system prompt. */
 export const PHASE_SUMMARY = {
     brainstorm: "problem, users, MVP features, recommended stack",
@@ -25,6 +95,7 @@ export const PHASE_SUMMARY = {
     build: "the application code, with tests per acceptance criterion, written test-first",
     review: "spec-compliance, security, and reliability findings, with a scorecard up top",
     fix: "fixes for the review's findings, each re-verified",
+    ship: "a handover summary, the test suite actually run, and an optional commit",
 };
 /**
  * Word budget for each phase's artifact. These docs are read by every phase
@@ -37,14 +108,231 @@ const PHASE_WORD_CAP = {
     plan: 1000,
     review: 800,
     fix: 600,
+    ship: 500,
 };
+/**
+ * How many times a project may loop back before the workflow refuses.
+ *
+ * A loop is fix -> spec -> plan -> build -> review -> fix, so it is not free,
+ * and without a bound a disagreement the model cannot resolve on its own
+ * becomes an unbounded spend. Past this the user drives it by hand.
+ */
+export const MAX_REVISITS = 2;
 const STATE_REL = path.join(".kritya", "project.json");
+const REGISTRY_REL = path.join(".kritya", "projects.json");
 export function stateFile(workspace) {
     return path.join(workspace, STATE_REL);
 }
+/**
+ * Path of the registry of every project this workspace has run the workflow
+ * for.
+ *
+ * `project.json` holds only the *active* project, which is why starting a
+ * second project used to look like losing the first: the phase pointer was
+ * overwritten and the old project's place in the flow went with it. The
+ * registry is the durable index that fixes that — one entry per slug, written
+ * on every phase change, so a parked project can be picked up again exactly
+ * where it stopped.
+ */
+export function registryFile(workspace) {
+    return path.join(workspace, REGISTRY_REL);
+}
 function isPhase(v) {
     return typeof v === "string" && PHASE_ORDER.includes(v);
 }
+function parseRevisit(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const { to, reason } = raw;
+    return isPhase(to) && typeof reason === "string" ? { to, reason } : undefined;
+}
+/**
+ * Cap on a recorded scorecard, in characters. The prompt asks for ~100; this is
+ * the backstop for a model that ignores it. `/project` lays these out in a
+ * fixed-width column next to the phase name, so one paragraph — or one embedded
+ * newline — would push the rest of the list off the screen.
+ */
+const SUMMARY_MAX = 120;
+/**
+ * Reduce a recorded scorecard to one displayable line. Truncates rather than
+ * drops: a cut-off line still tells the user more than a missing one, and this
+ * is the only thing standing between a chatty model and the `/project` layout.
+ */
+function clampSummary(v) {
+    const oneLine = v.replace(/\s+/g, " ").trim();
+    if (oneLine.length <= SUMMARY_MAX)
+        return oneLine;
+    return oneLine.slice(0, SUMMARY_MAX - 1).trimEnd() + "…";
+}
+/** Keep only the well-formed, non-empty one-liners; drop everything else. */
+function parseSummaries(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (!isPhase(k) || typeof v !== "string")
+            continue;
+        const line = clampSummary(v);
+        if (line)
+            out[k] = line;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+function parseRegistryEntry(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const { phase, updatedAt, revisits, revisit, summaries } = raw;
+    if (!isPhase(phase))
+        return null;
+    const entry = {
+        phase,
+        updatedAt: typeof updatedAt === "string" ? updatedAt : "",
+    };
+    if (typeof revisits === "number" && Number.isFinite(revisits)) {
+        entry.revisits = Math.max(0, Math.floor(revisits));
+    }
+    const r = parseRevisit(revisit);
+    if (r)
+        entry.revisit = r;
+    const s = parseSummaries(summaries);
+    if (s)
+        entry.summaries = s;
+    return entry;
+}
+/**
+ * Read the registry, discarding anything malformed.
+ *
+ * Same defensiveness as `loadProjectState`: a hand-edited or half-written file
+ * degrades to "no saved projects" rather than throwing into the UI, and one bad
+ * entry never takes the others down with it.
+ */
+export function loadRegistry(workspace) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(registryFile(workspace), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const out = {};
+        for (const [slug, raw] of Object.entries(parsed)) {
+            const entry = parseRegistryEntry(raw);
+            if (entry)
+                out[slug] = entry;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function saveRegistry(workspace, registry) {
+    const file = registryFile(workspace);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(registry, null, 2) + "\n");
+}
+/** The registry entry that mirrors a project's live pointer, exactly. */
+function entryFrom(state) {
+    const entry = { phase: state.phase, updatedAt: state.updatedAt };
+    if (state.revisits)
+        entry.revisits = state.revisits;
+    if (state.revisit)
+        entry.revisit = state.revisit;
+    if (state.summaries && Object.keys(state.summaries).length)
+        entry.summaries = state.summaries;
+    return entry;
+}
+/**
+ * Write the active pointer *and* mirror it into the registry.
+ *
+ * Every writer of `project.json` goes through here so the two can never drift:
+ * the registry is derived state, and a save that updated one but not the other
+ * would leave `/project list` showing a phase the active project had already
+ * left. The entry is replaced wholesale rather than merged — the pointer is the
+ * authority for whichever project is active, and merging would resurrect a
+ * value that was deleted on purpose (a summary cleared by re-entering a phase,
+ * a revisit cleared by acting on it).
+ *
+ * The registry is read *before* the pointer moves, and the project being
+ * displaced is captured on the way past. The agent edits `project.json` itself
+ * when it records a scorecard, so the outgoing project's pointer is routinely
+ * fresher than its registry entry — and this is the only moment that is still
+ * visible, since the pointer is about to be overwritten.
+ */
+function writeProjectState(workspace, state) {
+    const registry = loadRegistry(workspace);
+    const previous = loadProjectState(workspace);
+    if (previous && previous.name !== state.name)
+        registry[previous.name] = entryFrom(previous);
+    fs.mkdirSync(path.dirname(stateFile(workspace)), { recursive: true });
+    fs.writeFileSync(stateFile(workspace), JSON.stringify(state, null, 2) + "\n");
+    registry[state.name] = entryFrom(state);
+    saveRegistry(workspace, registry);
+}
+/**
+ * Every known project, most recently touched first.
+ *
+ * The active project is always included even if the registry has no entry for
+ * it (a workspace whose `project.json` predates the registry), so `/project
+ * list` can never omit the one project the user is actually in.
+ */
+export function listProjects(workspace) {
+    const registry = loadRegistry(workspace);
+    const active = loadProjectState(workspace);
+    const names = new Set(Object.keys(registry));
+    if (active)
+        names.add(active.name);
+    const rows = [];
+    for (const name of names) {
+        const isActive = active?.name === name;
+        const phase = isActive ? active.phase : registry[name]?.phase;
+        if (!phase)
+            continue;
+        rows.push({
+            name,
+            phase,
+            updatedAt: (isActive ? active.updatedAt : registry[name]?.updatedAt) ?? "",
+            revisits: isActive ? active.revisits : registry[name]?.revisits,
+            active: isActive,
+        });
+    }
+    return rows.sort((a, b) => (b.updatedAt || "").localeCompare(a.updatedAt || "") || a.name.localeCompare(b.name));
+}
+/**
+ * Make a saved project active again, restoring its phase, loop-back budget,
+ * pending revisit and per-phase summaries.
+ *
+ * Returns an error message rather than throwing, since the only caller is a
+ * slash command reporting back to the user. Resuming the already-active project
+ * is a no-op success, so a stray `/project resume <current>` does not look like
+ * a failure.
+ */
+export function resumeProject(workspace, name) {
+    const slug = slugify(name);
+    const active = loadProjectState(workspace);
+    if (active?.name === slug)
+        return { ok: true, name: slug };
+    const entry = loadRegistry(workspace)[slug];
+    if (!entry) {
+        const known = Object.keys(loadRegistry(workspace));
+        return {
+            ok: false,
+            error: known.length
+                ? `No project named "${slug}". Known: ${known.join(", ")}.`
+                : `No saved projects yet. Start one with /flow-brainstorm <idea>.`,
+        };
+    }
+    const state = {
+        name: slug,
+        phase: entry.phase,
+        updatedAt: new Date().toISOString(),
+    };
+    if (entry.revisits)
+        state.revisits = entry.revisits;
+    if (entry.revisit)
+        state.revisit = entry.revisit;
+    if (entry.summaries)
+        state.summaries = entry.summaries;
+    writeProjectState(workspace, state);
+    return { ok: true, name: slug };
+}
 /** Parse a phase name from user input (e.g. `/project goto spec`). */
 export function parsePhase(v) {
     const t = v.trim().toLowerCase();
@@ -103,28 +391,131 @@ export function loadProjectState(workspace) {
         const parsed = JSON.parse(fs.readFileSync(stateFile(workspace), "utf8"));
         if (!parsed || typeof parsed.name !== "string" || !isPhase(parsed.phase))
             return null;
-        return { name: parsed.name, phase: parsed.phase, updatedAt: parsed.updatedAt ?? "" };
+        const state = {
+            name: parsed.name,
+            phase: parsed.phase,
+            updatedAt: parsed.updatedAt ?? "",
+        };
+        // The agent writes this file itself when it runs autonomously, so anything
+        // malformed is treated as absent rather than allowed into the UI.
+        const revisit = parseRevisit(parsed.revisit);
+        if (revisit)
+            state.revisit = revisit;
+        if (typeof parsed.revisits === "number" && Number.isFinite(parsed.revisits)) {
+            state.revisits = Math.max(0, Math.floor(parsed.revisits));
+        }
+        const summaries = parseSummaries(parsed.summaries);
+        if (summaries)
+            state.summaries = summaries;
+        return state;
     }
     catch {
         return null;
     }
 }
-export function saveProjectState(workspace, name, phase) {
+export function saveProjectState(workspace, name, phase, carry) {
+    const previous = loadProjectState(workspace);
+    const slug = slugify(name);
+    // A rename is the same project under a new slug, so it hands its own state in
+    // rather than looking like a fresh project and starting from zero.
+    const same = previous && previous.name === slug ? previous : undefined;
     const state = {
-        name: slugify(name),
+        name: slug,
         phase,
         updatedAt: new Date().toISOString(),
     };
-    fs.mkdirSync(path.dirname(stateFile(workspace)), { recursive: true });
-    fs.writeFileSync(stateFile(workspace), JSON.stringify(state, null, 2) + "\n");
+    const revisits = same?.revisits ?? carry?.revisits;
+    if (revisits)
+        state.revisits = revisits;
+    // A recorded revisit is a standing note until it is acted on — so it survives
+    // a move to any *other* phase. It used to be dropped by every save, which
+    // meant running any phase silently ate a note pointing somewhere else, and
+    // only /flow ever displayed it. Clearing it when the phase being saved is the
+    // one it names is what "acted on" means, whether that came from /flow-back or
+    // from the /project goto + /flow-<phase> escape hatch.
+    const revisit = same?.revisit ?? carry?.revisit;
+    if (revisit && revisit.to !== phase)
+        state.revisit = revisit;
+    // Summaries accumulate, so they are never dropped by a save — but the save
+    // that moves a project *into* a phase must not carry that phase's old
+    // summary forward, or `/project` would show last run's scorecard as if it
+    // described the run about to happen. Everything else is kept.
+    const summaries = { ...(same?.summaries ?? carry?.summaries) };
+    delete summaries[phase];
+    if (Object.keys(summaries).length)
+        state.summaries = summaries;
+    writeProjectState(workspace, state);
     return state;
 }
+/**
+ * Record that `phase` has to change before a finding can be fixed — the
+ * programmatic counterpart to the agent writing the same field with
+ * `write_file` during an autonomous run. Returns false when there is no
+ * active project, since there is nothing to attach the note to.
+ */
+export function markRevisit(workspace, to, reason) {
+    const state = loadProjectState(workspace);
+    if (!state)
+        return false;
+    writeProjectState(workspace, {
+        ...state,
+        revisit: { to, reason },
+        updatedAt: new Date().toISOString(),
+    });
+    return true;
+}
+/** How many loop-backs this project has left before MAX_REVISITS is reached. */
+export function revisitsRemaining(workspace) {
+    return Math.max(0, MAX_REVISITS - (loadProjectState(workspace)?.revisits ?? 0));
+}
+/**
+ * Rewind to `to` and spend one of the project's loop-backs.
+ *
+ * Returns false when there is no project or the budget is spent — the caller
+ * reports that rather than looping anyway, which is what bounds the cycle.
+ * The recorded `revisit` is consumed here: acting on it is what it was for.
+ */
+export function takeRevisit(workspace, to) {
+    const state = loadProjectState(workspace);
+    if (!state)
+        return false;
+    const used = state.revisits ?? 0;
+    if (used >= MAX_REVISITS)
+        return false;
+    const next = {
+        name: state.name,
+        phase: to,
+        updatedAt: new Date().toISOString(),
+        revisits: used + 1,
+    };
+    // The phase being re-entered loses its summary: it is about to be produced
+    // again, and the old one would be stale by the time the user reads it.
+    const summaries = { ...state.summaries };
+    delete summaries[to];
+    if (Object.keys(summaries).length)
+        next.summaries = summaries;
+    writeProjectState(workspace, next);
+    return true;
+}
 /**
  * End the active workflow. The docs/<name>/ artifacts are left alone — only the
  * pointer goes, so the agent stops being told to resume a project the user has
  * moved on from.
+ *
+ * The registry entry is deliberately *kept*: ending the active workflow parks
+ * the project rather than forgetting it, which is what makes `/project resume`
+ * able to bring it back later. Forgetting would need an explicit delete, and
+ * nothing in the UI asks for one. The live pointer is mirrored one last time on
+ * the way out, so a scorecard the agent wrote since the last save is not lost
+ * with the file.
  */
 export function clearProjectState(workspace) {
+    const state = loadProjectState(workspace);
+    if (!state)
+        return false;
+    const registry = loadRegistry(workspace);
+    registry[state.name] = entryFrom(state);
+    saveRegistry(workspace, registry);
     try {
         fs.rmSync(stateFile(workspace));
         return true;
@@ -166,7 +557,17 @@ export function renameProject(workspace, from, to) {
     catch (err) {
         return { ok: false, error: `Could not move docs/${current}/: ${err.message}` };
     }
-    saveProjectState(workspace, next, state.phase);
+    // The registry is keyed by slug, so the rename is a move of the entry rather
+    // than a new one — otherwise the old slug lingers as a project that no longer
+    // exists and `/project list` offers to resume it into an empty folder. The
+    // delete has to come *after* the save: the save re-mirrors the pointer it is
+    // replacing, which still carries the old name.
+    saveProjectState(workspace, next, state.phase, state);
+    const registry = loadRegistry(workspace);
+    if (registry[current]) {
+        delete registry[current];
+        saveRegistry(workspace, registry);
+    }
     return { ok: true, name: next };
 }
 /** The phase before `phase` in PHASE_ORDER, or null for the first one. */
@@ -207,6 +608,21 @@ export function artifactExists(workspace, name, phase) {
  * and it would improvise the requirements instead.
  */
 export function phaseBlocker(workspace, name, phase) {
+    // Build writes code rather than a document, so the "did the previous phase
+    // leave its artifact behind" test passes for review trivially — and always.
+    // That let `/flow-review` run against a project that had never been built,
+    // dispatching subagents to review nothing. There is no file to look for, so
+    // fall back to the one piece of evidence there is: the recorded phase. Only
+    // consulted when there *is* a recorded phase, so a bare workspace behaves as
+    // before.
+    if (phase === "review") {
+        const recorded = loadProjectState(workspace)?.phase;
+        if (recorded && PHASE_ORDER.indexOf(recorded) < PHASE_ORDER.indexOf("build")) {
+            return (`The review phase checks what the build phase produced, and "${name}" has not ` +
+                `reached build yet (it is at ${recorded}). Run ${PHASE_COMMAND.build} first.`);
+        }
+        return null;
+    }
     const prev = previousPhase(phase);
     if (!prev || artifactExists(workspace, name, prev))
         return null;
@@ -315,7 +731,7 @@ function capLine(phase) {
  * the plan phase the belated write lands after plan mode has already been
  * turned off by the next command.
  */
-function approvalLine(phase, artifact) {
+function approvalLine(phase, artifact, stopAfter) {
     const next = nextPhase(phase);
     const write = artifact
         ? `Write ${artifact} BEFORE you ask for anything. Approval comes after the file exists — ` +
@@ -323,15 +739,43 @@ function approvalLine(phase, artifact) {
         : "";
     if (!next)
         return `${write}Finish by summarizing the findings for the user.`;
+    // An ungated phase is followed immediately by the next one in the same run,
+    // so asking for approval here would stall a stretch the user asked to run
+    // through — and the question would arrive after the next phase had started.
+    if (!stopAfter) {
+        return (`${write}Then summarize what you produced in a few lines and carry straight on into the ` +
+            `${next} phase (${PHASE_SUMMARY[next]}). Do not stop for approval.`);
+    }
     return (`${write}Then summarize what you produced in a few lines and ask the user to approve ` +
         `before the ${next} phase (they will run ${PHASE_COMMAND[next]}). Do not advance on your own.`);
 }
+/**
+ * Ask the agent to record a one-line scorecard for the phase it just finished.
+ *
+ * A gate hands back to the user with the artifact on disk and a few lines in
+ * chat, and the chat scrolls away — so `/project` had no way to say what a
+ * phase actually concluded without the user opening seven files. The line is
+ * written into `project.json` (not a file of its own) because that is the one
+ * record already mirrored into the registry, so it survives parking a project.
+ *
+ * The wording is deliberately literal about read-modify-write: the model is
+ * editing a file it does not own, and the keys it must not disturb are the ones
+ * that carry the workflow's own state.
+ */
+function summaryLine(phase) {
+    return (`Last, record a one-line scorecard so /project can show what this phase concluded ` +
+        `without the user opening the file: read .kritya/project.json, set "summaries"."${phase}" ` +
+        `to a single line under ~100 characters (a headline, e.g. "3 MVP features, FastAPI + SQLite" ` +
+        `or "5/6 acceptance criteria met, 1 high finding"), and write the whole file back with ` +
+        `every other key left exactly as it was.\n`);
+}
 /** The instruction sent to the agent to carry out a given phase. */
-export function phasePrompt(name, phase, userInput) {
+export function phasePrompt(name, phase, userInput, opts = {}) {
     const slug = slugify(name);
     const extra = userInput.trim() ? `\n\nUser input for this phase:\n${userInput.trim()}` : "";
+    const summary = summaryLine(phase);
     const cap = capLine(phase);
-    const approve = approvalLine(phase, artifactPath(name, phase));
+    const approve = approvalLine(phase, artifactPath(name, phase), opts.stopAfter ?? shouldStopAfter(phase));
     switch (phase) {
         case "brainstorm":
             return (`PROJECT WORKFLOW — BRAINSTORM phase for project "${slug}".\n` +
@@ -349,6 +793,7 @@ export function phasePrompt(name, phase, userInput) {
                 cap +
                 `Do NOT write application code, do NOT design the architecture, and do NOT specify ` +
                 `interfaces yet — this phase settles direction only.\n` +
+                summary +
                 approve +
                 extra);
         case "spec":
@@ -374,6 +819,7 @@ export function phasePrompt(name, phase, userInput) {
                 cap +
                 `Do NOT design the architecture, choose a folder layout, or sequence the work — that is ` +
                 `the plan phase's job. Do NOT write application code.\n` +
+                summary +
                 approve +
                 extra);
         case "plan":
@@ -404,6 +850,7 @@ export function phasePrompt(name, phase, userInput) {
                 cap +
                 `Do NOT restate the spec's requirements, contracts, or data schema — reference them by ` +
                 `number instead. Duplicated requirements drift.\n` +
+                summary +
                 approve +
                 extra);
         case "build":
@@ -437,6 +884,7 @@ export function phasePrompt(name, phase, userInput) {
                 `and its own branch, which keeps this conversation from accumulating the full text of ` +
                 `every file you touch. Give each one the milestone's criteria verbatim; never a summary ` +
                 `of them. Build sequentially otherwise.\n` +
+                summary +
                 approve +
                 extra);
         case "review":
@@ -467,6 +915,7 @@ export function phasePrompt(name, phase, userInput) {
                 `build satisfies the spec. Do not fix anything in this phase — reviewing and fixing in one ` +
                 `pass produces neither a trustworthy review nor a reviewed fix.\n` +
                 cap +
+                summary +
                 approve +
                 extra);
         case "fix":
@@ -485,12 +934,43 @@ export function phasePrompt(name, phase, userInput) {
                 `verdict per finding — fixed, still open, or newly broken — in docs/${slug}/fix.md.\n` +
                 `If anything is still open after the subagent's check, say so plainly; do not report success ` +
                 `on a finding that didn't actually verify as fixed.\n` +
+                `If a finding cannot be fixed in code because the requirement itself is wrong — an ` +
+                `acceptance criterion that is ambiguous or contradicts another, a plan milestone that ` +
+                `does not survive contact with the code — do NOT work around it. Leave it open, say so ` +
+                `plainly, and record where it belongs by writing .kritya/project.json with a "revisit" ` +
+                `field alongside the existing keys: { "name": "${slug}", "phase": "fix", ` +
+                `"revisit": { "to": "spec", "reason": "<one line>" } }. Use "spec" when the ` +
+                `requirement is wrong and "plan" when the design is. That is what lets the user run ` +
+                `${BACK_COMMAND} to redo the phases that depend on it. Reserve this for findings that ` +
+                `genuinely belong upstream — everything else gets fixed here.\n` +
                 cap +
+                summary +
                 `Write docs/${slug}/fix.md BEFORE you ask for anything. Approval comes after the file ` +
                 `exists — never show the writeup in chat and ask whether to save it. Then summarize the ` +
-                `outcome in a few lines. If anything is still open, tell the user they can run ` +
-                `${PHASE_COMMAND.review} to re-check the whole build, or run ${PHASE_COMMAND.fix} again ` +
-                `once they've decided how to handle what's left.\n` +
+                `outcome in a few lines. If anything is still open, say so, and tell the user they can ` +
+                `run ${PHASE_COMMAND.review} to re-check the whole build, ${PHASE_COMMAND.fix} again ` +
+                `once they've decided how to handle what's left, or ${BACK_COMMAND} <phase> if the ` +
+                `finding belongs upstream. Otherwise they can run ${PHASE_COMMAND.ship} to finish.\n` +
+                extra);
+        case "ship":
+            return (`PROJECT WORKFLOW — SHIP phase for project "${slug}". Plan mode is OFF.\n` +
+                `Read docs/${slug}/spec.md, plan.md, review.md and fix.md. This is the handover, so it ` +
+                `has to be trustworthy rather than encouraging.\n` +
+                `First, actually run the project's test suite and report the real result — the exact ` +
+                `command you ran and what it printed. If there is no test suite, say that plainly ` +
+                `instead of implying one passed. A handover that claims success without running ` +
+                `anything is worse than no handover at all.\n` +
+                `Then write docs/${slug}/ship.md BEFORE you ask anything — approval comes after the ` +
+                `file exists, so never show the handover in chat and ask whether to save it. It should ` +
+                `cover: what was built and where the code lives, how to run ` +
+                `it and how to run its tests, which acceptance criteria from spec.md are met and which ` +
+                `are not, and every finding review.md raised that fix.md left open. Cite the AC, SEC ` +
+                `and REL labels rather than restating the requirements.\n` +
+                cap +
+                summary +
+                `Then summarize in a few lines and ask whether to commit. Do NOT commit, push or tag ` +
+                `anything until the user says yes — and when they do, use a conventional-commit message ` +
+                `describing the project, not the individual edits.\n` +
                 extra);
     }
 }