superdev-cli 0.1.2 → 0.2.1

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Superdev - tell it what you want to build, and it keeps the product map, documentation, decisions and status in step while specialist providers do the specialist work.",
-    "version": "0.1.2",
+    "version": "0.2.1",
     "homepage": "https://github.com/superdev-ai/superdev"
   },
   "plugins": [
@@ -13,7 +13,7 @@
       "name": "superdev",
       "source": "./",
       "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence - plus a self-contained visual dashboard. Routes specialist work to external providers and reports their readiness truthfully.",
-      "version": "0.1.2",
+      "version": "0.2.1",
       "author": {
         "name": "Rahul Retnan"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence, plus a self-contained visual dashboard. Routes specialist work to external providers and reports their readiness truthfully.",
   "author": {
     "name": "Rahul Retnan"
@@ -16,6 +16,6 @@
   "homepage": "https://github.com/superdev-ai/superdev",
   "repository": "https://github.com/superdev-ai/superdev",
   "requires": {
-    "cli": "0.1.2"
+    "cli": "0.2.1"
   }
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Describe a product in ordinary language and get a living map of goals, features, workflows, tasks, integrations, UI surfaces, decisions and evidence, plus a self-contained visual dashboard.",
   "author": {
     "name": "Rahul Retnan"
@@ -22,6 +22,6 @@
   "homepage": "https://github.com/superdev-ai/superdev",
   "repository": "https://github.com/superdev-ai/superdev",
   "requires": {
-    "cli": "0.1.2"
+    "cli": "0.2.1"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superdev-cli",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "type": "module",
   "description": "Local-first product-building control system for humans and coding agents.",
   "author": "Rahul Retnan",

package/src/cli.mjs

@@ -39,7 +39,7 @@ class Refusal extends Error {
 // Flags that carry no value. Everything else must be given one, so that
 // `--reason --apply` fails loudly instead of silently recording "true" as the
 // reason a task is blocked.
-const BOOLEAN = new Set(["apply", "json", "help", "all", "enabling", "end", "reports", "partial", "adopt", "dryRun", "resolve", "version", "noUpdateCheck", "updateCheck", "entry", "remove"]);
+const BOOLEAN = new Set(["apply", "json", "help", "all", "enabling", "end", "reports", "partial", "adopt", "dryRun", "resolve", "version", "noUpdateCheck", "updateCheck", "entry", "remove", "open"]);
 
 const camel = (name) => name.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
 
@@ -82,6 +82,14 @@ function parseArgs(argv) {
 
 const asList = (value) => (value === undefined ? [] : [].concat(value).map(String));
 
+/** A JSON column's value, or the fallback when it is absent or malformed. */
+const json = (value, fallback) => {
+  try {
+    const parsed = JSON.parse(value ?? "null");
+    return parsed ?? fallback;
+  } catch { return fallback; }
+};
+
 /** A path with its symlinks resolved, or the path itself when it cannot be. */
 const realpathOf = (path) => {
   try { return realpathSync(path); } catch { return path; }
@@ -188,6 +196,9 @@ Knowledge
   milestone update <id>     Rename it, restate it, or move its target date
   module record        Record a slice of the product
   module rename <id>   Rename a module, or restate what it owns
+  capability list      Readiness areas and stack slots, and what settled each
+  capability specify <id>   Record what was chosen for an area
+  capability not-applicable <id>  Record that an area does not apply, with why
   scope record         Record what the product will not do, and why
   scope list           What is in scope, out of scope, and a non-goal
   scope remove <id>    Take a scope line back out
@@ -231,6 +242,10 @@ Flags worth knowing
   feature specify --not <text>
                        What the feature deliberately does not do. Repeatable.
                        Its counterpart is --in, and --out stays global
+  ui | start --port <number>
+                       Serve on this port instead of 4317. Every project defaults
+                       to the same port, so the second one to start is refused
+                       and needs this
 
 Exit codes
   0 it worked, 1 something was found or refused, 2 the command was misused`;
@@ -746,6 +761,23 @@ const service = () => import("./service/manage.mjs");
 // later rename of one field cannot silently make `ui` claim nothing is running.
 const isRunning = (report) => report?.state === "running" || report?.running === true;
 
+/**
+ * The port to serve on, when the default one is taken.
+ *
+ * The refusal for a held port told the reader to start on another port and no
+ * command could. This is that flag, validated here rather than in two places:
+ * `ui` and `start` are the same decision made twice, and a port that is not a
+ * usable number has to be refused before a process is spawned against it.
+ */
+function portFrom(ctx) {
+  if (ctx.flags.port === undefined) return null;
+  const value = Number(ctx.flags.port);
+  if (!Number.isInteger(value) || value < 1024 || value > 65535) {
+    throw new UsageError(`--port takes a whole number between 1024 and 65535. ${JSON.stringify(String(ctx.flags.port))} is not one.`);
+  }
+  return value;
+}
+
 async function cmdUi(ctx) {
   const { serviceStatus, startService } = await service();
   const current = await serviceStatus(ctx.root);
@@ -758,21 +790,25 @@ async function cmdUi(ctx) {
       ]),
     };
   }
+  const port = portFrom(ctx);
   if (!ctx.apply) {
     return planned(current, "start the control center",
-      R.wrap("The control center is not running. Starting it opens one local process for this project and listens on the loopback address only."));
+      R.wrap(`The control center is not running. Starting it opens one local process for this project and listens on the loopback address only${port ? `, on port ${port}` : ""}.`));
   }
-  const started = await startService(ctx.root, { actor: ctx.actor });
+  const started = await startService(ctx.root, { actor: ctx.actor, ...(port ? { port } : {}) });
   return { data: { applied: true, service: started }, text: report(ctx, "Control center started", started) };
 }
 
 async function cmdStart(ctx) {
   const { startService, serviceStatus } = await service();
+  const port = portFrom(ctx);
   if (!ctx.apply) {
     return planned(await serviceStatus(ctx.root), "start the local service",
-      "Starting the service opens one local process for this project.");
+      port
+        ? `Starting the service opens one local process for this project, on port ${port}.`
+        : "Starting the service opens one local process for this project.");
   }
-  const started = await startService(ctx.root, { actor: ctx.actor });
+  const started = await startService(ctx.root, { actor: ctx.actor, ...(port ? { port } : {}) });
   return { data: { applied: true, service: started }, text: report(ctx, "Service started", started) };
 }
 
@@ -2325,41 +2361,63 @@ async function cmdMemorySearch(ctx) {
 
 // -------------------------------------------------------- questions, decisions
 
+/**
+ * Answer a question, from its options or in your own words.
+ *
+ * This wrote the answer and set the status itself, which is a third
+ * implementation of answering alongside the engine's and the control centre's.
+ * The engine's is the complete one: it settles the capability area the question
+ * belongs to, turns "I do not know" into a reversible assumption with a revisit
+ * trigger rather than a decision, and writes a project-level answer through to the
+ * field it exists to fill. This one did none of that, so the same question
+ * answered here and answered there left the project in different states. Both
+ * surfaces now call the engine.
+ */
 async function cmdQuestionAnswer(ctx) {
-  const id = requireWord(ctx.words, 2, "Say which question to answer: superdev question answer <id> --answer <text>.");
-  const answer = ctx.flags.answer !== undefined
-    ? String(ctx.flags.answer)
-    : ctx.words.slice(3).join(" ");
-  if (!answer) throw new UsageError("An answer needs text. Pass --answer <text>.");
+  const id = requireWord(ctx.words, 2, "Say which question to answer: superdev question answer <id> --answer <text> or --option <one of its options>.");
+  const chosen = asList(ctx.flags.option);
+  const typed = ctx.flags.answer !== undefined ? String(ctx.flags.answer) : ctx.words.slice(3).join(" ");
+  if (!chosen.length && !typed) {
+    throw new UsageError("An answer needs an option or some text. Pass --option <one of its options>, or --answer <text>. Run superdev question list to read the options.");
+  }
 
-  const { query, mutate, patch, setStatus } = await store();
+  const { query } = await store();
   const question = await query(ctx.root, (db) => db.get("SELECT * FROM questions WHERE id = ?", id));
   if (!question) throw new Refusal(`There is no question ${id}.`, "E_NOT_FOUND");
   if (question.status === "answered") {
     throw new Refusal(`${id} was already answered: ${question.answer}`, "E_ALREADY_ANSWERED");
   }
 
+  const offered = json(question.alternatives_json, []);
+  const unknown = chosen.filter((choice) => !offered.includes(choice));
+  if (unknown.length) {
+    throw new UsageError(`${id} does not offer ${unknown.map((u) => JSON.stringify(u)).join(", ")}. Its options are: ${offered.length ? offered.map((o) => JSON.stringify(o)).join(", ") : "none, so answer it in your own words with --answer"}.`);
+  }
+  if (question.select_mode !== "many" && chosen.length > 1) {
+    throw new UsageError(`${id} takes one answer, and ${chosen.length} options were given. Pick one, or write what you mean with --answer.`);
+  }
+
+  const answer = [chosen.join("; "), typed].filter(Boolean).join(". ");
+
   if (!ctx.apply) {
-    return planned({ id, answer }, "record it", R.stitch([
+    return planned({ id, answer, selected: chosen }, "record it", R.stitch([
       `Would answer ${id}: ${question.question}`,
       R.wrap(`Answer: ${answer}`, R.WIDTH, "  "),
       question.recommendation ? R.wrap(`The recommendation on file was: ${question.recommendation}`, R.WIDTH, "  ") : null,
     ]));
   }
 
-  const row = await mutate(ctx.root, async (db) => {
-    const current = await db.get("SELECT * FROM questions WHERE id = ?", id);
-    await patch(db, "question", id, current.version, {
-      answer,
-      answered_by: ctx.actor,
-      answered_at: nowIso(),
-    }, { projectId: current.project_id, actor: ctx.actor, activitySummary: `Answered ${id}: ${question.question}` });
-    return setStatus(db, "question", id, "answered", {
-      projectId: current.project_id, actor: ctx.actor, note: answer,
-    });
+  const { answerQuestion } = await import("./init/questions.mjs");
+  const out = await answerQuestion(ctx.root, id, {
+    answer, inOwnWords: typed || null, actor: ctx.actor, answeredBy: ctx.actor,
   });
-
-  return { data: { applied: true, question: row }, text: `${id} is answered.` };
+  if (out.changed === false) throw new Refusal(out.reason, "E_ALREADY_ANSWERED");
+  return {
+    data: { applied: true, question: out.question ?? { id }, selected: chosen },
+    text: R.wrap(out.area
+      ? `${id} is answered, and ${out.area.id} ${out.area.area} is settled by it, which is what readiness counts.`
+      : `${id} is answered.`),
+  };
 }
 
 async function cmdDecisionList(ctx) {
@@ -2610,6 +2668,69 @@ async function cmdFeatureCreate(ctx) {
   };
 }
 
+async function cmdCapabilitySpecify(ctx) {
+  const id = requireWord(ctx.words, 2, "Say which area: superdev capability specify <CAP-id> --choice \"<what was chosen>\".");
+  const { settleCapabilityArea } = await import("./product/authoring.mjs");
+  const out = await settleCapabilityArea(ctx.root, id, {
+    choice: requireFlag(ctx.flags, "choice", "Say what was chosen for this area."),
+    evidence: ctx.flags.evidence ?? null,
+    actor: ctx.actor, apply: ctx.apply,
+  });
+  if (!out.applied) {
+    return planned(out, "record it", R.wrap(`Would specify ${out.area}: ${out.choice}`));
+  }
+  return {
+    data: out,
+    text: R.wrap(`${id} ${out.area} is specified: "${out.choice}". It was ${R.status(out.was)}, and readiness now counts it as answered.`),
+  };
+}
+
+async function cmdCapabilityNotApplicable(ctx) {
+  const id = requireWord(ctx.words, 2, "Say which area: superdev capability not-applicable <CAP-id> --reason \"<why>\".");
+  const { settleCapabilityArea } = await import("./product/authoring.mjs");
+  const out = await settleCapabilityArea(ctx.root, id, {
+    notApplicable: true,
+    reason: requireFlag(ctx.flags, "reason", "Say why this area does not apply to this product."),
+    evidence: ctx.flags.evidence ?? null,
+    actor: ctx.actor, apply: ctx.apply,
+  });
+  if (!out.applied) {
+    return planned(out, "record it", R.wrap(`Would record ${out.area} as not applicable: ${out.reason}`));
+  }
+  return {
+    data: out,
+    // The reason is somebody's sentence and may not end in a full stop, so it is
+    // quoted rather than run into the next sentence.
+    text: R.wrap(`${id} ${out.area} is recorded as not applicable: "${out.reason}". A reason is required precisely so this stays different from an area nobody looked at.`),
+  };
+}
+
+async function cmdCapabilityList(ctx) {
+  const { capabilityList } = await import("./product/authoring.mjs");
+  const rows = await capabilityList(ctx.root, {
+    catalog: ctx.flags.catalog ? String(ctx.flags.catalog) : null,
+    unsettled: Boolean(ctx.flags.open),
+  });
+  if (!rows.length) {
+    return { data: { areas: [] }, text: R.wrap("No capability area matches. Superdev seeds them during init.") };
+  }
+  return {
+    data: { areas: rows },
+    text: R.stitch([
+      R.heading(`Capability areas (${rows.length})`),
+      R.table(["Id", "Area", "State", "What settled it"],
+        rows.map((a) => [
+          a.id,
+          a.area,
+          R.status(a.state),
+          a.choice ?? a.reason ?? "Nothing yet",
+        ])),
+      "",
+      "Settle one with superdev capability specify <id> --choice, or capability not-applicable <id> --reason.",
+    ]),
+  };
+}
+
 async function cmdScopeRecord(ctx) {
   const { recordScopeItem } = await import("./product/authoring.mjs");
   // --not is the same word here as in feature specify, and means the same thing.
@@ -3030,6 +3151,9 @@ const COMMANDS = {
   "feature goal": cmdFeatureGoal,
   "milestone update": cmdMilestoneUpdate,
   "module rename": cmdModuleRename,
+  "capability list": cmdCapabilityList,
+  "capability specify": cmdCapabilitySpecify,
+  "capability not-applicable": cmdCapabilityNotApplicable,
   "scope record": cmdScopeRecord,
   "scope remove": cmdScopeRemove,
   "scope list": cmdScopeList,

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/init/index.mjs

@@ -22,6 +22,7 @@ import {
   questionCatalog,
   seedCapabilityAreas,
   seedModuleCompleteness,
+  settleAnsweredAreas,
   seedTaskCategories,
 } from "./questions.mjs";
 
@@ -345,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 });
@@ -368,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");

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,
     });
   }