superdev-cli 0.1.0

package/src/model/vocabulary.mjs

@@ -0,0 +1,190 @@
+// The words the product uses. Data, not UI constants: categories and capability
+// areas are seeded as rows so a project can add its own.
+
+/** Brief section 7.4. Order is lifecycle order, used for board columns. */
+export const TASK_STATUSES = [
+  "draft", "ready", "in_progress", "in_review", "verifying",
+  "blocked", "paused", "complete", "cancelled", "superseded",
+];
+
+export const OPEN_TASK_STATUSES = TASK_STATUSES.filter(
+  (s) => !["complete", "cancelled", "superseded"].includes(s),
+);
+
+export const TERMINAL_TASK_STATUSES = ["complete", "cancelled", "superseded"];
+
+/** Human-facing label. Title Case, plain language, no internal vocabulary. */
+export const LABEL = {
+  draft: "Draft",
+  ready: "Ready",
+  in_progress: "In Progress",
+  in_review: "In Review",
+  verifying: "Verifying",
+  blocked: "Blocked",
+  paused: "Paused",
+  complete: "Complete",
+  cancelled: "Cancelled",
+  superseded: "Superseded",
+  planned: "Planned",
+  implemented: "Implemented",
+  deprecated: "Deprecated",
+  accepted: "Accepted",
+  proposed: "Proposed",
+  rejected: "Rejected",
+  specified: "Specified",
+  awaiting_decision: "Awaiting Decision",
+  not_applicable: "Not Applicable",
+  deferred: "Deferred",
+  met: "Met",
+  unmet: "Unmet",
+  unmeasured: "Unmeasured",
+  open: "Open",
+  filled: "Filled",
+  answered: "Answered",
+};
+
+export const titleCase = (value) =>
+  LABEL[value] ??
+  String(value ?? "")
+    .replace(/[_-]+/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+
+/**
+ * Brief section 7.3, plus the categories the derivation inputs in 11.1 actually
+ * produce. Seeded per project, and projects may add their own: these are a
+ * starting vocabulary, not a closed set.
+ *
+ * The later entries exist because derivation was otherwise forced to file real
+ * work under a category that did not describe it. Proving rollout and rollback
+ * is not Infrastructure, and a surface with its actions is not a generic
+ * Feature.
+ */
+export const SYSTEM_TASK_CATEGORIES = [
+  "Feature", "Improvement", "Bug", "Refactor", "Investigation", "Documentation",
+  "Integration", "Migration", "Infrastructure", "Security", "Quality", "Backlog",
+  "Design", "Testing", "Performance", "Accessibility", "Observability",
+  "Data", "Release", "Compliance", "Chore",
+];
+
+/**
+ * One line per category, so the interface can say what a category means rather
+ * than assuming everyone reads the same meaning into a single word. Shown in
+ * the category picker and in filter help.
+ */
+export const TASK_CATEGORY_MEANINGS = {
+  Feature: "New product behavior somebody asked for.",
+  Improvement: "Existing behavior made better without changing what it is.",
+  Bug: "Behavior that does not match what was accepted.",
+  Refactor: "Internal change with no change in behavior.",
+  Investigation: "Finding something out before deciding what to build.",
+  Documentation: "Keeping the written record in step with the product.",
+  Integration: "Work at the boundary with something outside this product.",
+  Migration: "Moving data or schema from one shape to another.",
+  Infrastructure: "The ground the product runs on.",
+  Security: "Protecting the product, its data and the people in it.",
+  Quality: "Work that raises confidence rather than adding behavior.",
+  Backlog: "Agreed as worth doing, not yet scheduled.",
+  Design: "Surfaces, actions and how the product presents itself.",
+  Testing: "Product tests derived from the accepted test plan.",
+  Performance: "Meeting a declared speed or capacity target.",
+  Accessibility: "Making the product operable by everyone who uses it.",
+  Observability: "Signals that prove the product is working in the open.",
+  Data: "Modelling the entities and relationships the product owns.",
+  Release: "Getting the work out, and being able to take it back.",
+  Compliance: "Obligations under a regime this project has declared.",
+  Chore: "Routine upkeep that keeps the project healthy.",
+};
+
+/** Brief section 8.2. Every area is answered or explicitly not applicable. */
+export const CAPABILITY_AREAS = [
+  "Product purpose and success criteria",
+  "Users, roles, permissions and tenancy",
+  "Frontend delivery shape",
+  "Navigation and information architecture",
+  "Design system and accessibility",
+  "Backend boundaries and service responsibilities",
+  "API style and public contracts",
+  "Authentication and session lifecycle",
+  "Authorization enforcement",
+  "Database and data ownership",
+  "Data migrations and rollback",
+  "File or object storage",
+  "Search and indexing",
+  "Real-time behavior",
+  "Offline behavior and conflict handling",
+  "Background jobs and scheduling",
+  "Events and webhooks",
+  "External integrations",
+  "Notifications",
+  "Rate limiting and abuse controls",
+  "Security and privacy",
+  "Compliance",
+  "Observability and operational response",
+  "Performance and capacity targets",
+  "Environments and secret management",
+  "Continuous integration and delivery",
+  "Infrastructure and deployment",
+  "Backups, recovery, retention and deletion",
+  "Product analytics",
+  "Testing strategy for the product",
+  "Release and rollback",
+];
+
+/** Brief section 9.3, the twenty-step module loop. */
+export const MODULE_STEPS = [
+  "Pages and surfaces", "UI composition", "Actions", "API surface", "Data",
+  "End-to-end wiring", "State machines", "Events", "Edge cases", "UI states",
+  "Telemetry", "Accessibility", "Internationalization", "Feature flags",
+  "Responsive behavior", "User-facing copy", "URL state and deep links",
+  "Performance", "Discoverability and SEO", "Compliance and product tests",
+];
+
+/** Docs edge-case categories. Each is specified or deliberately not applicable. */
+export const EDGE_CASE_CATEGORIES = [
+  "empty_states", "boundary_values", "invalid_input", "permission_boundaries",
+  "state_machine_violations", "concurrent_actions", "ordering", "duplication",
+  "network_failure", "dependency_failure", "slow_paths", "time",
+  "data_migration_states", "recovery", "limits_and_quotas",
+  "multi_device_session", "offline_degraded", "localization",
+  "platform_variance", "versioning", "deletion_semantics", "consistency",
+  "privacy_lifecycle", "auditability",
+];
+
+export const ACTIVITY_EVENT_TYPES = [
+  "task_created", "task_claimed", "task_started", "task_updated", "task_blocked",
+  "task_unblocked", "verification_attached", "task_completed", "task_reopened",
+  "task_released", "task_cancelled", "decision_created", "decision_transitioned",
+  "specification_changed", "code_changed", "documentation_generated",
+  "documentation_proposal_raised", "documentation_proposal_resolved",
+  "session_started", "session_compacted", "session_handed_off", "session_ended",
+  "project_initialized", "scope_changed", "tasks_derived",
+];
+
+export const SPEC_DEPTHS = ["microspec", "standard", "full"];
+
+/** What each depth must carry before it can be accepted. Brief section 9.2. */
+export const DEPTH_REQUIREMENTS = {
+  microspec: ["purpose", "user_statement", "scope", "flow", "acceptance_criteria", "edge_cases"],
+  standard: ["purpose", "user_statement", "scope", "flow", "acceptance_criteria", "edge_cases",
+             "surfaces", "api_or_data", "workflow", "observability", "test_plan"],
+  full: ["purpose", "user_statement", "scope", "flow", "acceptance_criteria", "edge_cases",
+         "surfaces", "api_or_data", "workflow", "observability", "test_plan",
+         "decision", "migration_or_rollback", "security_privacy"],
+};
+
+/**
+ * `3 features`, `1 feature`, `2 categories`.
+ *
+ * The one place a count meets its noun. Superdev used to write `feature(s)`
+ * everywhere, which is a machine hedging about grammar it already has the
+ * number for, and it produced sentences no person would write: "1 verification
+ * record(s) are out of date", where the count is singular and the verb is not.
+ * Irregular plurals are passed in rather than guessed, because "criterion(s)"
+ * was the other half of the same problem and the plural is "criteria".
+ */
+export function count(n, singular, many = `${singular}s`) {
+  return `${n} ${n === 1 ? singular : many}`;
+}
+
+/** The same choice without the number, for a verb that has to agree with it. */
+export const agrees = (n, one, many) => (n === 1 ? one : many);

package/src/product/assumptions.mjs

@@ -0,0 +1,120 @@
+// Reversible answers, and what would make each worth revisiting.
+//
+// Section 8.4 says "I do not know" is a valid answer, that Superdev may
+// recommend a reversible assumption, and that it must record the assumption
+// and its review trigger. Without a place to put one, an assumption becomes an
+// undocumented guess: nobody knows it was assumed rather than decided, and
+// nobody knows when to check it again.
+//
+// The review trigger is required for exactly that reason. An assumption with no
+// trigger is never reviewed and quietly hardens into a fact nobody chose.
+
+import { create, mutate, query, setStatus } from "../db/store.mjs";
+import { assertStorable } from "../model/screening.mjs";
+
+export const E = { NOT_FOUND: "E_NOT_FOUND", INVALID: "E_INVALID" };
+
+export class AssumptionError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "AssumptionError";
+    this.code = code;
+  }
+}
+
+export const ASSUMPTION_STATUSES = ["holding", "confirmed", "overturned", "expired"];
+
+/**
+ * Record an assumption.
+ *
+ * Three things are required and each earns its place: the statement, because
+ * an unstated assumption cannot be checked; why it was assumed rather than
+ * decided, because that is what separates it from a decision nobody wrote down;
+ * and the review trigger, because without one it is never revisited.
+ */
+export async function recordAssumption(root, input = {}) {
+  const statement = String(input.statement ?? "").trim();
+  const whyAssumed = String(input.whyAssumed ?? "").trim();
+  const reviewTrigger = String(input.reviewTrigger ?? "").trim();
+
+  if (!statement) throw new AssumptionError(E.INVALID, "An assumption needs its statement.");
+  if (!whyAssumed) {
+    throw new AssumptionError(E.INVALID,
+      "Say why this is assumed rather than decided. Without that it reads as a decision nobody recorded.");
+  }
+  if (!reviewTrigger) {
+    throw new AssumptionError(E.INVALID,
+      "An assumption needs its review trigger. Without one nobody knows when to check it, and it hardens into a fact nobody chose.");
+  }
+
+  return mutate(root, async (db) => {
+    const project = await db.get("SELECT id FROM projects LIMIT 1");
+    if (!project) throw new AssumptionError(E.NOT_FOUND, "There is no project to record an assumption against.");
+
+    if (input.questionId) {
+      const q = await db.get("SELECT id FROM questions WHERE id = ?", input.questionId);
+      if (!q) throw new AssumptionError(E.NOT_FOUND, `There is no question ${input.questionId}.`);
+    }
+
+    return create(db, "assumption", {
+      project_id: project.id,
+      statement: assertStorable("statement", statement),
+      why_assumed: assertStorable("why_assumed", whyAssumed),
+      review_trigger: assertStorable("review_trigger", reviewTrigger),
+      consequence_if_wrong: input.consequenceIfWrong
+        ? assertStorable("consequence_if_wrong", String(input.consequenceIfWrong)) : null,
+      scope_type: input.scopeType ?? null,
+      scope_id: input.scopeId ?? null,
+      question_id: input.questionId ?? null,
+      status: "holding",
+    }, {
+      projectId: project.id,
+      actor: input.actor ?? "superdev",
+      sessionId: input.sessionId ?? null,
+      activityType: "assumption_recorded",
+      activitySummary: `Assumption recorded: ${statement}`.slice(0, 200),
+    });
+  });
+}
+
+/**
+ * Resolve an assumption, saying what it turned out to be.
+ *
+ * Confirmed and overturned are both resolutions worth recording. An overturned
+ * assumption that leaves no trace is how a project forgets that it once
+ * believed something and acted on it.
+ */
+export async function resolveAssumption(root, assumptionId, { to, resolution, actor = "superdev" } = {}) {
+  if (!ASSUMPTION_STATUSES.includes(to)) {
+    throw new AssumptionError(E.INVALID,
+      `"${to}" is not an assumption status. Use one of: ${ASSUMPTION_STATUSES.join(", ")}.`);
+  }
+  if (to !== "holding" && !String(resolution ?? "").trim()) {
+    throw new AssumptionError(E.INVALID,
+      "Say what it turned out to be. A resolved assumption with no resolution loses the answer it was standing in for.");
+  }
+
+  return mutate(root, async (db) => {
+    const row = await db.get("SELECT * FROM assumptions WHERE id = ?", assumptionId);
+    if (!row) throw new AssumptionError(E.NOT_FOUND, `There is no assumption ${assumptionId}.`);
+    if (row.status === to) {
+      throw new AssumptionError(E.INVALID, `${assumptionId} is already ${to}.`);
+    }
+    await db.run(
+      "UPDATE assumptions SET resolution = ?, resolved_by = ?, resolved_at = ? WHERE id = ?",
+      resolution ? assertStorable("resolution", String(resolution)) : null,
+      actor, new Date().toISOString(), assumptionId,
+    );
+    return setStatus(db, "assumption", assumptionId, to, { actor, reason: resolution ?? null });
+  });
+}
+
+/** Every assumption, the ones still holding first because those are live. */
+export async function listAssumptions(root, { status = null } = {}) {
+  return query(root, (db) => db.all(
+    `SELECT * FROM assumptions
+      ${status ? "WHERE status = ?" : ""}
+      ORDER BY CASE status WHEN 'holding' THEN 0 ELSE 1 END, created_at DESC`,
+    ...(status ? [status] : []),
+  ));
+}

package/src/product/changes.mjs

@@ -0,0 +1,180 @@
+// Recording what moved in accepted scope, and why.
+//
+// Section 6.2 says a Change must record the affected records and the reason,
+// and 14.2 says changes must preserve audit history. An activity event records
+// that something happened; a change records that accepted scope moved, which is
+// the claim a reader comes back for months later when asking why the product is
+// not what the plan said.
+//
+// A change is append-only, enforced by a trigger. Recording one wrongly is
+// corrected by recording another that says so, never by editing the first.
+
+import { create, mutate, query } from "../db/store.mjs";
+import { assertStorable } from "../model/screening.mjs";
+
+export const E = {
+  NOT_FOUND: "E_NOT_FOUND",
+  INVALID: "E_INVALID",
+};
+
+export class ChangeError extends Error {
+  constructor(code, message, detail = {}) {
+    super(message);
+    this.name = "ChangeError";
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+/** The kinds a change can be, in the vocabulary the schema accepts. */
+export const CHANGE_TYPES = [
+  "scope_added", "scope_removed", "behavior_changed",
+  "contract_changed", "correction", "scope_changed",
+];
+
+const asList = (value) =>
+  (value === null || value === undefined ? [] : [].concat(value))
+    .map((v) => String(v).trim()).filter(Boolean);
+
+/**
+ * Record a change to accepted scope or behaviour.
+ *
+ * A summary and a reason are both required. A change with no reason is an event
+ * log entry wearing a different name, and the reason is the whole point: it is
+ * what tells the next reader whether the product drifted or was steered.
+ *
+ * Targets are required for the same reason. "Something changed" is not a record
+ * anyone can act on, so a change names what it moved.
+ */
+export async function recordChange(root, input = {}) {
+  const summary = String(input.summary ?? "").trim();
+  const reason = String(input.reason ?? "").trim();
+  if (!summary) {
+    throw new ChangeError(E.INVALID, "A change needs a summary saying what moved.");
+  }
+  if (!reason) {
+    throw new ChangeError(E.INVALID,
+      "A change needs its reason. Without it nobody can tell later whether the product was steered or drifted.");
+  }
+
+  const changeType = String(input.changeType ?? "scope_changed");
+  if (!CHANGE_TYPES.includes(changeType)) {
+    throw new ChangeError(E.INVALID,
+      `"${changeType}" is not a kind of change. Use one of: ${CHANGE_TYPES.join(", ")}.`);
+  }
+
+  const targets = asList(input.targets);
+  if (targets.length === 0) {
+    throw new ChangeError(E.INVALID,
+      "A change names what it moved. Pass at least one target as <type>:<id>, for example feature:FEAT-0001.");
+  }
+
+  const parsed = targets.map((t) => {
+    const [type, id, ...rest] = t.split(":");
+    if (!type || !id) {
+      throw new ChangeError(E.INVALID,
+        `"${t}" is not a target. Write it as <type>:<id>, for example feature:FEAT-0001.`);
+    }
+    return { type, id, what: rest.join(":") || null };
+  });
+
+  return mutate(root, async (db) => {
+    const project = await db.get("SELECT id FROM projects LIMIT 1");
+    if (!project) throw new ChangeError(E.NOT_FOUND, "There is no project to record a change against.");
+
+    // A target that does not exist makes the audit trail point at nothing, and
+    // a dangling reference is the failure the record links validator exists to
+    // catch. Better to refuse than to write one.
+    for (const t of parsed) {
+      const table = TARGET_TABLES[t.type];
+      if (!table) {
+        throw new ChangeError(E.INVALID,
+          `"${t.type}" is not a kind of record this can point at. Known kinds: ${Object.keys(TARGET_TABLES).join(", ")}.`);
+      }
+      const found = await db.get(`SELECT 1 AS ok FROM ${table} WHERE id = ?`, t.id);
+      if (!found) throw new ChangeError(E.NOT_FOUND, `There is no ${t.type} ${t.id}.`);
+    }
+
+    const row = await create(db, "change", {
+      project_id: project.id,
+      summary: assertStorable("summary", summary),
+      reason: assertStorable("reason", reason),
+      change_type: changeType,
+      requested_by: input.requestedBy ?? null,
+      decided_by: input.decidedBy ?? input.actor ?? null,
+      decision_id: input.decisionId ?? null,
+      task_id: input.taskId ?? null,
+      session_id: input.sessionId ?? null,
+      status: "recorded",
+    }, {
+      projectId: project.id,
+      actor: input.actor ?? "superdev",
+      sessionId: input.sessionId ?? null,
+      taskId: input.taskId ?? null,
+      activityType: "scope_changed",
+      activitySummary: `Change recorded: ${summary}`.slice(0, 200),
+    });
+
+    for (const t of parsed) {
+      await db.run(
+        "INSERT OR IGNORE INTO change_targets (change_id, target_type, target_id, what_changed) VALUES (?, ?, ?, ?)",
+        row.id, t.type, t.id, t.what ? assertStorable("what_changed", t.what) : null,
+      );
+    }
+
+    row.targets = parsed;
+    return row;
+  });
+}
+
+/** Where each target type resolves, so a change cannot point at nothing. */
+const TARGET_TABLES = {
+  goal: "goals",
+  milestone: "milestones",
+  module: "modules",
+  feature: "features",
+  workflow: "workflows",
+  workflow_step: "workflow_steps",
+  surface: "surfaces",
+  api_operation: "api_operations",
+  api_service: "api_services",
+  data_entity: "data_entities",
+  integration: "integrations",
+  task: "tasks",
+  decision: "decisions",
+  nfr: "non_functional_requirements",
+  acceptance_criterion: "feature_acceptance_criteria",
+  test_plan: "test_plans",
+};
+
+/** Every change, newest first, each carrying what it moved. */
+export async function listChanges(root, { limit = 50, targetType = null, targetId = null } = {}) {
+  return query(root, async (db) => {
+    const filtered = targetType && targetId;
+    const rows = await db.all(
+      `SELECT c.* FROM changes c
+        ${filtered ? "JOIN change_targets t ON t.change_id = c.id AND t.target_type = ? AND t.target_id = ?" : ""}
+        ORDER BY c.created_at DESC, c.id DESC LIMIT ?`,
+      ...(filtered ? [targetType, targetId, limit] : [limit]),
+    );
+    for (const row of rows) {
+      row.targets = await db.all(
+        "SELECT target_type, target_id, what_changed FROM change_targets WHERE change_id = ?", row.id);
+    }
+    return rows;
+  });
+}
+
+/** One change in full. */
+export async function showChange(root, changeId) {
+  return query(root, async (db) => {
+    const row = await db.get("SELECT * FROM changes WHERE id = ?", changeId);
+    if (!row) throw new ChangeError(E.NOT_FOUND, `There is no change ${changeId}.`);
+    row.targets = await db.all(
+      "SELECT target_type, target_id, what_changed FROM change_targets WHERE change_id = ?", changeId);
+    if (row.decision_id) {
+      row.decision = await db.get("SELECT id, title, status FROM decisions WHERE id = ?", row.decision_id);
+    }
+    return row;
+  });
+}

package/src/product/test-plans.mjs

@@ -0,0 +1,183 @@
+// The agreed verification strategies, and whether anyone has run them.
+//
+// Section 9.3 makes the accepted test plan a completion condition. A plan is
+// therefore not a document: it is a gate, and a gate needs a way to be opened.
+// Two ways exist here, and the difference between them is the point.
+//
+// A plan whose how_to_run is a command this project can run unattended is run,
+// and the result recorded is whatever the run produced. Nothing asserts that it
+// passed. A plan whose how_to_run is a journey, such as opening every area of
+// the control centre or restoring a backup and checking what came back, cannot
+// be run by a script, and pretending otherwise would put a self issued pass
+// where an observation belongs. Those are recorded by whoever performed them,
+// and say who and what they saw.
+
+import { create, mutate, query } from "../db/store.mjs";
+import { refuseReason, runCheck } from "../verify/index.mjs";
+
+export const E = {
+  NOT_FOUND: "E_NOT_FOUND",
+  NOT_ACCEPTED: "E_PLAN_NOT_ACCEPTED",
+  NOT_RUNNABLE: "E_PLAN_NOT_RUNNABLE",
+};
+
+export class PlanError extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = "PlanError";
+    this.code = code;
+    if (detail !== undefined) this.detail = detail;
+  }
+}
+
+/** How many current passing runs a plan carries, as a subquery every read wants. */
+const PASSING_RUNS = `(SELECT COUNT(*) FROM verification_evidence e
+   WHERE e.test_plan_id = p.id AND e.status = 'current' AND e.result = 'pass'
+     AND (e.last_check_result IS NULL OR e.last_check_result = 'pass'))`;
+
+export async function listPlans(root) {
+  const rows = await query(root, (db) => db.all(
+    `SELECT p.id, p.name, p.strategy, p.how_to_run, p.passing_condition, p.status,
+            p.feature_id, p.module_id, p.workflow_id, ${PASSING_RUNS} AS passing_runs
+       FROM test_plans p ORDER BY p.id`));
+  return rows.map((p) => ({
+    ...p,
+    passing_runs: Number(p.passing_runs),
+    satisfied: Number(p.passing_runs) > 0,
+    // Whether this plan can be closed by a command or only by a person, said
+    // once here so no caller has to work it out again.
+    runnable: refuseReason(p.how_to_run) === null,
+    why_not_runnable: refuseReason(p.how_to_run),
+  }));
+}
+
+export async function showPlan(root, id) {
+  const found = await query(root, async (db) => ({
+    plan: await db.get(
+      `SELECT p.*, ${PASSING_RUNS} AS passing_runs FROM test_plans p WHERE p.id = ?`, id),
+    runs: await db.all(
+      `SELECT id, task_id, summary, result, reference, recorded_by, recorded_at,
+              last_check_result, last_checked_at
+         FROM verification_evidence WHERE test_plan_id = ? ORDER BY recorded_at DESC LIMIT 20`, id),
+  }));
+  if (!found.plan) {
+    throw new PlanError(E.NOT_FOUND, `There is no test plan ${id}. Run superdev test-plan list to see them.`);
+  }
+  const p = found.plan;
+  return {
+    ...found,
+    plan: {
+      ...p,
+      passing_runs: Number(p.passing_runs),
+      satisfied: Number(p.passing_runs) > 0,
+      runnable: refuseReason(p.how_to_run) === null,
+      why_not_runnable: refuseReason(p.how_to_run),
+    },
+  };
+}
+
+async function acceptedPlan(db, id) {
+  const plan = await db.get("SELECT * FROM test_plans WHERE id = ?", id);
+  if (!plan) throw new PlanError(E.NOT_FOUND, `There is no test plan ${id}. Run superdev test-plan list to see them.`);
+  if (plan.status !== "accepted") {
+    throw new PlanError(E.NOT_ACCEPTED,
+      `${id} is ${plan.status.replace(/_/g, " ")}, not accepted. A plan nobody has agreed to cannot satisfy anything.`);
+  }
+  return plan;
+}
+
+/**
+ * Write one run of a plan into the evidence table.
+ *
+ * A new run of the same plan supersedes the previous one rather than joining
+ * it. Runs of a plan are not separate claims that accumulate: they are the same
+ * claim, answered again. Left as they were, a plan that failed on Tuesday and
+ * passed on Wednesday would report both forever, and every reader would have to
+ * work out which one still counts.
+ *
+ * The superseded rows stay readable, so the failure is still part of the
+ * record. Nothing is deleted, and `test-plan show` lists them in order.
+ */
+async function recordEvidence(db, plan, { summary, result, reference, checkCommand, taskId, actor, sessionId }) {
+  await db.run(
+    `UPDATE verification_evidence SET status = 'superseded'
+      WHERE test_plan_id = ? AND status = 'current'`,
+    plan.id,
+  );
+  return create(db, "verification_evidence", {
+    project_id: plan.project_id,
+    task_id: taskId,
+    feature_id: plan.feature_id,
+    test_plan_id: plan.id,
+    evidence_type: checkCommand ? "command_output" : "manual_check",
+    summary,
+    reference,
+    result,
+    check_command: checkCommand,
+    last_checked_at: checkCommand ? new Date().toISOString() : null,
+    last_check_result: checkCommand ? result : null,
+    recorded_by: actor,
+    recorded_at: new Date().toISOString(),
+    status: "current",
+  }, {
+    projectId: plan.project_id, actor, sessionId, taskId,
+    activityType: "verification_attached",
+    activitySummary: `${plan.id} ${result === "pass" ? "ran and passed" : result === "fail" ? "ran and failed" : "was inconclusive"}: ${summary}`.slice(0, 200),
+  });
+}
+
+/**
+ * Run a plan's recorded command and record what it showed.
+ *
+ * The result comes from the exit status, so a failing run is recorded as
+ * failing. That is the only version of this worth having: one that recorded a
+ * pass regardless would turn the completion gate into a formality.
+ */
+export async function runPlan(root, id, { actor = "superdev", sessionId = null, taskId = null, apply = false } = {}) {
+  const plan = await query(root, (db) => acceptedPlan(db, id));
+  const refused = refuseReason(plan.how_to_run);
+  if (refused) {
+    throw new PlanError(E.NOT_RUNNABLE,
+      `${id} cannot be run unattended: ${refused}. Perform it and record what you saw with superdev test-plan record ${id} --summary "..." --result pass.`,
+      { howToRun: plan.how_to_run, why: refused });
+  }
+  const outcome = await runCheck(root, plan.how_to_run, { timeoutMs: 300000 });
+  const result = outcome.result === "pass" ? "pass" : outcome.result === "fail" ? "fail" : "inconclusive";
+  const summary = `${plan.how_to_run} ${result === "pass" ? "passed" : result === "fail" ? "failed" : "could not be judged"}. ${outcome.detail}`.trim().slice(0, 400);
+
+  if (!apply) return { applied: false, plan, result, summary, detail: outcome.detail };
+
+  const evidence = await mutate(root, async (db) => {
+    const current = await acceptedPlan(db, id);
+    return recordEvidence(db, current, {
+      summary, result, reference: null, checkCommand: plan.how_to_run, taskId, actor, sessionId,
+    });
+  });
+  return { applied: true, plan, result, summary, detail: outcome.detail, evidence };
+}
+
+/**
+ * Record a run that a person or an agent performed, for a plan no script can
+ * run. It takes a summary of what was observed rather than a bare verdict,
+ * because a pass with nothing behind it is what evidence exists to prevent.
+ */
+export async function recordPlanRun(root, id, {
+  summary, result = "pass", reference = null, taskId = null,
+  actor = "superdev", sessionId = null, apply = false,
+} = {}) {
+  if (!summary) {
+    throw new PlanError(E.NOT_FOUND, "Say what was actually observed when the plan was performed, not only whether it passed.");
+  }
+  if (!["pass", "fail", "inconclusive"].includes(result)) {
+    throw new PlanError(E.NOT_FOUND, `A result is pass, fail or inconclusive, not ${result}.`);
+  }
+  const plan = await query(root, (db) => acceptedPlan(db, id));
+  if (!apply) return { applied: false, plan, result, summary };
+  const evidence = await mutate(root, async (db) => {
+    const current = await acceptedPlan(db, id);
+    return recordEvidence(db, current, {
+      summary, result, reference, checkCommand: null, taskId, actor, sessionId,
+    });
+  });
+  return { applied: true, plan, result, summary, evidence };
+}