superdev-cli 0.1.0

package/src/db/migrations/010_test_plan_evidence.sql

@@ -0,0 +1,20 @@
+-- Connect evidence to the test plan it satisfies.
+--
+-- Section 9.3 lists five conditions for completing a task, and one of them is
+-- that the product tests defined by the accepted test plan pass. The gate
+-- enforced the other four. Test plans existed as records, were shown in the
+-- control centre, and reached nothing: a task could complete with passing
+-- evidence that had nothing to do with the plan the owner accepted.
+--
+-- The missing piece was small and structural. Evidence knew the task it proved
+-- and the command that produced it, and had no way to say which agreed
+-- verification strategy it was a run of. So a plan could never be satisfied,
+-- and a gate that can never be satisfied is one nobody can write.
+
+ALTER TABLE verification_evidence
+  ADD COLUMN test_plan_id TEXT REFERENCES test_plans(id) ON DELETE SET NULL;
+
+-- Asked on every completion, once per plan in scope, so it is worth an index
+-- rather than a scan of every result ever recorded.
+CREATE INDEX idx_verification_evidence_test_plan
+  ON verification_evidence(test_plan_id) WHERE test_plan_id IS NOT NULL;

package/src/db/migrations/011_criterion_waiver.sql

@@ -0,0 +1,13 @@
+-- Why a criterion was set aside.
+--
+-- The status vocabulary has allowed 'waived' since the first migration, two
+-- refusals tell the reader to waive a criterion, and nothing could record one:
+-- there was no command, and no column for the reason if there had been. A
+-- status nothing can reach is the same as no status at all, except that it
+-- makes the refusal a dead end.
+--
+-- The reason is the whole point. A waived criterion without one reads exactly
+-- like a criterion somebody quietly stopped trying to meet, which is what
+-- evidence gating exists to prevent.
+
+ALTER TABLE feature_acceptance_criteria ADD COLUMN waiver_reason TEXT;

package/src/db/migrations/012_synchronization.sql

@@ -0,0 +1,56 @@
+-- What synchronization needs to be real rather than described.
+--
+-- sync_peers and sync_conflicts have existed since the first migration and
+-- nothing ever wrote to them: the commands refused, naming three decisions in
+-- section 23 that were open. Those decisions are now recorded, so this adds the
+-- three things the protocol needs that the schema could not express.
+--
+-- A base snapshot, so a conflict can be detected rather than guessed. Knowing
+-- that two copies differ is not enough to know who changed what: without the
+-- version both sides agreed on last time, every difference looks like a
+-- conflict and a copy that only pulled would be told it had diverged.
+--
+-- A lease, so an assignment can be held across machines. The partial unique
+-- index already makes two active assignments impossible in one database, and
+-- says nothing about a second machine. A lease names its holder and expires, so
+-- a crashed machine releases its claim without anyone intervening.
+--
+-- Where a peer is and how it is reached, because a peer nothing can locate is a
+-- row rather than a connection.
+
+-- What both sides agreed on at the end of the last successful sync. The middle
+-- term of a three-way comparison, and the only thing that distinguishes "they
+-- changed it" from "we both changed it".
+CREATE TABLE sync_base (
+  id            TEXT PRIMARY KEY,
+  project_id    TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  peer_id       TEXT NOT NULL REFERENCES sync_peers(id) ON DELETE CASCADE,
+  record_type   TEXT NOT NULL,
+  record_id     TEXT NOT NULL,
+  -- The version both sides held, and a hash of the row as it stood. The hash
+  -- catches a change to a table with no version column, which several have.
+  base_version  INTEGER,
+  base_hash     TEXT NOT NULL,
+  synced_at     TEXT NOT NULL,
+  UNIQUE (peer_id, record_type, record_id)
+);
+CREATE INDEX sync_base_peer ON sync_base(peer_id, record_type);
+
+-- How to reach a peer, and which key opens what it holds.
+ALTER TABLE sync_peers ADD COLUMN transport TEXT NOT NULL DEFAULT 'directory';
+ALTER TABLE sync_peers ADD COLUMN location TEXT;
+ALTER TABLE sync_peers ADD COLUMN alias TEXT;
+ALTER TABLE sync_peers ADD COLUMN key_fingerprint TEXT;
+ALTER TABLE sync_peers ADD COLUMN connected_at TEXT;
+
+-- An assignment that can be held from another machine.
+--
+-- The holder is an alias rather than a person: section 18 forbids disclosing a
+-- developer's identity across the boundary, and refusing a second claim only
+-- needs a name the other side recognises, not who that name belongs to.
+ALTER TABLE task_assignments ADD COLUMN lease_holder TEXT;
+ALTER TABLE task_assignments ADD COLUMN lease_expires_at TEXT;
+ALTER TABLE task_assignments ADD COLUMN origin_peer TEXT;
+
+CREATE INDEX task_assignments_lease ON task_assignments(lease_expires_at)
+  WHERE lease_expires_at IS NOT NULL;

package/src/db/store.mjs

@@ -0,0 +1,327 @@
+// Repository layer. Every mutation goes through here so that four things are
+// always true and never depend on a caller remembering: content is screened,
+// history is appended, an activity event is recorded, and the record's version
+// moves. Callers get rows, not SQL.
+
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { read, write, DbError, E as DBE } from "./connect.mjs";
+import { migrate } from "./migrate.mjs";
+import { nextId, tableFor, PREFIX } from "../model/ids.mjs";
+import { assertRecordStorable } from "../model/screening.mjs";
+
+export { DbError, DBE };
+
+/** Everything Superdev writes lives under one git-ignored directory. */
+export function paths(root) {
+  const dir = join(root, ".superdev");
+  return {
+    dir,
+    db: join(dir, "superdev.db"),
+    backups: join(dir, "backups"),
+    runtime: join(dir, "runtime"),
+    exports: join(dir, "exports"),
+  };
+}
+
+export async function ensureDatabase(root, { apply = true } = {}) {
+  const p = paths(root);
+  return migrate(p.db, { apply });
+}
+
+/** Read helper bound to a project root. Opens and closes; never pooled. */
+export const query = (root, fn) => read(paths(root).db, fn);
+
+/** Write helper bound to a project root. One transaction, then closed. */
+export const mutate = (root, fn) => write(paths(root).db, fn);
+
+// ------------------------------------------------------------------ project
+
+export async function currentProject(db) {
+  return db.get("SELECT * FROM projects ORDER BY created_at LIMIT 1");
+}
+
+// ----------------------------------------------------------------- activity
+
+const nowIso = () => new Date().toISOString();
+
+/**
+ * Append an activity event. The sequence is allocated inside the caller's
+ * transaction, so it is gapless and ordered even with several writers, and the
+ * hash chains each event to the one before it.
+ */
+export async function recordActivity(db, projectId, event) {
+  const prev = await db.get(
+    "SELECT sequence, immutable_hash FROM activity_events WHERE project_id = ? ORDER BY sequence DESC LIMIT 1",
+    projectId,
+  );
+  const sequence = (prev?.sequence ?? 0) + 1;
+  const id = await nextId(db, "activity_event");
+  const created_at = event.createdAt ?? nowIso();
+  const payload = {
+    id,
+    project_id: projectId,
+    session_id: event.sessionId ?? null,
+    actor_id: event.actorId ?? null,
+    actor_label: event.actor ?? "superdev",
+    task_id: event.taskId ?? null,
+    feature_id: event.featureId ?? null,
+    event_type: event.type,
+    summary: event.summary,
+    metadata_json: JSON.stringify(event.metadata ?? {}),
+    created_at,
+    sequence,
+  };
+  assertRecordStorable(payload);
+  payload.immutable_hash = createHash("sha256")
+    .update(String(prev?.immutable_hash ?? ""))
+    .update(`${sequence}\u0000${payload.event_type}\u0000${payload.summary}\u0000${created_at}`)
+    .digest("hex");
+
+  const cols = Object.keys(payload);
+  await db.run(
+    `INSERT INTO activity_events (${cols.join(",")}) VALUES (${cols.map(() => "?").join(",")})`,
+    ...cols.map((c) => payload[c]),
+  );
+  return { id, sequence };
+}
+
+/** Append a status transition. Never revised, only added to. */
+export async function recordStatusChange(db, projectId, recordType, recordId, from, to, opts = {}) {
+  const prev = await db.get(
+    "SELECT sequence FROM status_history WHERE record_type = ? AND record_id = ? ORDER BY sequence DESC LIMIT 1",
+    recordType, recordId,
+  );
+  const id = await nextId(db, "status_history");
+  await db.run(
+    `INSERT INTO status_history
+       (id, project_id, record_type, record_id, from_status, to_status, actor_label, note, created_at, sequence)
+     VALUES (?,?,?,?,?,?,?,?,?,?)`,
+    id, projectId, recordType, recordId, from, to,
+    opts.actor ?? "superdev", opts.note ?? null, opts.at ?? nowIso(), (prev?.sequence ?? 0) + 1,
+  );
+  return id;
+}
+
+// ------------------------------------------------------------------- writes
+
+const AUTO = new Set(["created_at", "updated_at", "version"]);
+
+/**
+ * Insert a record of `kind`. Mints the id, screens every field, stamps
+ * timestamps, and records the creation as activity when the table has a
+ * project.
+ */
+export async function create(db, kind, values, opts = {}) {
+  const table = tableFor(kind);
+  if (!table) throw new Error(`unknown record kind: ${kind}`);
+  const columns = await columnsOf(db, table);
+  const at = opts.at ?? nowIso();
+
+  const row = { ...values };
+  if (!row.id) row.id = await nextId(db, kind);
+  if (columns.has("created_at") && !row.created_at) row.created_at = at;
+  if (columns.has("updated_at") && !row.updated_at) row.updated_at = at;
+
+  // A key that is not a column is a typo, and deleting it quietly is how a
+  // field silently keeps its default while the caller believes it was written.
+  const unknown = Object.keys(row).filter((key) => !columns.has(key));
+  if (unknown.length) {
+    throw new DbError(
+      "E_UNKNOWN_COLUMN",
+      `${table} has no column named ${unknown.join(", ")}. Check the spelling against the migration that defines the table.`,
+      { table, unknown },
+    );
+  }
+  assertRecordStorable(row);
+
+  const cols = Object.keys(row);
+  await db.run(
+    `INSERT INTO ${table} (${cols.join(",")}) VALUES (${cols.map(() => "?").join(",")})`,
+    ...cols.map((c) => row[c]),
+  );
+
+  if (opts.projectId && opts.activity !== false) {
+    await recordActivity(db, opts.projectId, {
+      type: opts.activityType ?? "specification_changed",
+      summary: opts.activitySummary ?? `Created ${kind.replace(/_/g, " ")} ${row.id}`,
+      actor: opts.actor,
+      sessionId: opts.sessionId,
+      featureId: row.feature_id ?? opts.featureId ?? null,
+      taskId: kind === "task" ? row.id : opts.taskId ?? null,
+      metadata: { kind, id: row.id },
+    });
+  }
+  return db.get(`SELECT * FROM ${table} WHERE id = ?`, row.id);
+}
+
+/**
+ * Update a record under its optimistic version. A zero-row result means someone
+ * else moved it, which surfaces as a conflict rather than a silent no-op.
+ */
+export async function patch(db, kind, id, expectedVersion, values, opts = {}) {
+  const table = tableFor(kind);
+  const columns = await columnsOf(db, table);
+  const row = {};
+  const unknown = [];
+  for (const [k, v] of Object.entries(values)) {
+    if (AUTO.has(k)) continue;
+    if (!columns.has(k)) { unknown.push(k); continue; }
+    row[k] = v;
+  }
+  if (unknown.length) {
+    throw new DbError(
+      "E_UNKNOWN_COLUMN",
+      `${table} has no column named ${unknown.join(", ")}. Check the spelling against the migration that defines the table.`,
+      { table, unknown },
+    );
+  }
+  if (!Object.keys(row).length) return db.get(`SELECT * FROM ${table} WHERE id = ?`, id);
+  assertRecordStorable(row);
+  if (columns.has("updated_at")) row.updated_at = opts.at ?? nowIso();
+
+  await db.versionedUpdate(table, id, expectedVersion, row);
+
+  if (opts.projectId && opts.activity !== false) {
+    await recordActivity(db, opts.projectId, {
+      type: opts.activityType ?? "specification_changed",
+      summary: opts.activitySummary ?? `Updated ${kind.replace(/_/g, " ")} ${id}`,
+      actor: opts.actor,
+      sessionId: opts.sessionId,
+      metadata: { kind, id, fields: Object.keys(row).filter((k) => k !== "updated_at") },
+    });
+  }
+  return db.get(`SELECT * FROM ${table} WHERE id = ?`, id);
+}
+
+/**
+ * Move a record's status, appending history and activity. Status is never
+ * changed through `patch`, so no transition can happen without a record of it.
+ */
+export async function setStatus(db, kind, id, toStatus, opts = {}) {
+  const table = tableFor(kind);
+  const before = await db.get(`SELECT * FROM ${table} WHERE id = ?`, id);
+  if (!before) throw new DbError("E_NOT_FOUND", `${kind} ${id} does not exist.`);
+  if (before.status === toStatus) return before;
+
+  const assignments = { status: toStatus };
+  const columns = await columnsOf(db, table);
+  const at = opts.at ?? nowIso();
+  if (columns.has("updated_at")) assignments.updated_at = at;
+
+  // When a table keeps a column for the moment a status was reached, fill it.
+  // This used to run only for tasks, so a feature could be accepted and leave
+  // accepted_at null, and every reading built on that column counted zero: the
+  // status report headline read "0 features accepted" while 35 were.
+  const STAMP = {
+    accepted: "accepted_at",
+    complete: "completed_at",
+    completed: "completed_at",
+    cancelled: "cancelled_at",
+    in_progress: "started_at",
+  };
+  const stamp = STAMP[toStatus];
+  // started_at records the first start, so a task returning to in_progress
+  // keeps the original. Every other stamp records the latest transition.
+  if (stamp && columns.has(stamp) && !(stamp === "started_at" && before[stamp])) {
+    assignments[stamp] = at;
+  }
+
+  if (kind === "task") {
+    if (toStatus === "blocked") assignments.block_reason = opts.reason ?? before.block_reason ?? null;
+    if (before.status === "blocked" && toStatus !== "blocked") assignments.block_reason = null;
+  }
+
+  await db.versionedUpdate(table, id, opts.expectedVersion ?? before.version, assignments);
+  await recordStatusChange(db, opts.projectId ?? before.project_id, kind, id, before.status, toStatus, opts);
+
+  const projectId = opts.projectId ?? before.project_id ?? null;
+  if (projectId && opts.activity !== false) {
+    await recordActivity(db, projectId, {
+      type: opts.activityType ?? statusEventType(kind, toStatus),
+      summary: opts.activitySummary ?? `${labelFor(kind)} ${id} moved to ${toStatus.replace(/_/g, " ")}`,
+      actor: opts.actor,
+      sessionId: opts.sessionId,
+      taskId: kind === "task" ? id : null,
+      featureId: kind === "feature" ? id : before.feature_id ?? null,
+      metadata: { kind, id, from: before.status, to: toStatus, note: opts.note ?? null },
+    });
+  }
+  return db.get(`SELECT * FROM ${table} WHERE id = ?`, id);
+}
+
+function statusEventType(kind, to) {
+  if (kind !== "task") return "specification_changed";
+  return {
+    in_progress: "task_started",
+    blocked: "task_blocked",
+    complete: "task_completed",
+    cancelled: "task_cancelled",
+    ready: "task_updated",
+  }[to] ?? "task_updated";
+}
+
+const labelFor = (kind) => kind.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+
+// ------------------------------------------------------------------ helpers
+
+const columnCache = new Map();
+async function columnsOf(db, table) {
+  // Keyed by database as well as table: two roots at different schema versions
+  // in one process would otherwise share a column set.
+  const key = `${db.file ?? ""}\u0000${table}`;
+  if (columnCache.has(key)) return columnCache.get(key);
+  const info = await db.all(`PRAGMA table_info(${table})`);
+  const set = new Set(info.map((c) => c.name));
+  columnCache.set(key, set);
+  return set;
+}
+
+
+export const json = (value, fallback = []) => {
+  if (value === null || value === undefined || value === "") return fallback;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+};
+
+/**
+ * Walk a parent chain iteratively. This engine has no recursive CTEs, and task
+ * and module trees are shallow enough that a few sub-millisecond reads beat any
+ * materialized path that could fall out of step.
+ */
+export async function ancestors(db, table, id, parentColumn = "parent_task_id", limit = 32) {
+  const chain = [];
+  let current = id;
+  for (let i = 0; i < limit && current; i++) {
+    const row = await db.get(`SELECT * FROM ${table} WHERE id = ?`, current);
+    if (!row) break;
+    chain.push(row);
+    current = row[parentColumn];
+  }
+  return chain;
+}
+
+/** Collect a whole subtree, breadth first, without recursion in SQL. */
+export async function descendants(db, table, id, parentColumn = "parent_task_id", limit = 5000) {
+  const out = [];
+  let frontier = [id];
+  const seen = new Set(frontier);
+  while (frontier.length && out.length < limit) {
+    const placeholders = frontier.map(() => "?").join(",");
+    const rows = await db.all(`SELECT * FROM ${table} WHERE ${parentColumn} IN (${placeholders})`, ...frontier);
+    if (!rows.length) break;
+    frontier = [];
+    for (const row of rows) {
+      if (seen.has(row.id)) continue;
+      seen.add(row.id);
+      out.push(row);
+      frontier.push(row.id);
+    }
+  }
+  return out;
+}
+
+export { PREFIX };

package/src/decisions/record.mjs

@@ -0,0 +1,167 @@
+// Record a decision, and supersede one that no longer holds.
+//
+// The decisions table, its transitions, its supersession chain and the reports
+// built on them all existed. Nothing could write a row. There was no CLI
+// command, no service mutation, and convertDiscovery turns accepted content
+// into goals, modules and features only, so a decision could be transitioned,
+// governed by, reported on and expired, but never made.
+//
+// That is why the twenty decisions in this project's own database were written
+// by a script reading the ADR files rather than by the product.
+//
+// The rules here are the ones the rest of the system already assumes:
+//
+//   A decision states what was decided and why in observable terms. The
+//   rationale is what a reader can check, not what a model was thinking.
+//
+//   Superseding is a link in both directions plus a status move on the old
+//   decision, done in one transaction. Half of that leaves the reports
+//   disagreeing about what governs.
+//
+//   A partial supersession says which part stops applying. Without that nobody
+//   can tell what the old decision still governs, which is the same rule
+//   transitionDecision already enforces.
+
+import { create, mutate, query, setStatus } from "../db/store.mjs";
+
+export const E = {
+  NOT_FOUND: "E_NOT_FOUND",
+  INVALID: "E_INVALID",
+  ALREADY_SUPERSEDED: "E_ALREADY_SUPERSEDED",
+};
+
+export class DecisionError extends Error {
+  constructor(code, message, detail = {}) {
+    super(message);
+    this.name = "DecisionError";
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const asList = (value) => {
+  if (value === null || value === undefined) return [];
+  return (Array.isArray(value) ? value : [value])
+    .map((v) => String(v).trim())
+    .filter(Boolean);
+};
+
+/**
+ * Record a decision.
+ *
+ * A title and the decision itself are required, because a record with neither
+ * is a heading nobody can act on. Everything else is optional and defaults to
+ * the empty shape the schema already declares.
+ */
+export async function recordDecision(root, input = {}) {
+  const title = String(input.title ?? "").trim();
+  const decision = String(input.decision ?? "").trim();
+  if (!title) {
+    throw new DecisionError(E.INVALID, "A decision needs a title, in plain language, so it can be found again.");
+  }
+  if (!decision) {
+    throw new DecisionError(E.INVALID,
+      "A decision needs to say what was decided. A title alone records that a choice happened, not what it was.");
+  }
+
+  const {
+    context = null, rationale = null, verification = null,
+    scopeType = null, scopeId = null, status = "proposed",
+    acceptedBy = null, expiresAt = null, actor = "superdev", sessionId = null,
+  } = input;
+
+  if (scopeType && !scopeId) {
+    throw new DecisionError(E.INVALID, `A decision scoped to a ${scopeType} has to name which one.`);
+  }
+
+  return mutate(root, async (db) => {
+    const project = await db.get("SELECT id FROM projects LIMIT 1");
+    if (!project) throw new DecisionError(E.NOT_FOUND, "There is no project to record a decision against.");
+
+    const row = await create(db, "decision", {
+      project_id: project.id,
+      title,
+      decision,
+      context,
+      observable_rationale: rationale,
+      verification,
+      scope_type: scopeType,
+      scope_id: scopeId,
+      status,
+      accepted_by: acceptedBy,
+      accepted_at: status === "accepted" ? new Date().toISOString() : null,
+      expires_at: expiresAt,
+      evidence_json: JSON.stringify(asList(input.evidence)),
+      criteria_json: JSON.stringify(asList(input.criteria)),
+      options_json: JSON.stringify(asList(input.options)),
+      risks_json: JSON.stringify(asList(input.risks)),
+      enforcement_json: JSON.stringify(asList(input.enforcement)),
+      revisit_triggers_json: JSON.stringify(asList(input.revisitTriggers)),
+    }, {
+      projectId: project.id,
+      actor,
+      sessionId,
+      activityType: "decision_recorded",
+      activitySummary: `Decision recorded: ${title}`,
+    });
+
+    // A decision that governs something says so, or the reports that ask what
+    // binds a module find nothing and report that nothing does.
+    for (const target of asList(input.governs)) {
+      const [targetType, targetId] = target.split(":");
+      if (!targetType || !targetId) {
+        throw new DecisionError(E.INVALID,
+          `"${target}" is not a link. Write it as <type>:<id>, for example module:MOD-0001.`);
+      }
+      await create(db, "decision_link", {
+        decision_id: row.id,
+        target_type: targetType,
+        target_id: targetId,
+        relationship: "governs",
+        scope_note: "The record this decision binds. Changing it here means superseding the decision, not editing around it.",
+      }, { projectId: project.id, actor, sessionId, activityType: "decision_recorded",
+           activitySummary: `${row.id} governs ${targetId}` });
+    }
+
+    return row;
+  });
+}
+
+/**
+ * Record a decision that replaces an earlier one.
+ *
+ * Both directions of the link and the old decision's status move happen in one
+ * transaction. Writing the new decision first and the supersession afterwards
+ * leaves a window where two decisions both claim to govern the same thing, and
+ * whichever report runs in that window is wrong.
+ */
+export async function supersedeDecision(root, supersededId, input = {}) {
+  const scopeDelta = String(input.scopeDelta ?? "").trim();
+  const partial = Boolean(input.partial);
+  if (partial && !scopeDelta) {
+    throw new DecisionError(E.INVALID,
+      "A partial supersession has to say which part stops applying, otherwise nobody can tell what still governs.");
+  }
+
+  const existing = await query(root, (db) => db.get("SELECT * FROM decisions WHERE id = ?", supersededId));
+  if (!existing) throw new DecisionError(E.NOT_FOUND, `There is no decision ${supersededId}.`);
+  if (existing.superseded_by_id) {
+    throw new DecisionError(E.ALREADY_SUPERSEDED,
+      `${supersededId} was already superseded by ${existing.superseded_by_id}. Supersede that one instead, so the chain stays a chain.`);
+  }
+
+  const replacement = await recordDecision(root, {
+    ...input,
+    status: input.status ?? "accepted",
+  });
+
+  return mutate(root, async (db) => {
+    await db.run("UPDATE decisions SET supersedes_id = ? WHERE id = ?", supersededId, replacement.id);
+    await db.run("UPDATE decisions SET superseded_by_id = ? WHERE id = ?", replacement.id, supersededId);
+    await setStatus(db, "decision", supersededId, partial ? "partially_superseded" : "superseded", {
+      actor: input.actor ?? "superdev",
+      reason: scopeDelta || `Superseded by ${replacement.id}.`,
+    });
+    return { ...replacement, supersedes: supersededId, partial };
+  });
+}