@nanopm/cli 0.1.8 → 0.1.10

package/dist/index.js

@@ -9234,6 +9234,9 @@ function gateOne(ctx, w, leaf) {
   return { draft, refused };
 }
 function draftOf(ctx, w) {
+  return { ...draftFields(w), sources: resolve3(ctx, w.restsOn) };
+}
+function draftFields(w) {
   const headline = w.changelog.headline.trim().replace(/\s+/g, " ");
   const room = CHANGELOG_MAX - headline.length - 1;
   return {
@@ -9243,8 +9246,7 @@ function draftOf(ctx, w) {
     steps: w.steps.map((s) => ({ do: s.do.trim().replace(/\s+/g, " "), who: s.who, ...s.checks ? { checks: true } : {} })),
     size: w.size,
     assumption: clipOrNull(w.worksIf, WORKS_IF_MAX),
-    reasoning: wholeSentences(w.why, WHY_THIS_MAX),
-    sources: resolve3(ctx, w.restsOn)
+    reasoning: wholeSentences(w.why, WHY_THIS_MAX)
   };
 }
 function resolve3(ctx, ids) {
@@ -9312,14 +9314,13 @@ async function readRoadmap(client, projectId) {
 var SPEC_SKILL = "spec";
 var SPEC_MINUTES = 5;
 var SPEC_STEPS = {
-  brief: { says: "Writing what your users will see, and how we\u2019ll know", label: "Writing the brief" },
-  agent: { says: "Turning the brief into a spec a coding agent can build from", label: "Writing the agent spec" },
+  solution: { says: "Writing what your users will see, and how we\u2019ll know", label: "Writing what your users will see" },
+  agent: { says: "Turning the solution into a spec a coding agent can build from", label: "Writing the agent spec" },
   review: { says: "Reading both as you would, then as a coding agent would", label: "Checking both as a coding agent would" }
 };
-function briefRefusal(brief2) {
-  if (!brief2.in_short.trim()) return "it does not say in short what we build";
-  if (!brief2.experience.some((s) => s.trim())) return "it does not walk through the experience";
-  if (!brief2.measure.signal.trim()) return "it does not say how we will know";
+function specRefusal(spec2) {
+  if (!spec2.experience.some((s) => s.trim())) return "it does not walk through the experience";
+  if (!spec2.measure.signal.trim()) return "it does not say how we will know";
   return null;
 }
 function agentSpecRefusal(markdown) {
@@ -9327,19 +9328,25 @@ function agentSpecRefusal(markdown) {
   if (!/^##\s+Acceptance criteria\b/im.test(markdown)) return "it has no acceptance criteria";
   return null;
 }
-function specsRefusal({ brief: brief2, markdown }) {
-  const b = briefRefusal(brief2);
-  if (b) return `the brief ${b}`;
+function specsRefusal({ spec: spec2, markdown }) {
+  const b = specRefusal(spec2);
+  if (b) return `the spec ${b}`;
   const a = agentSpecRefusal(markdown);
   return a ? `the agent spec ${a}` : null;
 }
+function specRecord(mode, answer) {
+  if (mode === "write") return { spec: answer.spec, markdown: answer.markdown, solution: null };
+  if (!answer.solution) throw new Error("a rework writes the whole solution again, and this one came back without it");
+  return { spec: answer.spec, markdown: answer.markdown, solution: answer.solution };
+}
 function specSolutionOf(params) {
   const id = params?.solution;
   return typeof id === "string" ? id : null;
 }
 async function queueSpecs(client, ask7) {
+  const mode = ask7.mode ?? "write";
   const [{ data: solution }, { data: active }, { data: clone }] = await Promise.all([
-    client.from("solutions").select("id, ref, status, opportunity_id").eq("project_id", ask7.projectId).eq("ref", ask7.ref.trim().toUpperCase()).maybeSingle(),
+    client.from("solutions").select("id, ref, status, opportunity_id, specced_at").eq("project_id", ask7.projectId).eq("ref", ask7.ref.trim().toUpperCase()).maybeSingle(),
     client.from("jobs").select("params").eq("project_id", ask7.projectId).eq("skill", SPEC_SKILL).in("status", [...ACTIVE_STATUSES]),
     // The clone on the machine that will run it: the daemon reads the code only in its own (`resolveCwd`).
     client.from("clones").select("repo_path").eq("project_id", ask7.projectId).eq("daemon_id", ask7.daemonId).maybeSingle()
@@ -9347,13 +9354,15 @@ async function queueSpecs(client, ask7) {
   if (!solution || !solution.opportunity_id) throw new Error(`No solution ${ask7.ref.toUpperCase()} on the Roadmap.`);
   if (solution.status === "rejected") throw new Error(`${solution.ref} was thrown out: it gets no specs.`);
   if ((active ?? []).some((j) => specSolutionOf(j.params) === solution.id)) throw new Error(`Nano is already writing the specs of ${solution.ref}.`);
+  if (mode === "write" && solution.specced_at) throw new Error(`${solution.ref} has its specs already: rework the solution to write it all again.`);
+  if (mode === "rework" && !solution.specced_at) throw new Error(`${solution.ref} has no specs yet: write them first.`);
   const { data, error } = await client.from("jobs").insert({
     project_id: ask7.projectId,
     skill: SPEC_SKILL,
     requested_by: ask7.userId,
     trigger: "user",
     target_daemon_id: ask7.daemonId,
-    params: { solution: solution.id, ...clone?.repo_path ? { repo_path: clone.repo_path } : {} }
+    params: { solution: solution.id, ...mode === "rework" ? { rework: true } : {}, ...clone?.repo_path ? { repo_path: clone.repo_path } : {} }
   }).select("id").single();
   if (error?.code === "23505") throw new Error(`Nano is already writing the specs of ${solution.ref}.`);
   if (error || !data) throw new Error(error?.message ?? "could not ask Nano for the specs");
@@ -9364,40 +9373,30 @@ async function queueSpecs(client, ask7) {
 import { z as z15 } from "zod";
 var SpecParams = z15.object({
   solution: z15.guid(),
+  /** *Rework the solution* (spec 74): the whole solution written again, as a new version. */
+  rework: z15.literal(true).optional(),
   repo_path: z15.string().optional(),
   background: z15.boolean().optional()
 }).strict();
 function specAsk(params) {
   const parsed = SpecParams.safeParse(params);
-  if (parsed.success) return { ok: true, solution: parsed.data.solution };
+  if (parsed.success) return { ok: true, solution: parsed.data.solution, mode: parsed.data.rework ? "rework" : "write" };
   const issue = parsed.error.issues[0];
   const unknown2 = issue.code === "unrecognized_keys" ? issue.keys?.join(", ") : null;
   return { ok: false, why: unknown2 ? `this run does not take ${unknown2}` : `${issue.path.join(".") || "params"}: ${issue.message}` };
 }
-var Journey = z15.object({
-  kind: z15.literal("journey"),
-  steps: z15.array(prose(1)).max(9).describe('The user\u2019s path, three to seven steps, each a few words from their side of the screen: "Opens the trial", "Picks a closed search".'),
-  fork: z15.object({
-    after: z15.number().int().describe("The step the path forks after, counted from 1."),
-    when: prose(1).describe('When it forks, a few words: "No closed search".'),
-    then: prose(1).describe("Where it goes instead, a few words.")
-  }).nullable().default(null).describe("One fork at most, only when the path really splits.")
-});
-var BeforeAfter = z15.object({
-  kind: z15.literal("before_after"),
-  before: z15.array(prose(1)).max(6).describe("What the user lives today, two to five short lines."),
-  after: z15.array(prose(1)).max(6).describe("What they will live, two to five short lines, side by side with before.")
+var Diagram = z15.object({
+  caption: prose(1).describe('What it shows, a few words: "Starting the trial on a closed search".'),
+  mermaid: z15.string().min(1).max(4e3).describe("The diagram in Mermaid syntax, whichever type helps most: flowchart, sequenceDiagram, stateDiagram-v2, journey, or a flowchart with two subgraphs for before and after. At most about twelve nodes, labels of a few words in quotes. No styling: no classDef, style, colours, click or links.")
 });
-var BriefFields = {
-  questions: z15.array(z15.object({ ask: prose(1).describe("The question, one sentence."), blocks: prose(1).describe('What it blocks, a few words: "what the trial screen says".') })).max(5).default([]).describe("To finish this brief: up to three questions only the founder can answer. Decide everything else yourself."),
-  in_short: prose(1).describe("In short: three sentences at most \u2014 what we build, for whom, what changes for them. The first could be read alone."),
-  diagrams: z15.array(z15.discriminatedUnion("kind", [Journey, BeforeAfter])).max(2).default([]).describe("At most two. The journey whenever the experience has three steps or more; before and after when the solution changes something the product already does."),
+var SpecFields = {
+  questions: z15.array(z15.object({ ask: prose(1).describe("The question, one sentence."), blocks: prose(1).describe('What it blocks, a few words: "what the trial screen says".') })).max(5).default([]).describe("Questions for you: up to three questions only the founder can answer, and any place the code shows the solution as settled is wrong. Decide everything else yourself."),
+  in_short: prose(1).describe("In short: three sentences at most \u2014 what we build, for whom, what changes for them. The first could be read alone. Read first, right after the problem: not the proposed solution again, its gist."),
+  diagrams: z15.array(Diagram).max(2).default([]).describe("Optional: only when a drawing makes it faster to understand than the words. At most two, in Mermaid, the shape that helps most."),
   experience: z15.array(prose(1)).max(8).describe("The experience: three to six steps, in the present tense, from the user\u2019s side of the screen. Under a hypothesis, the founder\u2019s check comes first, in one line."),
-  build: z15.array(prose(1)).max(8).describe("What we build: three to six points, in users\u2019 words \u2014 what is true the day it ships."),
   wont_do: z15.array(z15.object({ what: prose(1), why: prose(1) })).max(6).default([]).describe("What we won\u2019t do: two to four points, each with why or when."),
   measure: z15.object({
     signal: prose(1).describe("The signal, one sentence: who \xB7 does what \xB7 how many \xB7 by when. Small numbers for a product with few users. Never a baseline you did not measure."),
-    wrong_if: prose(1).describe("We were wrong if\u2026, one sentence. Under a hypothesis, it can show the problem itself wrong."),
     existing: z15.array(z15.object({ name: prose(1).describe("The event as the product records it, exactly."), counts: prose(1).describe("What it counts here, and where you found it.") })).max(8).default([]).describe("Events the product already records that measure this, found in the code or in the connected source. Only what you found."),
     added: z15.array(
       z15.object({
@@ -9411,22 +9410,26 @@ var BriefFields = {
   dependencies: z15.array(prose(1)).max(6).default([]).describe('What must exist first. Empty when nothing: the page says None. No analytics tool in the product: "An analytics tool" is one.')
 };
 var Notes2 = prose().nullable().default(null).describe("A sentence or two, for the Journal.");
-var BriefAnswer = z15.object({
-  ...BriefFields,
-  code: z15.array(z15.object({ path: z15.string().max(200), holds: prose(1).describe("What it holds that matters here, one line.") })).max(16).default([]).describe("The files you read that matter for this change, each with what it holds, for the agent spec\u2019s *Start here*. Empty when the code was not there."),
+var Code = z15.array(z15.object({ path: z15.string().max(200), holds: prose(1).describe("What it holds that matters here, one line.") })).max(16).default([]).describe("The files you read that matter for this change, each with what it holds, for the agent spec\u2019s *Start here*. Empty when the code was not there.");
+var Rewritten = Written.omit({ restsOn: true });
+var SolutionAnswer = z15.object({
+  solution: Rewritten.nullable().default(null).describe('Only when the snapshot says mode "rework": the whole solution, written again. Null in mode "write": those fields are settled.'),
+  ...SpecFields,
+  code: Code,
   notes: Notes2
 });
+var AgentMarkdown = z15.string().min(1).max(6e4);
 var AgentAnswer = z15.object({
-  markdown: prose(1).max(6e4).describe("The agent spec, whole, in markdown, with the sections named in your instructions."),
+  markdown: AgentMarkdown.describe("The agent spec, whole, in markdown, with the sections named in your instructions."),
   notes: Notes2
 });
 var ReviewAnswer = z15.object({
-  brief: z15.object(BriefFields).describe("The brief, whole, corrected where it failed a reader; as it was where it did not."),
-  markdown: prose(1).max(6e4).describe("The agent spec, whole, corrected; as it was where it did not fail."),
+  spec: z15.object(SpecFields).describe("The solution\u2019s sections, whole, corrected where they failed a reader; as they were where they did not."),
+  markdown: AgentMarkdown.describe("The agent spec, whole, corrected; as it was where it did not fail."),
   exchanges: z15.array(z15.object({ asked: prose(1).describe("What the coding agent would have had to guess, as its question, one short sentence."), did: prose(1).describe("What you did: decided it (and what), or left it to the founder.") })).max(5).default([]).describe("Two to five: the questions a coding agent asked of the spec, and what you did about each. They go in the Journal."),
   changed: z15.array(z15.string().max(200)).max(10).default([]).describe("What you changed, a line each, for the Journal.")
 });
-var SCHEMAS7 = { brief: BriefAnswer, agent: AgentAnswer, review: ReviewAnswer };
+var SCHEMAS7 = { solution: SolutionAnswer, agent: AgentAnswer, review: ReviewAnswer };
 function parseSpecAnswer(role7, json2) {
   return SCHEMAS7[role7].parse(json2);
 }
@@ -9557,6 +9560,7 @@ async function runSpecsJob({ client, job, adapter, spec: spec2, onEvent }) {
   const solution = row;
   if (!solution?.opportunity_id) throw new Error("That solution is not on the Roadmap.");
   if (solution.status === "rejected") throw new Error(`${solution.ref} was thrown out: it gets no specs.`);
+  const mode = asked.mode;
   const clone = typeof job.params?.repo_path === "string";
   const [all, card, stance, numbers, connections, commit] = await Promise.all([
     readOpportunities(client, projectId),
@@ -9571,16 +9575,8 @@ async function runSpecsJob({ client, job, adapter, spec: spec2, onEvent }) {
   const path = leaf ? pathOf(tree, leaf.id) : [];
   const known = {
     today: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
-    solution: {
-      ref: solution.ref,
-      title: solution.title,
-      proposed_solution: solution.description,
-      future_changelog: parseChangelog(solution.changelog),
-      plan: solution.steps,
-      size: solution.size,
-      works_if: solution.assumption,
-      why: solution.reasoning
-    },
+    mode,
+    solution: snapshotOf({ ref: solution.ref, title: solution.title, description: solution.description, changelog: solution.changelog ?? "", steps: solution.steps, size: solution.size ?? "small", assumption: solution.assumption, reasoning: solution.reasoning }),
     problem: leaf ? problemOf(tree, leaf) : null,
     part_of: path.slice(1).map((p) => p.problem),
     objective: lensOf(card.goals),
@@ -9590,27 +9586,37 @@ async function runSpecsJob({ client, job, adapter, spec: spec2, onEvent }) {
     numbers
   };
   const reads = clone ? `the code read at ${commit ?? "its current commit"}` : "no clone here, so the code is not read";
-  await journal("spec.read", `Writing the specs of \u201C${clip3(solution.title, 80)}\u201D (${solution.ref}): ${reads}; ${connections.length ? `${connections.length} connected source${connections.length === 1 ? "" : "s"}` : "no analytics connected"}.`);
+  const doing = mode === "rework" ? "Reworking" : "Writing the specs of";
+  await journal("spec.read", `${doing} \u201C${clip3(solution.title, 80)}\u201D (${solution.ref}): ${reads}; ${connections.length ? `${connections.length} connected source${connections.length === 1 ? "" : "s"}` : "no analytics connected"}.`);
   const ctx = { adapter, spec: spec2, onEvent };
   const timings = [];
-  const time = (what, cost) => timings.push({ what, ms: cost.ms });
+  const time = (what2, cost) => timings.push({ what: what2, ms: cost.ms });
   const repo = clone ? { repository: "the working directory", why_no_repository: null } : { repository: null, why_no_repository: "No clone of the product rode along with this run: work from what the snapshot says the product does." };
   const writerGrant = [...clone ? ["read_repo"] : [], ...connections.length ? ["read_data"] : []];
-  const brief2 = await ask3(ctx, "brief", { grant: writerGrant, prompt: { ...known, ...repo, connections } });
-  time("brief", brief2.cost);
-  const { code, notes: briefNotes, ...draft } = brief2.answer;
-  await step("spec.brief", `Brief written: ${count(draft.build.length, "point")} built, ${count(draft.questions.length, "question")} for you, ${count(draft.measure.added.length, "new event")}.${briefNotes ? ` ${briefNotes}` : ""}`, brief2.cost);
+  const writing = { grant: writerGrant, prompt: { ...known, ...repo, connections } };
+  const written = await ask3(ctx, "solution", writing);
+  time("solution", written.cost);
+  const { solution: rewritten, code, notes, ...draft } = written.answer;
+  const fields = mode === "rework" && rewritten ? draftFields(rewritten) : null;
+  const wrote = fields ? `Solution written again: \u201C${clip3(fields.title, 80)}\u201D` : `Sections written: ${count(draft.experience.length, "step")} of the experience`;
+  await step("spec.solution", `${wrote}, ${count(draft.questions.length, "question")} for you, ${count(draft.measure.added.length, "new event")}.${notes ? ` ${notes}` : ""}`, written.cost);
+  const whole = fields ? snapshotOf({ ref: solution.ref, ...fields }) : known.solution;
+  const first = specRecord(mode, { spec: draft, markdown: "", solution: fields });
+  const unreadable = specRefusal(first.spec) ?? (first.solution && leaf ? solutionRefusal(first.solution, leaf) : null);
+  if (unreadable) throw new Error(`The solution cannot be recorded: ${unreadable}.`);
+  const target = await recordSections(client, { projectId, jobId: job.id, solution, spec: first.spec, fields: first.solution });
+  await journal("spec.sections", first.solution ? `${target.ref} \u201C${clip3(first.solution.title, 80)}\u201D takes ${solution.ref}\u2019s place on the board; its agent spec is on its way.` : `Sections on the sheet; the agent spec is on its way.`);
   const agent = await ask3(ctx, "agent", {
     grant: clone ? ["read_repo"] : [],
-    prompt: { today: known.today, ref: solution.ref, commit: commit ?? "not read", ...repo, brief: draft, code, solution: known.solution, problem: known.problem, product: known.product, constraints: stance }
+    prompt: { today: known.today, ref: target.ref, commit: commit ?? "not read", ...repo, solution: whole, spec: draft, code, problem: known.problem, product: known.product, constraints: stance }
   });
   time("agent spec", agent.cost);
   await step("spec.agent", `Agent spec written.${agent.answer.notes ? ` ${agent.answer.notes}` : ""}`, agent.cost);
-  let final = { brief: draft, markdown: agent.answer.markdown };
+  let final = { spec: first.spec, markdown: agent.answer.markdown };
   try {
-    const review2 = await ask3(ctx, "review", { prompt: { brief: draft, markdown: agent.answer.markdown, solution: known.solution, problem: known.problem } });
+    const review2 = await ask3(ctx, "review", { prompt: { mode, solution: whole, spec: draft, markdown: agent.answer.markdown, problem: known.problem } });
     time("review", review2.cost);
-    const reviewed = { brief: review2.answer.brief, markdown: review2.answer.markdown };
+    const reviewed = { spec: review2.answer.spec, markdown: review2.answer.markdown };
     const refused2 = specsRefusal(reviewed);
     if (refused2) await journal("spec.review_kept_out", `The review\u2019s version was left out (${refused2}): the writers\u2019 drafts are recorded.`);
     else final = reviewed;
@@ -9624,19 +9630,15 @@ async function runSpecsJob({ client, job, adapter, spec: spec2, onEvent }) {
     await journal("spec.review_failed", `The review did not finish (${clip3(errorMessage(err), 200)}): the writers\u2019 drafts are recorded.`);
   }
   const refused = specsRefusal(final);
-  if (refused) throw new Error(`The specs cannot be read: ${refused}.`);
-  const { error: published } = await client.rpc("publish_spec", {
-    p_project_id: projectId,
-    p_solution_id: solution.id,
-    p_brief: final.brief,
-    p_agent_spec: final.markdown
-  });
+  if (refused) throw new Error(`The specs cannot be recorded: ${refused}.`);
+  const { error: published } = await client.rpc("publish_solution_spec", { p_project_id: projectId, p_solution_id: target.id, p_spec: final.spec, p_agent_spec: final.markdown });
   if (published) throw new Error(`could not record the specs: ${published.message}`);
-  const summary = `Specs of \u201C${clip3(solution.title, 80)}\u201D (${solution.ref}) written: the brief, with ${count(final.brief.questions.length, "question")} for you, and the agent spec. Took ${duration(Date.now() - started)}: ${timings.map((t) => `${t.what} ${duration(t.ms)}`).join(", ")}.`;
+  const what = first.solution ? `\u201C${clip3(solution.title, 80)}\u201D (${solution.ref}) reworked as ${target.ref} \u201C${clip3(first.solution.title, 80)}\u201D` : `Specs of \u201C${clip3(solution.title, 80)}\u201D (${solution.ref}) written`;
+  const summary = `${what}: ${count(final.spec.questions.length, "question")} for you, and the agent spec. Took ${duration(Date.now() - started)}: ${timings.map((t) => `${t.what} ${duration(t.ms)}`).join(", ")}.`;
   await journal("spec.summary", summary);
   return { status: "succeeded", result: summary };
 }
-var ROLE_NAME = { brief: "spec brief writer", agent: "spec agent writer", review: "spec reviewer" };
+var ROLE_NAME = { solution: "spec solution writer", agent: "spec agent writer", review: "spec reviewer" };
 async function ask3(ctx, role7, call2) {
   const cost = await runRole({
     adapter: ctx.adapter,
@@ -9653,6 +9655,33 @@ async function ask3(ctx, role7, call2) {
   });
   return { answer: stripDeep(parseSpecAnswer(role7, JSON.parse(cost.text))), cost };
 }
+async function recordSections(client, r) {
+  if (!r.fields) {
+    const { error: error2 } = await client.rpc("publish_solution_spec", { p_project_id: r.projectId, p_solution_id: r.solution.id, p_spec: r.spec });
+    if (error2) throw new Error(`could not record the sections: ${error2.message}`);
+    return { id: r.solution.id, ref: r.solution.ref };
+  }
+  const f = r.fields;
+  const { data, error } = await client.rpc("rework_spec", {
+    p_project_id: r.projectId,
+    p_solution_id: r.solution.id,
+    p_job_id: r.jobId,
+    p_title: f.title,
+    p_description: f.description ?? "",
+    p_changelog: f.changelog,
+    p_steps: f.steps,
+    p_size: f.size,
+    p_assumption: f.assumption ?? "",
+    p_reasoning: f.reasoning,
+    p_spec: r.spec
+  });
+  const made = data?.[0];
+  if (error || !made) throw new Error(`could not record the reworked solution: ${error?.message ?? "no new version"}`);
+  return made;
+}
+function snapshotOf(s) {
+  return { ref: s.ref, title: s.title, proposed_solution: s.description, future_changelog: parseChangelog(s.changelog), plan: s.steps, size: s.size, works_if: s.assumption, why: s.reasoning };
+}
 function problemOf(tree, leaf) {
   return { ref: placeOf(tree, leaf.id) ?? leaf.ref, problem: leaf.problem, description: leaf.description ?? null, status: leaf.evidence_status, confirmed_by_founder: leaf.status === "confirmed" };
 }
@@ -14231,7 +14260,7 @@ import { promisify as promisify8 } from "util";
 // package.json
 var package_default = {
   name: "@nanopm/cli",
-  version: "0.1.8",
+  version: "0.1.10",
   description: "An autonomous product manager for builders who run several small products. Runs on your machine, drives your own coding harness.",
   type: "module",
   license: "MIT",
@@ -15937,7 +15966,9 @@ async function spec(ref, opts) {
   const wanted = ref.trim().toUpperCase();
   const { data: solution } = await auth.client.from("solutions").select("id, ref, title, agent_spec").eq("project_id", project.id).eq("ref", wanted).maybeSingle();
   if (!solution) throw new Error(`no solution ${wanted}. Run \`nanopm roadmap\` to see them.`);
-  if (!opts.write) {
+  if (opts.write && opts.rework) throw new Error("--write or --rework, not both.");
+  const mode = opts.rework ? "rework" : opts.write ? "write" : null;
+  if (!mode) {
     if (!solution.agent_spec) return `${solution.ref} has no specs yet: \`nanopm spec ${solution.ref} --write\`, or *Write the specs* on its sheet.`;
     return solution.agent_spec.trimEnd();
   }
@@ -15945,11 +15976,9 @@ async function spec(ref, opts) {
   if (!daemon) throw new Error("Your machine is asleep: none of your daemons has been seen in the last two minutes, so nothing was queued. `nanopm daemon install` starts it; then ask again.");
   const repo = await detectRepo(opts.cwd);
   if (repo) await rememberClone(auth.client, project.id, repo.root);
-  await queueSpecs(auth.client, { projectId: project.id, userId: auth.userId, daemonId: daemon.id, ref: solution.ref });
-  return [
-    `Writing the specs of ${solution.ref} \u201C${clip(solution.title, 60)}\u201D: the brief and the agent spec, about ${SPEC_MINUTES} minutes on ${daemon.hostname}${repo ? ", reading this code" : ""}.`,
-    `They land on its sheet; \`nanopm spec ${solution.ref}\` prints the agent spec.`
-  ].join("\n");
+  await queueSpecs(auth.client, { projectId: project.id, userId: auth.userId, daemonId: daemon.id, ref: solution.ref, mode });
+  const where = `about ${SPEC_MINUTES} minutes on ${daemon.hostname}${repo ? ", reading this code" : ""}`;
+  return mode === "rework" ? [`Reworking ${solution.ref} \u201C${clip(solution.title, 60)}\u201D: the whole solution and its agent spec, ${where}.`, "The new version takes its card on the Roadmap; `nanopm roadmap` names it."].join("\n") : [`Writing the specs of ${solution.ref} \u201C${clip(solution.title, 60)}\u201D: what it lacks and the agent spec, ${where}.`, `They land on its sheet; \`nanopm spec ${solution.ref}\` prints the agent spec.`].join("\n");
 }
 
 // src/commands/want.ts
@@ -17941,8 +17970,8 @@ function buildProgram() {
     }
     console.log(await roadmap(ref, { cwd: process.cwd(), projectId: opts.project, board: opts.board, color: colorOf(opts) }));
   });
-  program.command("spec <ref>").description("A solution's agent spec, as written, to hand to any coding agent (`nanopm spec DOG-3 > SPEC.md`); `--write` asks Nano for its specs \u2014 the solution brief and the agent spec \u2014 reading this code, read-only").option("--project <id>", "project id (default: the project of the current repo)").option("--write", "write the specs, or write them again").action(async (ref, opts) => {
-    console.log(await spec(ref, { cwd: process.cwd(), projectId: opts.project, write: opts.write }));
+  program.command("spec <ref>").description("A solution's agent spec, as written, to hand to any coding agent (`nanopm spec DOG-3 > SPEC.md`); `--write` asks Nano for what the solution lacks and its agent spec, reading this code, read-only; `--rework` for the whole solution again").option("--project <id>", "project id (default: the project of the current repo)").option("--write", "write the specs: the sections the solution lacks, and the agent spec").option("--rework", "rework the whole solution and its agent spec, as a new version in its place").action(async (ref, opts) => {
+    console.log(await spec(ref, { cwd: process.cwd(), projectId: opts.project, write: opts.write, rework: opts.rework }));
   });
   for (const [kind, help] of [
     ["accept", "Accept a solution; NanoPM builds it when you ask, or you do it and say so with 'nanopm done'"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanopm/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "An autonomous product manager for builders who run several small products. Runs on your machine, drives your own coding harness.",
   "type": "module",
   "license": "MIT",

package/skills/spec/SKILL.md

@@ -1,3 +1,3 @@
 The spec crew is coordinated in code (`packages/daemon/src/specs-job.ts`): this skill is never run
-as one session. Its roles are `spec-brief`, `spec-agent` and `spec-review`
-(docs/✅nanopm-73-specs-from-a-solution.md §5).
+as one session. Its roles are `spec-solution`, `spec-agent` and `spec-review`
+(docs/✅nanopm-73-specs-from-a-solution.md §5, docs/✅nanopm-74-a-solution-is-its-spec.md §2).

package/skills/spec/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "spec",
-  "description": "Write the specs of one solution on the Roadmap: a crew coordinated in code. spec-brief writes the solution brief the founder reads, reading the code and the connected analytics read-only; spec-agent writes the agent spec any coding agent starts from; spec-review reads both cold as the founder and as a coding agent, and hands both back corrected. Recorded on the solution, both at once.",
+  "description": "Write the specs of one solution on the Roadmap, or rework it whole: a crew coordinated in code. spec-solution writes the sections the solution lacks — or the whole solution, in a rework — reading the code and the connected analytics read-only; spec-agent writes the agent spec any coding agent starts from; spec-review reads both cold as the founder and as a coding agent, and hands both back corrected. Recorded on the solution, both at once.",
   "capabilities": ["memory"],
   "maxTurns": 10,
   "timeout": "30m",

package/skills/spec-agent/SKILL.md

@@ -1,5 +1,5 @@
 You are Nano, the product manager of this product, on the spec crew. The founder asked for the
-specs of a solution on their Roadmap, and the brief is written. Your part is the **agent spec**:
+specs of a solution on their Roadmap, and the solution's page is written. Your part is the **agent spec**:
 the markdown a coding agent starts from — Claude Code, Codex, Cursor, or a person. A third role
 will read it cold, as that agent would, and fix what it would have to guess.
 
@@ -9,13 +9,15 @@ reads the code better than any spec — except where the product's rules decide.
 ## What you hold
 
 - **The code**, read-only — Read, Glob and Grep in the working directory — when the snapshot says
-  `repository`. Start from the files the brief's writer handed over in `code`, then look where the
+  `repository`. Start from the files the solution's writer handed over in `code`, then look where the
   change will live: the screens, the data, the tests beside them, the project's own instructions
   (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`). Never open `.env` files or anything holding
-  secrets. Without the code, write from the brief and say in *Start here* that the code was not read.
+  secrets. Without the code, write from the solution and say in *Start here* that the code was not read.
 - Nothing else: no web, no write.
 
-The snapshot gives you the `brief`, the `solution` it comes from (its plan among it), the `problem`
+The snapshot gives you the `solution` whole — its title, the proposed solution, its changelog, its
+plan, its size, *It works if* — and its `spec`: the questions, the experience and its diagrams,
+what we won't do, how we'll know, the risks, the dependencies. Then the `problem`
 it solves, the `product`, the founder's `constraints`, the `commit` the code was read at, and
 `today`.
 
@@ -27,18 +29,18 @@ an agent and the pages look for them:
 ```markdown
 # <the solution's title>
 
-> Spec for a coding agent, written by NanoPM on <today> from the solution brief of <ref>.
+> Spec for a coding agent, written by NanoPM on <today> from the solution <ref>.
 > Code read at <commit>.
 
 ## Goal
 Two lines: the change, and what it does for users.
 
 ## Context
-The product in three lines, who the user is, the problem this solves — from the brief.
+The product in three lines, who the user is, the problem this solves — from the solution.
 
 ## Before you start
 - Read the repository's CLAUDE.md or AGENTS.md, when there is one, and follow it.
-- The founder's open questions, from the brief: do not guess these; ask.
+- The founder's open questions, from the solution's *Questions for you*: do not guess these; ask.
 
 ## Start here
 The files and places it lives, each with what it holds — from your reading. Verify before relying
@@ -55,7 +57,7 @@ The existing events it reuses, and what they count. The new ones: name, when it
 properties. No event carries words a user wrote.
 
 ## Out of scope
-What not to build, from the brief's *What we won't do*.
+What not to build, from the solution's *What we won't do*.
 
 ## Constraints
 The founder's constraints, the project's conventions, and: ask the founder before adding a
@@ -71,7 +73,7 @@ The tests to write, the commands to run (the project's own: its package scripts,
 runner), what to look at by hand.
 
 ## Decisions Nano took
-What the brief left open that you settled, and why — one line each.
+What the solution left open that you settled, and why — one line each.
 
 ## Definition of done
 - [ ] Every acceptance criterion passes.
@@ -81,18 +83,18 @@ What the brief left open that you settled, and why — one line each.
 ## How to write it
 
 - **Only what an agent can build.** The plan's steps that are the founder's (*Ask three
-  principals…*) stay in the brief. Under a hypothesis, keep the build as small as the check needs,
+  principals…*) stay on the solution's page. Under a hypothesis, keep the build as small as the check needs,
   and say so in the goal.
-- **Every point of the brief's *What we build* has at least one acceptance criterion**, and every
+- **Every change the proposed solution and the changelog promise has at least one acceptance criterion**, and every
   *won't do* is in *Out of scope*.
 - **IDs and checkboxes** — R1, AC1, `- [ ]` — so an agent can cite them in commits and tick them.
-- **The diagrams** of the brief, when they help the agent, as `mermaid` blocks under *Context*.
+- **The diagrams** of the solution, when they help the agent, as `mermaid` blocks under *Context*.
 - **Name what exists.** When the product already has a screen, a component, a table or a helper
   that this should reuse, name it in *Start here*: an agent that does not know it will build a
   second one.
 - **Be exact where it matters**: event names, routes, field names, the words on a button the
-  brief settled. Elsewhere, describe the behaviour and let the agent choose.
-- Write in the language the brief is written in. Keep it as long as the change needs and no
+  solution settled. Elsewhere, describe the behaviour and let the agent choose.
+- Write in the language the solution is written in. Keep it as long as the change needs and no
   longer: a Small solution reads in a few minutes.
 
 ## Rules

package/skills/spec-agent/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-agent",
-  "description": "Write the agent spec of one solution from its brief: markdown any coding agent can start from — goal, context, where it lives in the code, requirements, acceptance criteria, analytics, out of scope, constraints, slices, how to verify, the decisions taken, a definition of done. Reads the founder's code, read-only. Internal crew role; no publication authority.",
+  "description": "Write the agent spec of one solution from the whole solution: markdown any coding agent can start from — goal, context, where it lives in the code, requirements, acceptance criteria, analytics, out of scope, constraints, slices, how to verify, the decisions taken, a definition of done. Reads the founder's code, read-only. Internal crew role; no publication authority.",
   "capabilities": ["read_repo"],
   "model": "claude-opus-5-5",
   "maxTurns": 40,

package/skills/spec-review/SKILL.md

@@ -1,17 +1,25 @@
-You are the reviewer on the spec crew. Nano wrote two documents from one solution on the founder's
-Roadmap: the **solution brief**, which the founder reads in two minutes, and the **agent spec**,
-which a coding agent starts from. You read both **cold**, as two readers, and you hand both back
-corrected. You have no tools: everything is in the snapshot — the `brief`, the agent spec as
-`markdown`, the `solution` they come from, and its `problem`.
+You are the reviewer on the spec crew. Nano completed one solution on the founder's Roadmap: the
+**solution**, one page the founder reads in two minutes — its roadmap fields in `solution`, the
+sections just written in `spec` — and the **agent spec**, which a coding agent starts from. You
+read both **cold**, as two readers, and you hand both back corrected. You have no tools:
+everything is in the snapshot — the `mode`, the `solution`, its `spec`, the agent spec as
+`markdown`, and its `problem`.
+
+**You touch only `spec` and the agent spec.** The solution's fields are on the founder's board
+already, in both modes (in `rework`, Nano just wrote them again): they are settled. A section that
+says again what the proposed solution says, or disagrees with it in silence, fails: cut the
+repeat, and turn a disagreement into a question. The founder may be reading the sections while you
+work: change what fails a reader, not what you would merely say differently.
 
 ## Two readers
 
-**The founder**, reading the brief with no context, in thirty seconds:
+**The founder**, reading the solution's page with no context, in thirty seconds:
 
-- Do I know what we build, for whom, and what changes for them? (*In short*.)
-- Can I picture what my users will see and do? (*The experience*, the diagram.)
-- Do I know how we'll know it worked — who does what, how many, by when — and what would prove us
-  wrong?
+- Do I know what we build, for whom, and what changes for them? (The proposed solution.)
+- Can I picture what my users will see and do? (*The experience*, the diagrams.) Does each diagram
+  help, or say again what the words say? Cut one that does not; keep each valid Mermaid, small,
+  with no styling, colours or links.
+- Do I know how we'll know it worked — who does what, how many, by when?
 - Is anything in words I would not use about my own product? Any Nano shorthand (*leaf*, *lens*,
   *pick*, *run*, *crew*)? Any sentence too long to read once?
 - Are the open questions really mine to answer — a price, a promise to users, a rule of my
@@ -31,11 +39,11 @@ corrected. You have no tools: everything is in the snapshot — the `brief`, the
   jargon. Keep what holds as it was: you are an editor, not a second author.
 - **For each thing the agent would have to guess**, either **decide** it — the obvious choice for
   this product, written into *Decisions Nano took* with one line of why — or, when only the founder
-  can answer, **leave it to them**: add it to the brief's questions (three at most) and to *Before
+  can answer, **leave it to them**: add it to the solution's questions (three at most) and to *Before
   you start*.
-- **Make the two agree**: every point of *What we build* has at least one acceptance criterion;
-  every *won't do* is in *Out of scope*; the same events, under the same names, in both; the
-  questions in the brief are the ones in *Before you start*.
+- **Make the two agree**: every change the proposed solution and the changelog promise has at
+  least one acceptance criterion; every *won't do* is in *Out of scope*; the same events, under
+  the same names, in both; the solution's questions are the ones in *Before you start*.
 - **Honesty**: cut any number nobody measured (a baseline, a percentage of users), any file or
   event named as existing that the documents do not show was found, and any event property that
   would carry words a user wrote.
@@ -43,10 +51,10 @@ corrected. You have no tools: everything is in the snapshot — the `brief`, the
 
 ## What you hand back
 
-- `brief` and `markdown`: both documents, **whole**, corrected.
+- `spec` and `markdown`: the sections and the agent spec, **whole**, corrected.
 - `exchanges`: two to five — each a question the coding agent asked of the spec, in its voice,
   one short sentence (*"Does a closed search count against the trial's limit?"*), and what you did
-  (*"Decided: it does not — in Decisions."*, *"Left to you: added to the brief's questions."*).
+  (*"Decided: it does not — in Decisions."*, *"Left to you: added to the solution's questions."*).
   They go in the Journal, where the founder reads what the review did, so make them the real
   ones, the ones that mattered most.
 - `changed`: what you changed, a line each.

package/skills/spec-review/skill.json

@@ -1,9 +1,9 @@
 {
   "name": "spec-review",
-  "description": "Read a solution brief and its agent spec cold, as the founder and as a coding agent; check they agree; hand both back corrected, with the questions a coding agent would have asked and what was done about each. Internal crew role; no tools and no publication authority.",
+  "description": "Read a solution and its agent spec cold, as the founder and as a coding agent; check they agree; hand both back corrected, with the questions a coding agent would have asked and what was done about each. Internal crew role; no tools and no publication authority.",
   "capabilities": [],
   "model": "claude-opus-5-5",
   "maxTurns": 8,
   "timeout": "15m",
-  "prompt": "Review the brief and the agent spec, and return only the required JSON."
+  "prompt": "Review the solution and the agent spec, and return only the required JSON."
 }

package/skills/{spec-brief → spec-solution}/SKILL.md

@@ -1,8 +1,28 @@
 You are Nano, the product manager of this product, on the spec crew. The founder picked a solution
-on their Roadmap and asked for its specs. Your part is the **solution brief**: the page they read
-in two minutes, like a short PRD, and understand at once — **what we build, what their users will
-live, and how we will know it worked**. After you, a second role turns your brief into a spec for
-a coding agent, and a third reads both cold and fixes what fails.
+on their Roadmap and asked for its specs. A solution is one page the founder reads like a short
+PRD: on the Roadmap it already has its title, the proposed solution, its future changelog, its
+plan, its size and what it rests on (*It works if*). Your part is **the rest of that page** — what
+their users will live, what we won't do, **how we will know it worked**, the risks, the
+dependencies, and the questions only the founder can answer. After you, a second role turns the
+whole solution into a spec for a coding agent, and a third reads both cold and fixes what fails.
+
+## Two modes
+
+The snapshot says which, in `mode`:
+
+- **`write`** — *Write the specs*. The solution's fields are **settled**: build on them, never
+  repeat them, never contradict them. Write only the sections below. The proposed solution
+  already says what we build, in short: there is no section for that. **Where the code shows a
+  settled field is wrong** — a step that already exists, a size that does not hold, a promise the
+  product cannot keep — you do not correct it: you say it in `questions`, with what it blocks.
+- **`rework`** — *Rework the solution*. The founder asked you to write **the whole solution
+  again**, in `solution`, from what you know and from the code, then the sections below. Hold its
+  fields to the Roadmap's rules: a title of at most 60 characters starting with a verb, in words a
+  user understands; the proposed solution in two to four short paragraphs, never the changelog
+  again; a changelog in the users' own words; a plan of two to six concrete steps, Nano's or the
+  founder's, the first one checking the problem when it is still a hypothesis; Small or Big,
+  scope, never time; *It works if* the one belief it rests on. Keep what was right; change what the
+  code or what you know shows wrong, the title and the size included.
 
 Write it like a very good PM who knows this product: specific, plain, short. The founder is often
 alone on their product. They will hand the work to a coding agent, so what you leave vague, an
@@ -18,14 +38,15 @@ agent will guess.
 - Nothing else: no web, no write. You change nothing anywhere.
 
 The snapshot gives you the `solution` (its title, the proposed solution, its future changelog, its
-plan, its size, what it rests on), the `problem` it solves and what that problem is `part_of`, the
+plan, its size, *It works if*, why this one), the `problem` it solves and what that problem is `part_of`, the
 `objective`, the `product` and its `pitch` as the business card says them, the `personas`, the
 founder's `stance` and `constraints`, and the `numbers` Nano has measured.
 
 ## Steps
 
-1. **Read the solution and its problem.** The brief never tells the problem again: its page links
-   to it. Start from the changelog — what users would read the day it ships.
+1. **Read the solution and its problem.** Never tell the problem or the proposed solution again:
+   the page shows them just above your sections. Start from the changelog — what users would read
+   the day it ships.
 2. **Look at the code, briefly**, when you have it: where this change would live, what the product
    already does around it, what it already records. You are writing for the founder, not building:
    a few minutes, not an audit. Never open `.env` files or anything holding secrets.
@@ -33,26 +54,29 @@ founder's `stance` and `constraints`, and the `numbers` Nano has measured.
    `posthog.capture`, `analytics.track`, `track(`, `amplitude`, `mixpanel`, `segment`, `gtag`, an
    events table — and note the event names exactly as written. With a connected source,
    `describe_source` to see which events it receives. Query only when a count settles the signal.
-4. **Write the brief.** Hand over in `code` the files that matter, each with what it holds: the
-   agent spec starts from them.
+4. **Write your sections.** Hand over in `code` the files that matter, each with what it holds:
+   the agent spec starts from them.
 
-## The brief
+## The sections
 
-- **questions** — *To finish this brief*: up to three questions **only the founder can answer**
-  (a price, a promise to users, a rule of their business, a taste call), each with what it blocks.
-  Decide everything else yourself: the reviewer will move what a coding agent would guess into
-  decisions. No question for the sake of a section; none is fine.
-- **in_short** — three sentences at most: what we build, for whom, what changes for them. The
-  first sentence could be read alone.
+- **questions** — *Questions for you*: up to three questions **only the founder can
+  answer** (a price, a promise to users, a rule of their business, a taste call), or a settled
+  field the code shows wrong, each with what it blocks. Decide everything else yourself: the
+  reviewer will move what a coding agent would guess into decisions. No question for the sake of a
+  section; none is fine.
 - **experience** — three to six steps, in the present tense, from the user's side of the screen:
   what they see, what they do, what happens. When the problem is still a hypothesis, the first line
   is the founder's check (the plan's first step), in one line.
-- **diagrams** — at most two, only when there is something to draw:
-  - the **journey**, the user's path in three to seven steps of a few words, with one fork at most
-    — drawn whenever the experience has three steps or more;
-  - **before and after**, two to five short lines each — when the solution changes something the
-    product already does.
-- **build** — three to six points, in users' words: what is true the day it ships.
+- **in_short** — *In short*, read first, right after the problem: three sentences at most — what
+  we build, for whom, what changes for them. The first sentence could be read alone. The gist of
+  the proposed solution, not its paragraphs again.
+- **diagrams** — **optional**, at most two, in **Mermaid**. Draw one only when it makes the
+  solution faster to understand than the words already do. Any shape that helps: a `flowchart` of
+  the user's path or of a decision, a `sequenceDiagram` of who talks to whom, a `stateDiagram-v2`
+  of what something goes through, a `journey`, a flowchart with two subgraphs for *before* and
+  *after*. Each with a `caption` of a few words saying what it shows. Keep it small — about twelve
+  nodes at most — with labels of a few words, in quotes, in the founder's words. No styling at all:
+  no `classDef`, `style`, colours, `click` or links. Make sure it is valid Mermaid.
 - **wont_do** — two to four points, each with why or when. The obvious next thing someone would
   add belongs here.
 - **measure** — how we'll know (below).
@@ -65,8 +89,6 @@ founder's `stance` and `constraints`, and the `numbers` Nano has measured.
 - **signal**: who · does what · how many · by when — *3 of the next 10 principals who start a
   trial run a past search on their first day*. Small numbers for a product with few users; a
   percentage over a handful of people is not a signal.
-- **wrong_if**: one sentence that would prove us wrong. Under a hypothesis, it can show the
-  problem itself wrong, not only the solution.
 - **existing**: the events the product already records that measure this — **only what you
   found**, named exactly as the code or the source names them, with what each counts here.
 - **added**: the new events, in the **object-action** form — an object the user would recognise,
@@ -82,14 +104,10 @@ founder's `stance` and `constraints`, and the `numbers` Nano has measured.
 
 Short sentences, the founder's own words, the product's names for things. No jargon a founder
 would not use about their own product, no Nano shorthand (*leaf*, *lens*, *pick*, *run*, *crew*).
-About 500 words in all. Write in the language the solution is written in.
+About 400 words for your sections. Write in the language the solution is written in.
 
 An example of the register, on a recruiting tool:
 
-> **In short** — Principals can start their trial on a search they closed this year. dogo builds
-> the longlist as if the role opened today, and shows the people they placed beside it. They judge
-> dogo on ground they know, without waiting for a live search.
->
 > **What we won't do** — Import searches from another tool: the closed searches already in dogo
 > are enough to start. Count a past search against the trial's limit: it would punish the
 > principals who try it.

package/skills/spec-solution/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "spec-solution",
+  "description": "Write what a solution on the Roadmap lacks — the open questions as a to-do, the experience with its diagram, what we won't do, how we'll know with analytics, risks, dependencies — or, in a rework, the whole solution again. Reads the founder's code and connected analytics, read-only. Internal crew role; no publication authority.",
+  "capabilities": ["read_repo", "read_data"],
+  "model": "claude-opus-5-5",
+  "maxTurns": 40,
+  "timeout": "20m",
+  "prompt": "Write the solution's sections, and return only the required JSON."
+}

package/skills/spec-brief/skill.json

@@ -1,9 +0,0 @@
-{
-  "name": "spec-brief",
-  "description": "Write the solution brief of one solution on the Roadmap: a short PRD the founder reads in two minutes — the open questions as a to-do, in short, the experience with its diagram, what we build and won't, how we'll know with analytics, risks, dependencies. Reads the founder's code and connected analytics, read-only. Internal crew role; no publication authority.",
-  "capabilities": ["read_repo", "read_data"],
-  "model": "claude-opus-5-5",
-  "maxTurns": 40,
-  "timeout": "20m",
-  "prompt": "Write the solution brief, and return only the required JSON."
-}