superdev-cli 0.1.0

package/src/db/migrations/002_docs_coverage.sql

@@ -0,0 +1,126 @@
+-- Storage for Docs template fields that version 1 left homeless. Without these
+-- the renderer would have to invent a place to keep them, which is how a second
+-- writable source of truth gets created by accident.
+
+-- foundations.md asks for explicit non-goals and a project-level scope. Feature
+-- scope does not roll up to answer "what is deliberately out of scope".
+CREATE TABLE project_scope_items (
+  id         TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  direction  TEXT NOT NULL CHECK (direction IN ('in','out','non_goal')),
+  statement  TEXT NOT NULL,
+  why        TEXT,
+  horizon    TEXT,
+  sequence   INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX project_scope_items_project ON project_scope_items(project_id, direction, sequence);
+
+-- foundations.md requires a glossary. One meaning per term.
+CREATE TABLE glossary_terms (
+  id         TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  term       TEXT NOT NULL,
+  meaning    TEXT NOT NULL,
+  source_ref TEXT,
+  UNIQUE (project_id, term)
+);
+
+-- architecture.md's runtime pieces table. Modules are a logical decomposition,
+-- not a runtime topology, so they cannot answer "runs where, talks to what".
+CREATE TABLE runtime_pieces (
+  id           TEXT PRIMARY KEY,
+  project_id   TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  name         TEXT NOT NULL,
+  runs_where   TEXT,
+  evidence_ref TEXT,
+  sequence     INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (project_id, name)
+);
+
+CREATE TABLE runtime_piece_edges (
+  from_piece_id TEXT NOT NULL REFERENCES runtime_pieces(id) ON DELETE CASCADE,
+  to_piece_id   TEXT NOT NULL REFERENCES runtime_pieces(id) ON DELETE CASCADE,
+  protocol      TEXT,
+  PRIMARY KEY (from_piece_id, to_piece_id)
+);
+
+-- The ADR template carries four relationship statuses that version 1 could not
+-- store. Partial supersession needs its exact scope, not just a pointer.
+CREATE TABLE decision_links (
+  id           TEXT PRIMARY KEY,
+  decision_id  TEXT NOT NULL REFERENCES decisions(id) ON DELETE CASCADE,
+  target_type  TEXT NOT NULL CHECK (target_type IN
+               ('decision','feature','module','workflow','document','api_operation','data_entity','nfr')),
+  target_id    TEXT NOT NULL,
+  relationship TEXT NOT NULL CHECK (relationship IN
+               ('supersedes','partially_supersedes','amends','relates_to','governs')),
+  scope_note   TEXT,
+  created_at   TEXT NOT NULL,
+  -- A partial supersession without its scope is the ambiguity the ADR
+  -- lifecycle exists to prevent.
+  CHECK (relationship <> 'partially_supersedes' OR scope_note IS NOT NULL)
+);
+CREATE INDEX decision_links_decision ON decision_links(decision_id);
+CREATE INDEX decision_links_target ON decision_links(target_type, target_id);
+
+-- A time-boxed decision needs an expiry, and it cannot be derived from
+-- acceptance. An expired decision stops governing and starts asking.
+ALTER TABLE decisions ADD COLUMN expires_at TEXT;
+
+-- roles.md asks for Role, Who, and Primary goals. Two columns forced one of the
+-- three into free prose.
+ALTER TABLE roles ADD COLUMN who TEXT;
+ALTER TABLE roles ADD COLUMN primary_goals TEXT;
+
+-- Not every generated file is an authored projection. A changelog, a status
+-- report and a drift report are derived views: they are rewritten every time
+-- and must never be trapped behind an edit proposal. Without this distinction
+-- one stray manual edit would permanently block regeneration of a report whose
+-- whole purpose is to be current.
+ALTER TABLE documents ADD COLUMN regeneration_mode TEXT NOT NULL DEFAULT 'authored_projection';
+
+-- A project-wide revision would mark every document stale on any unrelated
+-- write, so freshness is per document: a hash of the ordered records that fed
+-- the render.
+ALTER TABLE documents ADD COLUMN source_fingerprint TEXT;
+
+-- Capability areas gain a catalog so the readiness checklist, the foundations
+-- stack slots and the architecture boundaries share one shape and one query.
+-- The table is rebuilt rather than altered because the uniqueness rule changes,
+-- which is exactly the case an ordered migration exists to handle.
+CREATE TABLE capability_areas_v2 (
+  id              TEXT PRIMARY KEY,
+  project_id      TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  catalog         TEXT NOT NULL DEFAULT 'readiness'
+                  CHECK (catalog IN ('readiness','stack_slot','boundary')),
+  scope_type      TEXT NOT NULL DEFAULT 'project'
+                  CHECK (scope_type IN ('project','module','feature')),
+  scope_id        TEXT,
+  area            TEXT NOT NULL,
+  state           TEXT NOT NULL DEFAULT 'awaiting_decision'
+                  CHECK (state IN ('specified','awaiting_decision','not_applicable','deferred')),
+  choice          TEXT,
+  evidence_ref    TEXT,
+  decision_id     TEXT REFERENCES decisions(id) ON DELETE SET NULL,
+  reason          TEXT,
+  owner           TEXT,
+  revisit_trigger TEXT,
+  consequence     TEXT,
+  question_id     TEXT REFERENCES questions(id) ON DELETE SET NULL,
+  sequence        INTEGER NOT NULL DEFAULT 0,
+  updated_at      TEXT NOT NULL,
+  version         INTEGER NOT NULL DEFAULT 1,
+  CHECK (state = 'specified' OR reason IS NOT NULL),
+  UNIQUE (project_id, catalog, scope_type, scope_id, area)
+);
+
+INSERT INTO capability_areas_v2
+  (id, project_id, catalog, scope_type, scope_id, area, state, reason, owner,
+   revisit_trigger, consequence, question_id, sequence, updated_at, version)
+SELECT id, project_id, 'readiness', 'project', NULL, area, state, reason, owner,
+       revisit_trigger, consequence, question_id, sequence, updated_at, version
+FROM capability_areas;
+
+DROP TABLE capability_areas;
+
+ALTER TABLE capability_areas_v2 RENAME TO capability_areas;

package/src/db/migrations/003_memory_retrieval_and_integrity.sql

@@ -0,0 +1,168 @@
+-- Memory retrieval, link integrity, idempotent capture and honest verification.
+--
+-- Measured on the engine before designing this: under MVCC every virtual table
+-- is refused outright ("Virtual tables are not supported in MVCC mode"), and
+-- under WAL the bundled build reports "no such module: fts5" and "no such
+-- module: rtree". So full-text retrieval is an inverted index in ordinary
+-- tables, not FTS5, and not a scan over the newest N rows.
+
+-- ------------------------------------------------------- inverted term index
+
+-- One row per (memory, term, field). Retrieval selects candidates through the
+-- term index and only then applies recency, authority and epistemic weighting,
+-- so a relevant memory stays reachable no matter how old it is or how many
+-- newer ones exist.
+CREATE TABLE memory_search_terms (
+  memory_id    TEXT NOT NULL REFERENCES memory_entries(id) ON DELETE CASCADE,
+  term         TEXT NOT NULL,
+  field        TEXT NOT NULL CHECK (field IN ('title','content','source_ref')),
+  frequency    INTEGER NOT NULL DEFAULT 1,
+  field_weight REAL NOT NULL DEFAULT 1.0,
+  PRIMARY KEY (memory_id, term, field)
+);
+
+-- The lookup direction: term first. Without this the index is a scan wearing a
+-- table's clothes.
+CREATE INDEX memory_search_terms_term ON memory_search_terms(term, memory_id);
+
+-- --------------------------------------------------------- idempotent capture
+
+-- A hook, a compaction and a handoff all retry. Without a deterministic key the
+-- same observation lands three times and recall starts reporting its own echo
+-- as corroboration.
+ALTER TABLE memory_entries ADD COLUMN dedupe_key TEXT;
+ALTER TABLE memory_entries ADD COLUMN source_event_id TEXT;
+ALTER TABLE memory_entries ADD COLUMN content_hash TEXT;
+
+-- Deliberately scoped to an explicit key rather than to the content hash: two
+-- genuinely different observations may be worded alike, and collapsing those
+-- would lose real information. Only a caller-supplied key claims "this is the
+-- same delivery".
+CREATE UNIQUE INDEX memory_entries_dedupe
+  ON memory_entries(project_id, dedupe_key) WHERE dedupe_key IS NOT NULL;
+
+CREATE INDEX memory_entries_source_event
+  ON memory_entries(source_event_id) WHERE source_event_id IS NOT NULL;
+
+-- --------------------------------------------------------- honest verification
+
+-- Rebuilt rather than altered: target_type gains a CHECK, and every link now
+-- captures what the target looked like when the memory was written. Existence
+-- alone can never prove a recalled fact is still true, so the version and
+-- fingerprint recorded here are what later distinguishes verified from
+-- needs_review.
+CREATE TABLE memory_links_v2 (
+  memory_id          TEXT NOT NULL REFERENCES memory_entries(id) ON DELETE CASCADE,
+  target_type        TEXT NOT NULL CHECK (target_type IN (
+                       'task','feature','workflow','workflow_step','decision',
+                       'branch','verification_evidence','module','milestone',
+                       'goal','surface','ui_action','api_operation','data_entity',
+                       'integration','question','work_session')),
+  target_id          TEXT NOT NULL,
+  relationship       TEXT NOT NULL DEFAULT 'about',
+  target_version     INTEGER,
+  target_fingerprint TEXT,
+  created_at         TEXT,
+  PRIMARY KEY (memory_id, target_type, target_id)
+);
+
+INSERT INTO memory_links_v2 (memory_id, target_type, target_id, relationship)
+SELECT memory_id, target_type, target_id, relationship FROM memory_links
+WHERE target_type IN (
+  'task','feature','workflow','workflow_step','decision','branch',
+  'verification_evidence','module','milestone','goal','surface','ui_action',
+  'api_operation','data_entity','integration','question','work_session');
+
+DROP TABLE memory_links;
+
+ALTER TABLE memory_links_v2 RENAME TO memory_links;
+
+-- Reverse lookup: "what do we remember about this record". Structured recall
+-- filters through here, not only through the direct task and feature columns.
+CREATE INDEX memory_links_reverse ON memory_links(target_type, target_id, memory_id);
+
+-- ------------------------------------------------------------ link integrity
+
+-- A link to a record that does not exist is not a weak link, it is a false one.
+-- SQLite cannot express a foreign key whose table depends on a column value, so
+-- each supported type gets its own guard.
+CREATE TRIGGER memory_links_task_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'task' AND NOT EXISTS (SELECT 1 FROM tasks WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_feature_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'feature' AND NOT EXISTS (SELECT 1 FROM features WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_workflow_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'workflow' AND NOT EXISTS (SELECT 1 FROM workflows WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_workflow_step_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'workflow_step' AND NOT EXISTS (SELECT 1 FROM workflow_steps WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_decision_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'decision' AND NOT EXISTS (SELECT 1 FROM decisions WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_branch_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'branch' AND NOT EXISTS (SELECT 1 FROM branches WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_evidence_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'verification_evidence' AND NOT EXISTS (SELECT 1 FROM verification_evidence WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_module_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'module' AND NOT EXISTS (SELECT 1 FROM modules WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_milestone_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'milestone' AND NOT EXISTS (SELECT 1 FROM milestones WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_goal_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'goal' AND NOT EXISTS (SELECT 1 FROM goals WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_session_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'work_session' AND NOT EXISTS (SELECT 1 FROM work_sessions WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+CREATE TRIGGER memory_links_question_exists
+BEFORE INSERT ON memory_links
+WHEN NEW.target_type = 'question' AND NOT EXISTS (SELECT 1 FROM questions WHERE id = NEW.target_id)
+BEGIN SELECT RAISE(ABORT, 'E_MEMORY_LINK_ORPHAN'); END;
+
+-- ------------------------------------------------------------ embedding seam
+
+-- The seam, kept separate and empty. The embedding column on memory_entries was
+-- a placeholder that looked like a finished vector design and was not: it had no
+-- provider, no model, no dimensions, and nothing recording which content it was
+-- computed from. This table is the honest shape. Nothing populates it in this
+-- release, and this engine has no vector index, so any future recall through it
+-- is a bounded scan and must say so.
+CREATE TABLE memory_embeddings (
+  memory_id    TEXT NOT NULL REFERENCES memory_entries(id) ON DELETE CASCADE,
+  provider     TEXT NOT NULL,
+  model        TEXT NOT NULL,
+  dimensions   INTEGER NOT NULL,
+  content_hash TEXT NOT NULL,
+  embedding    BLOB,
+  generated_at TEXT,
+  status       TEXT NOT NULL DEFAULT 'pending'
+               CHECK (status IN ('pending','ready','stale','failed')),
+  PRIMARY KEY (memory_id, provider, model)
+);

package/src/db/migrations/004_task_categories.sql

@@ -0,0 +1,59 @@
+-- More task categories, and a place for a category to say what it means.
+--
+-- The original twelve came from brief section 7.3, but derivation produces work
+-- the twelve could not describe: proving rollout and rollback was filed under
+-- Infrastructure, and a surface with its actions under Feature. A category that
+-- does not describe the work is worse than no category, because it is a label
+-- people learn to ignore.
+--
+-- The descriptions are written out here rather than read from the vocabulary
+-- module because a migration cannot import application code. The module stays
+-- the source for newly created projects; this is the one-time backfill for
+-- projects that already exist.
+
+ALTER TABLE task_categories ADD COLUMN description TEXT;
+
+-- Meanings for the categories already seeded.
+UPDATE task_categories SET description = 'New product behavior somebody asked for.' WHERE name = 'Feature' AND description IS NULL;
+UPDATE task_categories SET description = 'Existing behavior made better without changing what it is.' WHERE name = 'Improvement' AND description IS NULL;
+UPDATE task_categories SET description = 'Behavior that does not match what was accepted.' WHERE name = 'Bug' AND description IS NULL;
+UPDATE task_categories SET description = 'Internal change with no change in behavior.' WHERE name = 'Refactor' AND description IS NULL;
+UPDATE task_categories SET description = 'Finding something out before deciding what to build.' WHERE name = 'Investigation' AND description IS NULL;
+UPDATE task_categories SET description = 'Keeping the written record in step with the product.' WHERE name = 'Documentation' AND description IS NULL;
+UPDATE task_categories SET description = 'Work at the boundary with something outside this product.' WHERE name = 'Integration' AND description IS NULL;
+UPDATE task_categories SET description = 'Moving data or schema from one shape to another.' WHERE name = 'Migration' AND description IS NULL;
+UPDATE task_categories SET description = 'The ground the product runs on.' WHERE name = 'Infrastructure' AND description IS NULL;
+UPDATE task_categories SET description = 'Protecting the product, its data and the people in it.' WHERE name = 'Security' AND description IS NULL;
+UPDATE task_categories SET description = 'Work that raises confidence rather than adding behavior.' WHERE name = 'Quality' AND description IS NULL;
+UPDATE task_categories SET description = 'Agreed as worth doing, not yet scheduled.' WHERE name = 'Backlog' AND description IS NULL;
+
+-- The nine additions, seeded for every project that already exists. Sequence
+-- continues from whatever that project already had, so a project that added its
+-- own categories does not have them reordered underneath it.
+INSERT INTO task_categories (id, project_id, name, description, system, active, sequence)
+SELECT
+  'TC-' || substr('0000' || CAST(
+    (SELECT count(*) FROM task_categories x WHERE x.project_id = p.id) + n.ord AS TEXT
+  ), -4),
+  p.id, n.name, n.description, 1, 1,
+  (SELECT coalesce(max(x.sequence), -1) FROM task_categories x WHERE x.project_id = p.id) + n.ord
+FROM projects p
+CROSS JOIN (
+  SELECT 1 AS ord, 'Design' AS name, 'Surfaces, actions and how the product presents itself.' AS description
+  UNION ALL SELECT 2, 'Testing', 'Product tests derived from the accepted test plan.'
+  UNION ALL SELECT 3, 'Performance', 'Meeting a declared speed or capacity target.'
+  UNION ALL SELECT 4, 'Accessibility', 'Making the product operable by everyone who uses it.'
+  UNION ALL SELECT 5, 'Observability', 'Signals that prove the product is working in the open.'
+  UNION ALL SELECT 6, 'Data', 'Modelling the entities and relationships the product owns.'
+  UNION ALL SELECT 7, 'Release', 'Getting the work out, and being able to take it back.'
+  UNION ALL SELECT 8, 'Compliance', 'Obligations under a regime this project has declared.'
+  UNION ALL SELECT 9, 'Chore', 'Routine upkeep that keeps the project healthy.'
+) n
+WHERE NOT EXISTS (
+  SELECT 1 FROM task_categories e WHERE e.project_id = p.id AND e.name = n.name
+);
+
+-- A category a project added itself is never silently removed, so retiring one
+-- has to be a status change rather than a delete. `active` already carries that;
+-- this index makes the common read, the pickable list, cheap.
+CREATE INDEX task_categories_active ON task_categories(project_id, active, sequence);

package/src/db/migrations/005_executable_evidence.sql

@@ -0,0 +1,32 @@
+-- Evidence that can be checked again.
+--
+-- verification_evidence already carried status ('current', 'stale',
+-- 'superseded'), stale_at and content_hash, so the design always intended
+-- evidence to go out of date. Nothing ever marked it. Evidence was a sentence
+-- written once and believed forever, which is the same shape as every other
+-- failure found in this codebase: an intention recorded on one side with no
+-- mechanism on the other.
+--
+-- A claim that carries the command which proved it can be checked again. That
+-- turns honesty from something asserted at one moment into something the
+-- product keeps checking, and it is the only way a completed task can notice
+-- that the ground moved under it.
+--
+-- check_command is nullable on purpose. Reading a screenshot, confirming a
+-- decision with the owner, watching a migration run: these are real
+-- verifications that no command reproduces. Requiring one would push people to
+-- invent commands, which is worse than admitting a check is manual.
+
+ALTER TABLE verification_evidence ADD COLUMN check_command TEXT;
+
+-- When the command was last run, and what happened. Distinct from recorded_at,
+-- which is when the claim was first made: the gap between the two is exactly
+-- the question "is this still true?".
+ALTER TABLE verification_evidence ADD COLUMN last_checked_at TEXT;
+ALTER TABLE verification_evidence ADD COLUMN last_check_result TEXT
+  CHECK (last_check_result IS NULL OR last_check_result IN ('pass', 'fail', 'error'));
+
+-- Finding stale evidence is a scan over everything current that carries a
+-- command, so it gets an index rather than a table walk on every run.
+CREATE INDEX IF NOT EXISTS idx_evidence_recheck
+  ON verification_evidence (status, check_command);

package/src/db/migrations/006_module_and_feature_boundaries.sql

@@ -0,0 +1,27 @@
+-- What a module excludes, and what a feature is for.
+--
+-- Section 8.3 step 4 of the requirements document asks, for every module, "What
+-- is explicitly outside its scope?". There was nowhere to put the answer.
+-- Features carry scope_in_json and scope_out_json; modules carried neither, so
+-- the boundary that makes a module a module had to be folded into its purpose
+-- as prose or dropped.
+--
+-- A module without a stated boundary is the failure the document names in
+-- section 3: unclear architecture, and work that drifts because nobody wrote
+-- down where one part stops.
+
+ALTER TABLE modules ADD COLUMN out_of_scope TEXT;
+
+-- Which people this module serves, from the same interview. Kept as text rather
+-- than a link table because the answer is usually a sentence naming a role, and
+-- a role row may not exist yet at discovery time.
+ALTER TABLE modules ADD COLUMN primary_users TEXT;
+
+-- Section 8.3 step 5 asks for a feature's user problem and intended outcome
+-- before anything else. user_statement holds the first; the table already has
+-- user_value for the second. Without it a feature is a title and a purpose,
+-- which is what makes a specification thin enough to build the wrong thing.
+--
+-- features.user_statement already exists, so only the module columns are added
+-- here. This migration is named for both because the boundary question is one
+-- question asked at two levels.

package/src/db/migrations/007_drop_redundant_module_users.sql

@@ -0,0 +1,13 @@
+-- Remove a column that duplicated one already there.
+--
+-- 006 added modules.primary_users without checking that modules.primary_users_json
+-- already held the same answer. Two columns for "which people this module serves"
+-- is worse than either alone: a reader has to work out which one is filled, and a
+-- writer has to guess which one is read.
+--
+-- The column was added and dropped without ever being written to, so nothing is
+-- lost. It is dropped in its own migration rather than by editing 006, because
+-- an applied migration's checksum is recorded and changing the file after the
+-- fact is exactly the drift the migration validator exists to catch.
+
+ALTER TABLE modules DROP COLUMN primary_users;

package/src/db/migrations/008_changes_assumptions_test_plans_api_services.sql

@@ -0,0 +1,166 @@
+-- The four objects the requirements document names and the schema never built.
+--
+-- Section 6.1 defines each of them, 14.1 lists each as a record the local
+-- database must store, and none of them existed. The record could name them and
+-- nothing could hold one, so four capabilities the document promises had no
+-- place to live: recording what altered accepted scope, recording a reversible
+-- answer with its review trigger, recording how a feature will be verified, and
+-- grouping API operations under the boundary that owns them.
+
+-- A recorded alteration to accepted product scope or behaviour.
+--
+-- Section 6.2 says a Change must record the affected records and the reason,
+-- and 14.2 says changes must preserve audit history. Activity events already
+-- record that something happened; a change records that accepted scope moved
+-- and why, which is a different claim and the one a reader asks about later.
+CREATE TABLE changes (
+  id                   TEXT PRIMARY KEY,
+  project_id           TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  summary              TEXT NOT NULL,
+  reason               TEXT NOT NULL,
+  -- What kind of movement this was, so a reader can tell a widening from a
+  -- correction without reading every one.
+  change_type          TEXT NOT NULL DEFAULT 'scope_changed'
+    CHECK (change_type IN ('scope_added', 'scope_removed', 'behavior_changed',
+                           'contract_changed', 'correction', 'scope_changed')),
+  requested_by         TEXT,
+  decided_by           TEXT,
+  -- The decision that authorised it, when one did. A change that contradicts an
+  -- accepted decision without superseding it is the drift this product exists
+  -- to prevent.
+  decision_id          TEXT REFERENCES decisions(id) ON DELETE SET NULL,
+  task_id              TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  session_id           TEXT,
+  status               TEXT NOT NULL DEFAULT 'recorded'
+    CHECK (status IN ('proposed', 'recorded', 'reverted')),
+  created_at           TEXT NOT NULL,
+  version              INTEGER NOT NULL DEFAULT 1
+);
+
+-- Which records a change moved. Polymorphic because a change can touch a
+-- feature, a workflow, an entity or an operation, and one column cannot
+-- reference six tables.
+CREATE TABLE change_targets (
+  change_id            TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  target_type          TEXT NOT NULL,
+  target_id            TEXT NOT NULL,
+  -- What moved about it, in plain language: "acceptance criterion added",
+  -- "purpose rewritten". Without this the link says something changed and never
+  -- what.
+  what_changed         TEXT,
+  PRIMARY KEY (change_id, target_type, target_id)
+);
+
+-- A reversible answer used temporarily.
+--
+-- 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 somewhere to put one, an assumption becomes an
+-- undocumented guess that nobody knows to revisit.
+CREATE TABLE assumptions (
+  id                   TEXT PRIMARY KEY,
+  project_id           TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  statement            TEXT NOT NULL,
+  -- Why this was assumed rather than decided. An assumption with no reason is
+  -- indistinguishable from a decision nobody wrote down.
+  why_assumed          TEXT NOT NULL,
+  -- What would make this worth revisiting. Required, because an assumption with
+  -- no trigger is never reviewed and quietly becomes a fact.
+  review_trigger       TEXT NOT NULL,
+  -- What breaks if the assumption turns out wrong.
+  consequence_if_wrong TEXT,
+  scope_type           TEXT,
+  scope_id             TEXT,
+  question_id          TEXT REFERENCES questions(id) ON DELETE SET NULL,
+  status               TEXT NOT NULL DEFAULT 'holding'
+    CHECK (status IN ('holding', 'confirmed', 'overturned', 'expired')),
+  -- Set when the assumption stops holding, with what replaced it.
+  resolved_by          TEXT,
+  resolved_at          TEXT,
+  resolution           TEXT,
+  created_at           TEXT NOT NULL,
+  updated_at           TEXT NOT NULL,
+  version              INTEGER NOT NULL DEFAULT 1
+);
+
+-- The agreed verification strategy for a feature or a workflow.
+--
+-- Section 9.3 gates task completion on "product tests defined by the accepted
+-- test plan" passing, and 7.2 requires generated test plan documents. The gate
+-- named a document that could not exist. Section 20.2 says the strategy is the
+-- product's own rather than one universal style, so the kinds are open text
+-- with a check on the ones the document names.
+CREATE TABLE test_plans (
+  id                   TEXT PRIMARY KEY,
+  project_id           TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  feature_id           TEXT REFERENCES features(id) ON DELETE CASCADE,
+  workflow_id          TEXT REFERENCES workflows(id) ON DELETE CASCADE,
+  module_id            TEXT REFERENCES modules(id) ON DELETE CASCADE,
+  name                 TEXT NOT NULL,
+  strategy             TEXT NOT NULL,
+  -- What running it looks like, so someone else can run it.
+  how_to_run           TEXT,
+  -- What counts as passing, in terms a person can check.
+  passing_condition    TEXT,
+  status               TEXT NOT NULL DEFAULT 'draft'
+    CHECK (status IN ('draft', 'accepted', 'superseded')),
+  created_at           TEXT NOT NULL,
+  updated_at           TEXT NOT NULL,
+  version              INTEGER NOT NULL DEFAULT 1
+);
+
+-- The individual checks a plan is made of.
+CREATE TABLE test_plan_cases (
+  id                   TEXT PRIMARY KEY,
+  test_plan_id         TEXT NOT NULL REFERENCES test_plans(id) ON DELETE CASCADE,
+  name                 TEXT NOT NULL,
+  kind                 TEXT NOT NULL DEFAULT 'manual_check',
+  -- What this case proves. A case that names no expectation proves nothing.
+  expectation          TEXT NOT NULL,
+  -- A command that runs it, when one exists. Null is honest for a check a
+  -- person performs, and matches how verification_evidence treats the same
+  -- question.
+  command              TEXT,
+  sequence             INTEGER NOT NULL DEFAULT 0
+);
+
+-- A logical API boundary.
+--
+-- Section 6.1 defines an API Service as the boundary and an API Operation as a
+-- concrete endpoint within one. Only operations were stored, so every operation
+-- was loose rather than grouped under the thing that owns it.
+CREATE TABLE api_services (
+  id                   TEXT PRIMARY KEY,
+  project_id           TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  module_id            TEXT REFERENCES modules(id) ON DELETE SET NULL,
+  name                 TEXT NOT NULL,
+  purpose              TEXT,
+  style                TEXT NOT NULL DEFAULT 'rest'
+    CHECK (style IN ('rest', 'graphql', 'rpc', 'events', 'local-only')),
+  base_path            TEXT,
+  auth_requirement     TEXT,
+  versioning           TEXT,
+  status               TEXT NOT NULL DEFAULT 'specified',
+  sequence             INTEGER NOT NULL DEFAULT 0,
+  created_at           TEXT NOT NULL,
+  updated_at           TEXT NOT NULL,
+  version              INTEGER NOT NULL DEFAULT 1
+);
+
+-- Operations belong to the boundary that exposes them. Nullable, because an
+-- operation recorded before its service is still worth having.
+ALTER TABLE api_operations ADD COLUMN api_service_id TEXT REFERENCES api_services(id) ON DELETE SET NULL;
+
+-- A change is a historical claim about what moved and when. Revising one
+-- rewrites the audit trail that 14.2 requires be preserved, so the same
+-- append-only rule that guards activity events guards these.
+CREATE TRIGGER changes_no_update BEFORE UPDATE ON changes
+BEGIN SELECT RAISE(ABORT, 'E_APPEND_ONLY'); END;
+CREATE TRIGGER changes_no_delete BEFORE DELETE ON changes
+BEGIN SELECT RAISE(ABORT, 'E_APPEND_ONLY'); END;
+
+CREATE INDEX IF NOT EXISTS idx_changes_project ON changes (project_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_change_targets_target ON change_targets (target_type, target_id);
+CREATE INDEX IF NOT EXISTS idx_assumptions_status ON assumptions (project_id, status);
+CREATE INDEX IF NOT EXISTS idx_test_plans_feature ON test_plans (feature_id);
+CREATE INDEX IF NOT EXISTS idx_api_operations_service ON api_operations (api_service_id);

package/src/db/migrations/009_retired_documents.sql

@@ -0,0 +1,54 @@
+-- A document whose record no longer exists.
+--
+-- docs generate already noticed these and skipped them, which left them in the
+-- table marked generated at whatever revision they were last written. Freshness
+-- then counted them behind forever and no later run could clear it: five
+-- documents from an earlier schema sat at revision 681 while the documentation
+-- check confirmed all 295 files matched the database. Two checks disagreeing
+-- about the same files is worse than either being wrong.
+--
+-- retired says what is true. The row stays queryable so what was once
+-- documented is still answerable, and freshness stops counting it as work
+-- outstanding, because a document for a deleted record is not behind. It is
+-- finished with.
+--
+-- SQLite cannot alter a CHECK constraint, so the table is rebuilt. Columns are
+-- listed explicitly rather than copied with a wildcard, because a silent column
+-- mismatch here would lose documentation state.
+
+CREATE TABLE documents_next (
+  id                  TEXT PRIMARY KEY,
+  project_id          TEXT NOT NULL,
+  kind                TEXT NOT NULL,
+  scope_type          TEXT NOT NULL,
+  scope_id            TEXT,
+  path                TEXT NOT NULL,
+  template            TEXT,
+  database_revision   INTEGER NOT NULL DEFAULT 0,
+  generated_body      TEXT,
+  generated_hash      TEXT,
+  manual_hash         TEXT,
+  sync_status         TEXT NOT NULL DEFAULT 'generated'
+    CHECK (sync_status IN ('generated', 'manual_edit_pending', 'accepted',
+                           'rejected', 'missing', 'retired')),
+  generated_at        TEXT,
+  regeneration_mode   TEXT NOT NULL DEFAULT 'authored_projection',
+  source_fingerprint  TEXT,
+  FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+  UNIQUE (project_id, path)
+);
+
+INSERT INTO documents_next (
+  id, project_id, kind, scope_type, scope_id, path, template, database_revision,
+  generated_body, generated_hash, manual_hash, sync_status, generated_at,
+  regeneration_mode, source_fingerprint)
+SELECT
+  id, project_id, kind, scope_type, scope_id, path, template, database_revision,
+  generated_body, generated_hash, manual_hash, sync_status, generated_at,
+  regeneration_mode, source_fingerprint
+FROM documents;
+
+DROP TABLE documents;
+ALTER TABLE documents_next RENAME TO documents;
+
+CREATE INDEX IF NOT EXISTS idx_documents_sync ON documents (sync_status);