superdev-cli 0.1.1 → 0.2.0

package/src/db/migrations/013_question_options.sql

@@ -0,0 +1,28 @@
+-- A question's options, and which of them is recommended.
+--
+-- `alternatives_json` has held the options since the first migration, and both
+-- surfaces treated them as prose: the control centre folded them into a read-only
+-- list and offered no way to answer at all, and the command line took a free-text
+-- answer only. So a question arrived with its options already worked out and the
+-- reader had to retype one of them.
+--
+-- Three things were missing to make an option selectable rather than readable.
+--
+-- `select_mode` because some questions take one answer and some take several.
+-- "Which database?" is one. "Which roles exist?" is several. Guessing wrongly in
+-- either direction produces a record that does not say what the reader meant.
+--
+-- `recommended_json` because `recommendation` holds advice in prose ("State the
+-- outcome in one sentence and name one thing you could observe"), which cannot be
+-- matched against an option to tag it. Naming the recommended options separately
+-- lets the tag sit on the option itself.
+--
+-- `recommendation_why` because a recommendation nobody can weigh is an
+-- instruction. The reason is what lets somebody disagree with it on purpose.
+
+ALTER TABLE questions ADD COLUMN select_mode TEXT NOT NULL DEFAULT 'one'
+  CHECK (select_mode IN ('one', 'many'));
+
+ALTER TABLE questions ADD COLUMN recommended_json TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE questions ADD COLUMN recommendation_why TEXT;

package/src/docs/proposals.mjs

@@ -486,6 +486,19 @@ function valueFor(column, lines) {
   return lines.join("\n").trim();
 }
 
+/**
+ * Sections that are lists of records rather than one field, and the command that
+ * writes each. These cannot be read back out of Markdown, because a bullet list
+ * cannot say which record each line is, but every one of them can be written.
+ */
+const WRITTEN_BY = {
+  non_goals: 'Non-goals are records rather than one field. Add one with superdev scope record --not "<what this will not do>" --why "<reason>" --apply.',
+  out_of_scope: 'This is a list of records. Add one with superdev scope record --out "<what is out>" --apply.',
+  success_criteria: 'Success criteria belong to a goal. Add one with superdev goal criterion <GOAL-id> --criterion "<what must be true>" --measurement "<how it is read>" --apply.',
+  goals: 'A goal is a record. Add one with superdev goal record --name "<the outcome>" --apply.',
+  milestones: 'A milestone is a record. Add one with superdev milestone record --name "<the stage>" --apply.',
+};
+
 function columnFor(name, columns, constrained) {
   const key = normalizeHeading(name);
   if (!key) return null;
@@ -636,7 +649,12 @@ async function planAcceptance(db, doc, state) {
     }
     const column = item.heading ? columnFor(item.heading, columns, constrained) : null;
     if (!column) {
-      reject(where, `No ${kind} field is projected from this section, so its edit cannot be stored.`);
+      // A section backed by child records has a command, and naming it is the
+      // difference between a refusal and a dead end. Non-goals invited an edit
+      // in its own generated prose and then refused it with nowhere to go, so a
+      // reader who did exactly what the document asked had no next step.
+      reject(where, WRITTEN_BY[normalizeHeading(item.heading ?? "")]
+        ?? `No ${kind} field is projected from this section, so its edit cannot be stored.`);
       continue;
     }
     if (item.section.lines.some((line) => TABLE_ROW.test(line) || LABEL_LINE.test(line))) {

package/src/init/discovery.mjs

@@ -892,6 +892,52 @@ const splitSentences = (text) =>
     .map((s) => s.trim())
     .filter(Boolean);
 
+/**
+ * A statement's name and its description, when the statement carries both.
+ *
+ * Briefs list their parts as `**Screens.** Four routes with shared layout,
+ * navigation, and session state.` Every word of that was taken as the name, so a
+ * product map read as a column of truncated sentences whose first several words
+ * were identical, and the module slug reached the filesystem as
+ * `screens-four-routes-with-shared-layout-navigation-and-sessio`, cut mid-word,
+ * as a committed directory path.
+ *
+ * A label is short, comes first, and has a description after it. The three forms
+ * briefs actually use are `Name. Rest`, `Name: Rest` and `Name - Rest`, and the
+ * dash arrives as a hyphen, an en dash or an em dash because a person typed it.
+ * When there is no description the whole statement is the name, minus the
+ * full stop that would otherwise be part of it.
+ *
+ * The limits are deliberately tight. A label is a noun phrase: "Weather client",
+ * "Course data". A long first clause is a sentence, and treating it as a label
+ * would rename every feature to its opening clause, which is a different defect
+ * with the same cause. Word count separates the two better than length does:
+ * "The outgoing chef records what is prepped and what ran out" is short enough to
+ * pass any character limit and is plainly not a name.
+ */
+export function splitLabel(statement, limit = 60, words = 6) {
+  const text = String(statement ?? "").replace(/\s+/g, " ").trim();
+  if (!text) return { name: null, description: null };
+
+  // The dashes are written as escapes because the em dash character is refused in
+  // this project's own source, and this has to match one a person typed.
+  const separated = text.match(/^(.{2,}?)\s*(?:[.:]|\s[-\u2013\u2014])\s+(\S.*)$/);
+  if (separated) {
+    const label = separated[1].trim();
+    // A label holds no sentence-ending punctuation of its own, and a trailing
+    // "and" or "or" means the split landed inside a list rather than after a name.
+    if (
+      label.length <= limit &&
+      label.split(/\s+/).length <= words &&
+      !/[.!?:]/.test(label) &&
+      !/\b(and|or|but|with|for|to|of)$/i.test(label)
+    ) {
+      return { name: label, description: separated[2].trim() };
+    }
+  }
+  return { name: text.replace(/\s*\.$/, ""), description: null };
+}
+
 const normalize = (text) => String(text ?? "").toLowerCase().replace(/\s+/g, " ").trim();
 
 function clean(text) {

package/src/init/index.mjs

@@ -14,7 +14,7 @@ import { ensureDatabase, mutate, paths, query, create, patch, setStatus, recordA
 import { slugify, uniqueSlug } from "../model/ids.mjs";
 import { sanitizeExternal } from "../model/screening.mjs";
 import { CAPABILITY_AREAS, SYSTEM_TASK_CATEGORIES, count } from "../model/vocabulary.mjs";
-import { buildConceptMap, detectProjectKind, ingestSources, inspectEvidence, titleOf } from "./discovery.mjs";
+import { buildConceptMap, detectProjectKind, ingestSources, inspectEvidence, splitLabel, titleOf } from "./discovery.mjs";
 import {
   MATERIAL_AREAS,
   STACK_SLOTS,
@@ -22,6 +22,7 @@ import {
   questionCatalog,
   seedCapabilityAreas,
   seedModuleCompleteness,
+  settleAnsweredAreas,
   seedTaskCategories,
 } from "./questions.mjs";
 
@@ -104,7 +105,18 @@ export async function planInit(root, opts = {}) {
     warnings.push("The repository is larger than the inspection limit, so the evidence below is a sample rather than a census.");
   }
   if (detection.route === "adopt") {
-    warnings.push(`This repository already has documentation (profile ${detection.docsProfile}). Initialization is refused here; adoptProject leaves those files exactly where they are.`);
+    // Name a command, never a function. This said "adoptProject leaves those
+    // files exactly where they are", which is the internal function, so the
+    // refusal told the reader the remedy in a vocabulary they cannot type. It
+    // also stayed silent about the confidence, and a low-confidence detection is
+    // exactly the case where the reader should know to override it.
+    warnings.push([
+      `This repository already has documentation (profile ${detection.docsProfile}, ${detection.confidence} confidence).`,
+      "Initialization is refused here. Run superdev adopt, which leaves every existing file exactly where it is.",
+      detection.confidence === "low" || detection.confidence === "unknown"
+        ? "If those documents are input rather than a record of this project, for example a brief you are initializing from, run superdev init --adopt to say so and initialization will proceed."
+        : null,
+    ].filter(Boolean).join(" "));
   }
   if (existing.project) {
     warnings.push(`Project ${existing.project.id} already exists. Initialization will report what is present and create only what is missing.`);
@@ -334,6 +346,9 @@ export async function applyInit(root, opts = {}) {
         why_it_matters: descriptor.whyItMatters,
         recommendation: descriptor.recommendation,
         alternatives_json: JSON.stringify(descriptor.alternatives ?? []),
+        select_mode: descriptor.selectMode ?? "one",
+        recommended_json: JSON.stringify(descriptor.recommended ?? []),
+        recommendation_why: descriptor.recommendedWhy ?? null,
         status: "open",
         created_at: stamp,
       }, { projectId: created.project.id, activity: false });
@@ -357,6 +372,11 @@ export async function applyInit(root, opts = {}) {
         metadata: { questions: rows.map((r) => r.id) },
       });
     }
+    // A material area whose question was not raised because the project already
+    // answers it is settled here, in the same transaction that raised the rest.
+    // Otherwise it sits awaiting a decision that nobody was asked about, which is
+    // the one state this checklist exists to make impossible.
+    await settleAnsweredAreas(db, created.project.id, { at: stamp, actor });
     return rows;
   });
   record(7, questions.length ? "done" : "skipped", questions.length ? `${count(questions.length, "question")} raised: ${questions.map((q) => q.id).join(", ")}` : "every material area is answered by the repository or already asked");
@@ -372,15 +392,6 @@ export async function applyInit(root, opts = {}) {
   // Step 14 and 15 run outside every transaction: both open their own.
   // `notRun` rather than `skipped`: both generate and deriveAll return their own
   // `skipped` collection, and an empty array is still truthy.
-  let documents = { notRun: "documentation generation was turned off for this run" };
-  if (opts.generateDocs !== false) {
-    documents = await runQuietly(async () => {
-      const { generate } = await import("../docs/render.mjs");
-      return generate(at, { apply: true });
-    }, "documentation could not be generated");
-  }
-  record(14, outcomeOf(documents), documents.error ?? documents.notRun ?? summarize(documents));
-
   let tasks = { notRun: "task derivation was turned off for this run" };
   if (opts.deriveTasks !== false) {
     tasks = await runQuietly(async () => {
@@ -408,6 +419,25 @@ export async function applyInit(root, opts = {}) {
     metadata: { route: plan.route, questions: questions.length, discoveryItems: conceptMap.created.length, reused: created.reused },
   }));
 
+  // Documents are generated last, after every record and every event init will
+  // write, and the step is still reported as 14 because the brief's order is
+  // what a reader follows.
+  //
+  // It ran before task derivation and before the closing event, so a document
+  // was stamped with a revision lower than the project's own, and freshness
+  // compares the two. Every project therefore began its life reporting that its
+  // documentation was built from an older database revision, seconds after init
+  // wrote it, and no command the user could run would clear it. A gate that is
+  // red on arrival teaches the reader that red means nothing.
+  let documents = { notRun: "documentation generation was turned off for this run" };
+  if (opts.generateDocs !== false) {
+    documents = await runQuietly(async () => {
+      const { generate } = await import("../docs/render.mjs");
+      return generate(at, { apply: true });
+    }, "documentation could not be generated");
+  }
+  record(14, outcomeOf(documents), documents.error ?? documents.notRun ?? summarize(documents));
+
   return {
     root: at,
     project: created.project,
@@ -485,6 +515,34 @@ const titleFrom = (name) =>
  * with no goal candidates gets no goals, and the gap stays visible as the
  * unknown the concept map already wrote down.
  */
+/**
+ * The module a feature names, or nothing.
+ *
+ * Matching is on the module's name appearing in the feature's own words, which is
+ * how a brief actually signals ownership: "Read the previous shift's handover"
+ * belongs to "Handover", and says so. A single common word is not a signal, so
+ * short and structural words are ignored, and nothing matching means nothing is
+ * claimed.
+ */
+const STRUCTURAL = new Set(["the", "and", "for", "with", "data", "core", "app", "api", "web", "ui", "service", "client", "server", "module", "system"]);
+
+function ownerFor(modules, statement) {
+  const text = String(statement ?? "").toLowerCase();
+  let best = null;
+  for (const module of modules) {
+    const words = String(module.name).toLowerCase().split(/[^a-z0-9]+/)
+      .filter((word) => word.length > 3 && !STRUCTURAL.has(word));
+    if (!words.length) continue;
+    const hits = words.filter((word) => text.includes(word)).length;
+    // Every distinctive word of the module's name has to appear, so "Shot log"
+    // does not claim a feature that merely mentions a shot.
+    if (hits === words.length && (!best || words.length > best.words)) {
+      best = { module, words: words.length };
+    }
+  }
+  return best?.module ?? null;
+}
+
 async function draftProduct(root, project, { actor, at, milestones }) {
   const outcome = await mutate(root, async (db) => {
     const items = await db.all(
@@ -513,9 +571,13 @@ async function draftProduct(root, project, { actor, at, milestones }) {
 
     const modules = [];
     for (const [index, item] of moduleCandidates.entries()) {
-      const name = trim(item.statement.replace(/^Module candidate:\s*/, ""), 120);
+      const stated = item.statement.replace(/^Module candidate:\s*/, "");
+      // The name is the label the brief gave the part, and the sentence after it
+      // is what the part does. Both used to become the name.
+      const { name: label, description } = splitLabel(stated);
+      const name = trim(label, 120);
       if (!name) continue;
-      const module = await createModule(db, project, name, item.statement, index, at);
+      const module = await createModule(db, project, name, description ?? stated, index, at);
       if (!module) continue;
       modules.push(module);
       await convert(db, item, "module", module.id, at);
@@ -528,14 +590,27 @@ async function draftProduct(root, project, { actor, at, milestones }) {
     }
 
     const features = [];
-    for (const [index, item] of featureCandidates.entries()) {
-      const name = trim(item.statement, 120);
+    const unowned = [];
+    for (const item of featureCandidates) {
+      const { name: label } = splitLabel(item.statement);
+      const name = trim(label, 120);
       if (!name || !modules.length) continue;
       if (await db.get("SELECT 1 FROM features WHERE project_id = ? AND name = ?", project.id, name)) continue;
       const slug = await uniqueSlug(db, "features", project.id, name, "feature");
+      // Which module owns this feature is read from the feature, never from where
+      // it happened to sit in the list.
+      //
+      // It was `modules[index % modules.length]`, so feature n went to module n.
+      // Four features that were all screens landed on four different modules, one
+      // per supporting library, and the result was defensible only because the
+      // two lists happened to be the same length and in a compatible order.
+      // Reorder either list in the brief and the map becomes nonsense that reads
+      // as deliberate.
+      const matched = ownerFor(modules, item.statement);
+      const owner = matched ?? modules[0];
       const feature = await create(db, "feature", {
         project_id: project.id,
-        module_id: modules[index % modules.length].id,
+        module_id: owner.id,
         name,
         slug,
         purpose: item.statement,
@@ -547,9 +622,54 @@ async function draftProduct(root, project, { actor, at, milestones }) {
         updated_at: at,
       }, { projectId: project.id, activity: false });
       features.push(feature);
+      // An unmatched feature still needs a module, so it gets the first one and
+      // the guess is written down as a question rather than left to look decided.
+      if (!matched && modules.length > 1) unowned.push({ feature, owner });
       await convert(db, item, "feature", feature.id, at);
     }
 
+    // What the brief said is out of scope, stored where the product reads it.
+    //
+    // An "Out of scope" section became a discovery item of kind `exclusion` and
+    // stopped there. project_scope_items, the table the product document reads,
+    // was written by nothing at all, so the generated foundations said "None
+    // declared. An empty list here is a gap, not a statement" to somebody who had
+    // just declared three. The most valuable section of a brief was parsed,
+    // stored as a proposal, and contradicted in the same run.
+    const exclusions = items.filter((i) => i.kind === "exclusion");
+    const scope = [];
+    for (const [index, item] of exclusions.entries()) {
+      const { name: statement, description: why } = splitLabel(item.statement);
+      if (!statement) continue;
+      const already = await db.get(
+        "SELECT id FROM project_scope_items WHERE project_id = ? AND statement = ?", project.id, statement);
+      if (already) continue;
+      const row = await create(db, "project_scope_item", {
+        project_id: project.id,
+        direction: "non_goal",
+        statement,
+        why: why ?? item.provenance ?? null,
+        sequence: index,
+      }, { projectId: project.id, activity: false });
+      scope.push(row);
+      await convert(db, item, "project_scope_item", row.id, at);
+    }
+
+    // Every guess about ownership, asked rather than assumed.
+    for (const { feature, owner } of unowned) {
+      await create(db, "question", {
+        project_id: project.id,
+        scope_type: "feature",
+        scope_id: feature.id,
+        question: `Which module owns ${feature.name}?`,
+        why_it_matters: `The brief named ${modules.length} modules and none of them appears in this feature, so it was placed in ${owner.name} to have a home. Module ownership decides which test plan covers it and which documentation directory it is written to.`,
+        recommendation: `Leave it in ${owner.name} if that is right, or run superdev feature move ${feature.id} --module <MOD-id>.`,
+        alternatives_json: JSON.stringify(modules.filter((m) => m.id !== owner.id).map((m) => m.name)),
+        status: "open",
+        created_at: at,
+      }, { projectId: project.id, activity: false });
+    }
+
     const created = [];
     for (const [index, supplied] of (milestones ?? []).entries()) {
       created.push(await createMilestone(db, project, clean(supplied.name), clean(supplied.outcome), index, at));
@@ -564,24 +684,24 @@ async function draftProduct(root, project, { actor, at, milestones }) {
 
     for (const module of modules) await seedModuleCompleteness(db, module.id, { at });
 
-    if (goals.length || modules.length || features.length || created.length) {
+    if (goals.length || modules.length || features.length || created.length || scope.length) {
       await recordActivity(db, project.id, {
         type: "specification_changed",
-        summary: `Drafted ${count(goals.length, "goal")}, ${count(modules.length, "module")}, ${count(features.length, "feature")} and ${count(created.filter(Boolean).length, "milestone")} from the concept map`,
+        summary: `Drafted ${count(goals.length, "goal")}, ${count(modules.length, "module")}, ${count(features.length, "feature")}, ${count(created.filter(Boolean).length, "milestone")} and ${count(scope.length, "non-goal")} from the concept map`,
         actor,
-        metadata: { goals: goals.length, modules: modules.length, features: features.length, milestones: created.filter(Boolean).length },
+        metadata: { goals: goals.length, modules: modules.length, features: features.length, milestones: created.filter(Boolean).length, nonGoals: scope.length },
       });
     }
 
-    return { goals, modules, features, milestones: created.filter(Boolean) };
+    return { goals, modules, features, milestones: created.filter(Boolean), nonGoals: scope };
   });
 
-  const total = outcome.goals.length + outcome.modules.length + outcome.features.length;
+  const total = outcome.goals.length + outcome.modules.length + outcome.features.length + outcome.nonGoals.length;
   return {
     ...outcome,
     created: total > 0,
     detail: total
-      ? `${count(outcome.goals.length, "goal")}, ${count(outcome.modules.length, "module")}, ${count(outcome.features.length, "feature")}, ${count(outcome.milestones.length, "milestone")}`
+      ? `${count(outcome.goals.length, "goal")}, ${count(outcome.modules.length, "module")}, ${count(outcome.features.length, "feature")}, ${count(outcome.milestones.length, "milestone")}, ${count(outcome.nonGoals.length, "non-goal")}`
       : "the concept map held no candidates to convert, so nothing was invented to fill the gap",
   };
 }

package/src/init/questions.mjs

@@ -42,6 +42,9 @@ const MATERIAL = [
       "Give the outcome now and the measure once the first feature is real",
       "Declare the project exploratory, with no success measure yet",
     ],
+    selectMode: "one",
+    recommended: ["Give the outcome now and the measure once the first feature is real"],
+    recommendedWhy: "An outcome with no measure is still worth recording, and the measure is easier to name once one real feature exists. Declaring the project exploratory is honest but leaves readiness unable to report better than unknown.",
     ifDeferred: "Goals and milestones stay unmeasurable and readiness can never report better than unknown.",
   },
   {
@@ -55,6 +58,9 @@ const MATERIAL = [
       "Several roles, data shared",
       "Several roles with per-account separation (multi-tenant)",
     ],
+    selectMode: "one",
+    recommended: ["One role, all data shared"],
+    recommendedWhy: "It is the only one of the three that can be widened later without reworking every query. Separation added early costs a column; separation added late costs every surface at once, so this is the cheap direction to be wrong in.",
     ifDeferred: "Authorization is designed after the data model, which is the most expensive order to do it in.",
   },
   {
@@ -64,6 +70,10 @@ const MATERIAL = [
       "The delivery shape decides whether surfaces, UI actions and accessibility are part of the specification at all, or deliberately not applicable.",
     recommendation: "Name the one surface the first user will touch. A second one can be added when it exists.",
     alternatives: ["A web application", "A command line tool", "An API or library only", "An existing host application"],
+    // No recommendation. Nothing about a product in general makes one of these
+    // likelier, and a tag with no reason behind it is an instruction wearing a
+    // recommendation's clothes.
+    selectMode: "one",
     ifDeferred: "Surface and UI-action specifications cannot be started, so a whole layer of the product has no home.",
   },
   {
@@ -73,6 +83,7 @@ const MATERIAL = [
       "A shared server turns authentication, authorization and data ownership from optional into mandatory, and turns a local tool into an operated service.",
     recommendation: "Say whether anything runs outside the user's own machine. If nothing does, several capability areas become genuinely not applicable.",
     alternatives: ["Local only", "A single service", "Several services with separate ownership"],
+    selectMode: "one",
     ifDeferred: "Backend boundaries, authentication and operational response are all left undecided together.",
   },
   {
@@ -82,6 +93,9 @@ const MATERIAL = [
       "A contract with an outside caller cannot be changed quietly. That single fact decides versioning, error contracts and how much of the specification is public.",
     recommendation: "Assume no external caller until one exists. Declare it the moment one does.",
     alternatives: ["No external caller", "An internal client only", "A published, versioned public API"],
+    selectMode: "one",
+    recommended: ["No external caller"],
+    recommendedWhy: "A contract with an outside caller cannot be withdrawn quietly, so it is worth declaring only when one actually exists. Nothing is lost by declaring it the day it does.",
     ifDeferred: "An internal shape becomes a public contract by accident, which is the most expensive kind of accident.",
   },
   {
@@ -91,6 +105,7 @@ const MATERIAL = [
       "Sessions, tokens and the enforcement point for every permission hang off this answer, and retrofitting identity touches every route.",
     recommendation: "If anything is per-user or private, decide identity now rather than after the first data model.",
     alternatives: ["No sign in", "Identity from an existing provider", "Identity issued by this product"],
+    selectMode: "one",
     ifDeferred: "Every permission question gets deferred with it, and the data model is designed without an owner column.",
   },
   {
@@ -100,6 +115,7 @@ const MATERIAL = [
       "Data ownership decides the store, the retention rules, the backup posture and whether deletion is a real feature or a database statement.",
     recommendation: "Name the one or two things the product is the authority on. Say whether losing them is an inconvenience or a catastrophe.",
     alternatives: ["Nothing durable yet", "Local data only", "Shared durable data with a recovery expectation"],
+    selectMode: "one",
     ifDeferred: "Entities are invented per feature and the same fact ends up stored in two places.",
   },
   {
@@ -109,6 +125,9 @@ const MATERIAL = [
       "Every integration adds an authentication approach, a failure behavior and an environment to configure. Discovering one late reopens the architecture.",
     recommendation: "List the services you already know about, even the obvious ones. An empty list is a fine answer and is recorded as one.",
     alternatives: ["None", "Payment or billing", "An email or messaging provider", "A model or inference provider"],
+    // Several of these are true at once on most products, and a question that
+    // forces one answer gets a wrong one rather than an incomplete one.
+    selectMode: "many",
     ifDeferred: "Integration failure behavior is invented at the moment of the first outage.",
   },
   {
@@ -118,6 +137,9 @@ const MATERIAL = [
       "Compliance is only specified when it is declared. Declaring it late means auditing work that is already shipped, which is the expensive direction.",
     recommendation: "Answer no unless you can name the regime. A named regime turns retention, deletion and audit into required specification.",
     alternatives: ["No regulated data", "Personal data under a privacy regime", "Payment or health data"],
+    selectMode: "many",
+    recommended: ["No regulated data"],
+    recommendedWhy: "Compliance is specified only when it is declared, and a regime nobody can name is not one. Naming one turns retention, deletion and audit into required specification, so this is worth answering yes to only deliberately.",
     ifDeferred: "Retention and deletion are designed as convenience features and have to be rebuilt as obligations.",
   },
   {
@@ -127,6 +149,9 @@ const MATERIAL = [
       "Superdev refuses to store a credential anywhere, so it needs to know where secrets do live before it can specify configuration honestly.",
     recommendation: "Name the environments you will really have. Two is usually right; one is a valid answer for a local tool.",
     alternatives: ["Local only", "Local and production", "Local, staging and production"],
+    selectMode: "one",
+    recommended: ["Local and production"],
+    recommendedWhy: "Two environments is what most products actually have, and configuration specified against environments that do not exist diverges from the real ones. One is a valid answer for a local tool.",
     ifDeferred: "Configuration is specified per feature and diverges between environments before anybody notices.",
   },
 ];
@@ -397,7 +422,7 @@ export async function materialQuestions(db, projectId) {
     const area = byArea.get(entry.area);
     // No seeded row yet means discovery has not run; the question still applies.
     if (area && area.state !== "awaiting_decision") return false;
-    if (entry.scopeId === "statement" && clean(project.statement)) return false;
+    if (ALREADY_ANSWERED[entry.area]?.(project)) return false;
     return true;
   });
 
@@ -412,6 +437,76 @@ export async function materialQuestions(db, projectId) {
  * `planInit` prints the exact questions before a project row exists, so the
  * wording has to be derivable from the area name alone.
  */
+/**
+ * Material areas the project already answers, and what answers them.
+ *
+ * This used to be one inline condition inside the question filter, and the same
+ * fact was not consulted when the area was seeded. So supplying a purpose
+ * statement suppressed the purpose question while leaving the area awaiting a
+ * decision, and readiness then reported, at high severity, that the product's
+ * purpose was awaiting a decision with nobody asked about it. To somebody who had
+ * just stated it. Neither remedy the warning named was a command that existed.
+ *
+ * Holding the rule in one place is what lets `settleAnsweredAreas` agree with the
+ * filter by construction rather than by both being edited together.
+ */
+const ALREADY_ANSWERED = {
+  [AREA.purpose]: (project) => Boolean(clean(project?.statement)),
+};
+
+/** What the project's own record says, for an area that needs no question. */
+const ANSWERED_BY = {
+  [AREA.purpose]: (project) => ({
+    choice: clean(project.statement),
+    evidence: "stated at initialization",
+  }),
+};
+
+/**
+ * Settle every material area that needs no question because the project already
+ * answers it.
+ *
+ * Run after questions are raised, so "awaiting a decision with no question
+ * raised" is unreachable for these areas rather than merely unlikely. An area
+ * this cannot settle keeps its state and keeps its warning: the point is to close
+ * a hole, not to quieten the checklist.
+ */
+export async function settleAnsweredAreas(db, projectId, { at = nowIso(), actor = "superdev" } = {}) {
+  const project = await db.get("SELECT * FROM projects WHERE id = ?", projectId);
+  if (!project) return [];
+  const areas = await db.all(
+    `SELECT * FROM capability_areas
+      WHERE project_id = ? AND catalog = 'readiness'
+        AND state = 'awaiting_decision' AND question_id IS NULL`,
+    projectId,
+  );
+  const settled = [];
+  for (const area of areas) {
+    if (!ALREADY_ANSWERED[area.area]?.(project)) continue;
+    const answer = ANSWERED_BY[area.area]?.(project);
+    if (!answer?.choice) continue;
+    await patch(db, "capability_area", area.id, area.version, {
+      state: "specified",
+      choice: answer.choice,
+      evidence_ref: answer.evidence,
+      reason: null,
+      owner: null,
+      revisit_trigger: null,
+      consequence: null,
+    }, { projectId, activity: false, at });
+    settled.push({ id: area.id, area: area.area, evidence: answer.evidence });
+  }
+  if (settled.length) {
+    await recordActivity(db, projectId, {
+      type: "specification_changed",
+      actor,
+      summary: `${settled.length === 1 ? "1 capability area" : `${settled.length} capability areas`} settled from what the project already records`,
+      metadata: { areas: settled.map((a) => a.id) },
+    });
+  }
+  return settled;
+}
+
 export function questionCatalog(areas, { project = null } = {}) {
   const wanted = new Set(areas);
   return MATERIAL.filter((entry) => wanted.has(entry.area)).map((entry) => ({
@@ -425,6 +520,11 @@ export function questionCatalog(areas, { project = null } = {}) {
     whyItMatters: `${entry.whyItMatters} If this is deferred: ${entry.ifDeferred}`,
     recommendation: entry.recommendation,
     alternatives: entry.alternatives,
+    // How many of the options can be true at once, which options are recommended,
+    // and why. A question whose options nobody can select is a paragraph.
+    selectMode: entry.selectMode ?? "one",
+    recommended: entry.recommended ?? [],
+    recommendedWhy: entry.recommendedWhy ?? null,
     ifDeferred: entry.ifDeferred,
     revisitTrigger: REVISIT[entry.area] ?? "the next specification touches it",
     projectId: project?.id ?? null,
@@ -463,12 +563,12 @@ export async function answerQuestion(root, questionId, opts = {}) {
       question.project_id, questionId,
     );
 
-    if (unknown) return recordAssumption(db, { question, area, opts, at, actor, answeredBy });
-    return recordAnswer(db, { question, area, answer, at, actor, answeredBy });
+      if (unknown) return recordAssumption(db, { question, area, opts, at, actor, answeredBy });
+    return recordAnswer(db, { question, area, answer, inOwnWords: clean(opts.inOwnWords), at, actor, answeredBy });
   });
 }
 
-async function recordAnswer(db, { question, area, answer, at, actor, answeredBy }) {
+async function recordAnswer(db, { question, area, answer, inOwnWords = null, at, actor, answeredBy }) {
   const updated = await patch(db, "question", question.id, question.version, {
     answer,
     answered_by: answeredBy,
@@ -497,10 +597,20 @@ async function recordAnswer(db, { question, area, answer, at, actor, answeredBy
 
   // The two project-level questions write straight through to the field they
   // exist to fill, so an answer does not have to be copied by hand afterwards.
+  //
+  // What gets written through is the reader's own words when there are any. The
+  // purpose question's options are strategies for answering it ("give the outcome
+  // now and the measure once the first feature is real"), not the answer, so
+  // selecting one and writing the whole composed answer into projects.statement
+  // put advice where the product statement belongs. The question keeps the full
+  // answer, because what was chosen is part of the record; the field gets the
+  // sentence that was meant for it.
   let project = null;
   if (question.scope_type === "project" && ["statement", "problem"].includes(question.scope_id)) {
     const current = await db.get("SELECT * FROM projects WHERE id = ?", question.project_id);
-    project = await patch(db, "project", current.id, current.version, { [question.scope_id]: answer }, {
+    project = await patch(db, "project", current.id, current.version, {
+      [question.scope_id]: inOwnWords ?? answer,
+    }, {
       projectId: current.id, activity: false, at,
     });
   }