@jaguilar87/gaia 5.0.2 → 5.0.5

package/scripts/migrations/v15_to_v16.sql

@@ -1,57 +0,0 @@
--- Migration v15 -> v16 (gaia-scan-overhaul: projects soft-delete columns)
---
--- Background
--- ----------
--- The prune step in scan_workspace_to_store currently issues hard DELETEs for
--- projects that are no longer found on disk. Brief gaia-scan-overhaul replaces
--- that with a soft-delete: projects are marked 'missing' instead of removed,
--- so historical context (memory atoms, episodes, briefs keyed on that project)
--- survives the scan cycle.
---
--- This migration adds two scanner-owned columns to the `projects` table:
---
---   status TEXT NOT NULL DEFAULT 'active'
---     Values: 'active' | 'missing'.
---     'active'  -- project was present on the last scan run.
---     'missing' -- project was NOT found on the most recent scan; kept as a
---                  tombstone so child-table data and historical context survive.
---     Default 'active': existing rows (which were present at migration time)
---     are classified as active. New rows inserted by the scanner also default
---     to 'active' without requiring callers to supply the column.
---
---   missing_since TEXT (nullable)
---     ISO8601 UTC timestamp of when status was first set to 'missing'.
---     NULL when status='active'. The scanner sets this on the first cycle
---     where it cannot find the project; subsequent cycles leave it unchanged
---     (the timestamp records the FIRST disappearance, not the most recent).
---
--- Scope of this migration
--- -----------------------
--- ONLY the DDL changes. The prune logic (DELETE -> UPDATE status='missing') is
--- implemented in the NEXT task (scan populator changes). This migration only
--- ensures the columns exist and that the writer accepts them.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT. A failure
--- mid-flight rolls back to v15 state; the ledger row is NOT inserted, so the
--- next bootstrap retry sees the same pending migration.
-
--- ---------------------------------------------------------------------------
--- Step 1: Add status column to projects (NOT NULL DEFAULT 'active')
--- ---------------------------------------------------------------------------
-ALTER TABLE projects ADD COLUMN status TEXT NOT NULL DEFAULT 'active';
-
--- ---------------------------------------------------------------------------
--- Step 2: Add missing_since column to projects (nullable)
--- ---------------------------------------------------------------------------
-ALTER TABLE projects ADD COLUMN missing_since TEXT;
-
--- ---------------------------------------------------------------------------
--- Step 3: Bump schema_version to 16
--- ---------------------------------------------------------------------------
-INSERT OR IGNORE INTO schema_version (version, applied_at, description)
-VALUES (16, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'),
-        'projects soft-delete: status + missing_since columns');
-
--- Verification queries (run after applying):
--- SELECT MAX(version) FROM schema_version;          -- expect: 16
--- PRAGMA table_info(projects);                       -- expect: status, missing_since columns present

package/scripts/migrations/v15_to_v16_fresh.sql

@@ -1,18 +0,0 @@
--- Migration v15 -> v16 fresh-install variant
---
--- Used by bootstrap_database.sh when the live DB was created directly from
--- schema.sql at v16 state -- i.e. the `projects` table already carries the
--- `status` and `missing_since` columns because schema.sql declared them that way.
---
--- On a fresh install there are no legacy rows to alter, so the ALTER TABLE
--- statements in v15_to_v16.sql would fail with "duplicate column name".
--- This variant is a no-op; it exists only so the bootstrap guard-probe branch
--- (Section 3c, case 16) can select it and stamp the ledger without attempting
--- the ALTER.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- No DDL is executed; the COMMIT is harmless.
-
--- No-op: fresh install already at v16 state (schema.sql created projects with
--- status and missing_since columns).
-SELECT 1;

package/scripts/migrations/v16_to_v17.sql

@@ -1,51 +0,0 @@
--- Migration v16 -> v17 (DEMOTE case: workspaces soft-delete columns)
---
--- Background
--- ----------
--- v16 added soft-delete (status / missing_since) to the `projects` table. The
--- multi-workspace DEMOTE test revealed the same gap one level up: when a
--- workspace loses its Gaia install footprint (the user removes its `.claude/`,
--- "demoting" it), the `workspaces` row had no way to record that. A re-scan of
--- a demoted directory would persist the row and refresh `last_scan_at` as if it
--- were still a live workspace.
---
--- This migration adds two scanner-owned columns to the `workspaces` table,
--- mirroring the v16 projects soft-delete contract:
---
---   status TEXT NOT NULL DEFAULT 'active'
---     Values: 'active' | 'missing'.
---     'active'  -- the workspace carried a Gaia install on the last scan.
---     'missing' -- the workspace's install footprint disappeared (demoted);
---                  kept as a tombstone so its projects/history survive.
---     Default 'active': existing rows (live workspaces at migration time) are
---     classified active without requiring callers to supply the column.
---
---   missing_since TEXT (nullable)
---     ISO8601 UTC timestamp of when status was first set to 'missing'.
---     NULL when status='active'. Set on the first scan that finds the install
---     gone; subsequent scans leave it unchanged (records the FIRST demote).
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT. A failure
--- mid-flight rolls back to v16 state; the ledger row is NOT inserted, so the
--- next bootstrap retry sees the same pending migration.
-
--- ---------------------------------------------------------------------------
--- Step 1: Add status column to workspaces (NOT NULL DEFAULT 'active')
--- ---------------------------------------------------------------------------
-ALTER TABLE workspaces ADD COLUMN status TEXT NOT NULL DEFAULT 'active';
-
--- ---------------------------------------------------------------------------
--- Step 2: Add missing_since column to workspaces (nullable)
--- ---------------------------------------------------------------------------
-ALTER TABLE workspaces ADD COLUMN missing_since TEXT;
-
--- ---------------------------------------------------------------------------
--- Step 3: Bump schema_version to 17
--- ---------------------------------------------------------------------------
-INSERT OR IGNORE INTO schema_version (version, applied_at, description)
-VALUES (17, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'),
-        'workspaces soft-delete: status + missing_since columns (DEMOTE)');
-
--- Verification queries (run after applying):
--- SELECT MAX(version) FROM schema_version;          -- expect: 17
--- PRAGMA table_info(workspaces);                      -- expect: status, missing_since columns present

package/scripts/migrations/v16_to_v17_fresh.sql

@@ -1,18 +0,0 @@
--- Migration v16 -> v17 fresh-install variant
---
--- Used by bootstrap_database.sh when the live DB was created directly from
--- schema.sql at v17 state -- i.e. the `workspaces` table already carries the
--- `status` and `missing_since` columns because schema.sql declared them that way.
---
--- On a fresh install there are no legacy rows to alter, so the ALTER TABLE
--- statements in v16_to_v17.sql would fail with "duplicate column name".
--- This variant is a no-op; it exists only so the bootstrap guard-probe branch
--- (Section 3c, case 17) can select it and stamp the ledger without attempting
--- the ALTER.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- No DDL is executed; the COMMIT is harmless.
-
--- No-op: fresh install already at v17 state (schema.sql created workspaces with
--- status and missing_since columns).
-SELECT 1;

package/scripts/migrations/v17_to_v18.sql

@@ -1,66 +0,0 @@
--- Migration v17 -> v18 (stable project identity: collapse same repo across vantages)
---
--- Background
--- ----------
--- The `projects` table is keyed (workspace, name). The scanner derives `name`
--- from the on-disk basename and `workspace` from the scan vantage's identity.
--- The SAME physical repository scanned from two different roots -- e.g. once
--- from the workspace root and once from inside the repo's own subdirectory
--- (which resolves a different *workspace* identity) -- produced TWO distinct
--- (workspace, name) rows: a duplicate of one physical project.
---
--- This migration adds a stable, vantage-independent project identity so the
--- UPSERT can collapse those duplicates into one row. Identity is resolved by
--- the scanner (tools/scan/store_populator.resolve_project_identity) in this
--- order: git-common-dir (realpath) > normalized remote (host/owner/repo) >
--- realpath of the project path.
---
--- Two additive, NON-DESTRUCTIVE changes:
---
---   1. ALTER TABLE projects ADD COLUMN project_identity TEXT (nullable)
---      Scanner-owned. NULL allowed for legacy/uninitialized rows so the column
---      adds cleanly to an existing DB without backfill. A subsequent `gaia scan`
---      populates it for every live project.
---
---   2. CREATE UNIQUE INDEX idx_projects_identity ... WHERE project_identity IS NOT NULL
---      PARTIAL unique index. Enforces one row per physical repo for rows that
---      HAVE an identity, while exempting legacy NULL-identity rows from the
---      uniqueness constraint (so multiple NULL rows can coexist until the next
---      scan backfills them). This is the ON CONFLICT target the writer uses.
---
--- Backfill note
--- -------------
--- This migration does NOT backfill project_identity for existing rows -- it
--- cannot derive git-common-dir from SQL alone, and the value is cheap to
--- recompute on the next scan. Existing duplicate rows (if any) are left intact;
--- the first scan after migration assigns identities and any genuine duplicate
--- collapses on the following scan once both rows share an identity. Because the
--- index is PARTIAL, the ADD COLUMN (all rows NULL) cannot fail on existing
--- duplicates.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT. A failure
--- mid-flight rolls back to v17 state; the ledger row is NOT inserted, so the
--- next bootstrap retry sees the same pending migration.
-
--- ---------------------------------------------------------------------------
--- Step 1: Add project_identity column to projects (nullable, scanner-owned)
--- ---------------------------------------------------------------------------
-ALTER TABLE projects ADD COLUMN project_identity TEXT;
-
--- ---------------------------------------------------------------------------
--- Step 2: Partial UNIQUE index that collapses the same physical repo to one row
--- ---------------------------------------------------------------------------
-CREATE UNIQUE INDEX IF NOT EXISTS idx_projects_identity
-    ON projects(project_identity) WHERE project_identity IS NOT NULL;
-
--- ---------------------------------------------------------------------------
--- Step 3: Bump schema_version to 18
--- ---------------------------------------------------------------------------
-INSERT OR IGNORE INTO schema_version (version, applied_at, description)
-VALUES (18, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'),
-        'projects stable identity: project_identity column + partial unique index (collapse same repo across vantages)');
-
--- Verification queries (run after applying):
--- SELECT MAX(version) FROM schema_version;                                  -- expect: 18
--- SELECT name FROM pragma_table_info('projects') WHERE name='project_identity'; -- expect: project_identity
--- SELECT name FROM sqlite_master WHERE type='index' AND name='idx_projects_identity'; -- expect: idx_projects_identity

package/scripts/migrations/v17_to_v18_fresh.sql

@@ -1,24 +0,0 @@
--- Migration v17 -> v18 fresh-install variant
---
--- Used by bootstrap_database.sh when the live DB was created directly from
--- schema.sql at v18 state -- i.e. the `projects` table already carries the
--- `project_identity` column because schema.sql declared it that way.
---
--- On a fresh install there are no legacy rows to alter, so the ALTER TABLE
--- statement in v17_to_v18.sql would fail with "duplicate column name".
--- This variant therefore SKIPS the ALTER but still creates the partial unique
--- index -- the index is intentionally NOT declared in schema.sql because
--- referencing project_identity there would parse-fail when bootstrapping a
--- legacy (pre-v18) DB whose CREATE TABLE IF NOT EXISTS short-circuits before
--- the column exists. Creating it here (idempotent IF NOT EXISTS) is the only
--- place the index lands on a fresh install. Same convention as
--- idx_memory_class_status (scripts/migrations/v3_to_v4_fresh.sql).
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
-
--- Step 1 (skipped on fresh install): the project_identity column already exists.
-
--- Step 2: create the partial unique index that collapses the same physical repo
--- (same project_identity) to one row, exempting NULL-identity legacy rows.
-CREATE UNIQUE INDEX IF NOT EXISTS idx_projects_identity
-    ON projects(project_identity) WHERE project_identity IS NOT NULL;

package/scripts/migrations/v1_to_v2.sql

@@ -1,97 +0,0 @@
--- Migration v1 -> v2: widen memory.type CHECK constraint.
---
--- Background
--- ----------
--- v1 schema: memory.type CHECK (type IN ('project', 'user', 'feedback'))
--- v2 schema: memory.type CHECK (type IN ('project', 'user', 'feedback', 'atom', 'decision', 'negative'))
---
--- The bug this migration fixes
--- ----------------------------
--- bootstrap_database.sh applies schema.sql with `CREATE TABLE IF NOT EXISTS`.
--- On DBs created under v1 the CREATE short-circuits and the widened CHECK in
--- schema.sql never lands -- yet the bootstrap historically stamped the
--- schema_version ledger row for v2 unconditionally. Result: the ledger lied
--- and writes of the new types ('atom', 'decision', 'negative') failed at
--- runtime with CHECK constraint errors while `gaia doctor` reported OK.
---
--- Pattern: SQLite cannot ALTER a CHECK constraint. Canonical workaround:
---   1. Drop the FTS5 mirror triggers (avoid duplicate writes during copy).
---   2. Rename the old table out of the way.
---   3. Create the new table with the widened CHECK matching schema.sql.
---   4. Copy rows preserving rowid (memory_fts joins on rowid).
---   5. Drop the renamed old table.
---   6. Recreate the indexes on the new table.
---   7. Recreate the FTS5 mirror triggers verbatim.
---   8. Rebuild memory_fts from the new memory table.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT. A
--- failure mid-flight rolls back to the v1 state and the ledger row is NOT
--- inserted -- the next bootstrap retry will see the same pending migration.
---
--- Pre-conditions: caller has verified that the live memory.type CHECK does
--- NOT yet include 'atom'. Applying this on an already-widened table would
--- still succeed (the rename-create-copy ends in the same state) but the
--- caller skips it to avoid unnecessary work.
-
--- 1. Drop the FTS5 trigger trio. They mirror writes into memory_fts; we do
---    not want them to fire during the bulk copy below. memory_fts itself is
---    untouched here -- we will rebuild it after the copy completes.
-DROP TRIGGER IF EXISTS memory_ai;
-DROP TRIGGER IF EXISTS memory_ad;
-DROP TRIGGER IF EXISTS memory_au;
-
--- 2. Rename the old table out of the way. The indexes (idx_memory_project,
---    idx_memory_workspace, idx_memory_type) move with the table under their
---    original names -- SQLite ALTER TABLE RENAME carries indexes along.
-ALTER TABLE memory RENAME TO memory_v1_legacy;
-
--- 3. Create the new memory table with the widened CHECK constraint that
---    matches schema.sql verbatim (6 allowed types).
-CREATE TABLE memory (
-    workspace         TEXT NOT NULL,
-    name              TEXT NOT NULL,
-    type              TEXT NOT NULL CHECK (type IN ('project', 'user', 'feedback', 'atom', 'decision', 'negative')),
-    description       TEXT,
-    body              TEXT NOT NULL,
-    origin_session_id TEXT,
-    updated_at        TEXT,
-    PRIMARY KEY (workspace, name),
-    FOREIGN KEY (workspace) REFERENCES workspaces(name) ON DELETE CASCADE
-);
-
--- 4. Copy all rows preserving rowid. This is critical: memory_fts joins on
---    rowid, so changing them would invalidate the FTS5 index. We list rowid
---    explicitly to bypass SQLite's default rowid allocation.
-INSERT INTO memory (rowid, workspace, name, type, description, body, origin_session_id, updated_at)
-SELECT rowid, workspace, name, type, description, body, origin_session_id, updated_at
-FROM memory_v1_legacy;
-
--- 5. Drop the renamed old table. Its indexes go with it.
-DROP TABLE memory_v1_legacy;
-
--- 6. Recreate the indexes on the new table. Same names as schema.sql.
-CREATE INDEX IF NOT EXISTS idx_memory_workspace ON memory(workspace);
-CREATE INDEX IF NOT EXISTS idx_memory_type ON memory(type);
-
--- 7. Recreate the three FTS5 mirror triggers verbatim from schema.sql.
-CREATE TRIGGER memory_ai AFTER INSERT ON memory BEGIN
-    INSERT INTO memory_fts(rowid, workspace, name, description, body)
-    VALUES (new.rowid, new.workspace, new.name, new.description, new.body);
-END;
-
-CREATE TRIGGER memory_ad AFTER DELETE ON memory BEGIN
-    INSERT INTO memory_fts(memory_fts, rowid, workspace, name, description, body)
-    VALUES ('delete', old.rowid, old.workspace, old.name, old.description, old.body);
-END;
-
-CREATE TRIGGER memory_au AFTER UPDATE ON memory BEGIN
-    INSERT INTO memory_fts(memory_fts, rowid, workspace, name, description, body)
-    VALUES ('delete', old.rowid, old.workspace, old.name, old.description, old.body);
-    INSERT INTO memory_fts(rowid, workspace, name, description, body)
-    VALUES (new.rowid, new.workspace, new.name, new.description, new.body);
-END;
-
--- 8. Rebuild memory_fts from the new memory table. FTS5's native reindex:
---    clears the internal state and rescans the backing table. Cleaner than
---    DELETE + INSERT loops.
-INSERT INTO memory_fts(memory_fts) VALUES('rebuild');

package/scripts/migrations/v2_to_v3.sql

@@ -1,68 +0,0 @@
--- Migration v2 -> v3 (rename path).
---
--- Background
--- ----------
--- v2 schema had:
---   context_contracts (workspace, section_name, payload, metadata, updated_at)
---   PK: (workspace, section_name)
---
--- v3 schema has:
---   project_context_contracts (workspace, contract_name, payload, metadata, updated_at)
---   PK: (workspace, contract_name)
---   + new table agent_contract_permissions
---   + new index idx_agent_contract_perms_agent
---
--- The rename of `context_contracts` -> `project_context_contracts` reflects
--- its actual role: rows are project-context contracts, not permission grants.
--- The column rename `section_name` -> `contract_name` aligns the vocabulary
--- with the permission model introduced alongside it.
---
--- Three real-world entry states
--- -----------------------------
--- State 1 (only old):  context_contracts exists, project_context_contracts does NOT.
---                      Typical of a clean v2 install upgrading for the first time.
---                      This script handles state 1 via ALTER TABLE RENAME.
--- State 2 (only new):  project_context_contracts exists, context_contracts does NOT,
---                      agent_contract_permissions exists.  Nothing to do -- the guard
---                      probe in bootstrap_database.sh detects state 2 and stamps the
---                      ledger without invoking this script.
--- State 3 (both):      Both tables exist.  Caused by a previous bootstrap where
---                      schema.sql under v3 was applied (CREATE TABLE IF NOT EXISTS
---                      created the new table) but the legacy context_contracts was
---                      never dropped.  State 3 needs row migration + drop, handled
---                      by v2_to_v3_merge.sql -- not by this script.
---
--- bootstrap_database.sh selects state 1 vs 3 via the guard probe and runs the
--- matching script.  Each script is therefore single-purpose and atomic.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.  A failure
--- mid-flight rolls back to v2 state and the ledger row is NOT inserted, so the
--- next bootstrap retry will see the same pending migration.
-
--- 1. Rename the table.
-ALTER TABLE context_contracts RENAME TO project_context_contracts;
-
--- 2. Rename the column.
-ALTER TABLE project_context_contracts RENAME COLUMN section_name TO contract_name;
-
--- 3. Index on workspace -- name reflects the new table identity.  The old
---    index moved with the table on RENAME TO, but its name still references
---    the legacy table.  Drop + recreate keeps the index name consistent
---    with the new table identity.
-DROP INDEX IF EXISTS idx_context_contracts_workspace;
-CREATE INDEX IF NOT EXISTS idx_project_context_contracts_workspace
-    ON project_context_contracts(workspace);
-
--- 4. New permissions table + its index.  IF NOT EXISTS makes the script
---    safe to re-run if a partial earlier attempt already created them.
-CREATE TABLE IF NOT EXISTS agent_contract_permissions (
-    agent_name    TEXT NOT NULL,
-    contract_name TEXT NOT NULL,
-    can_read      INTEGER NOT NULL DEFAULT 0,
-    can_write     INTEGER NOT NULL DEFAULT 0,
-    cloud_scope   TEXT,
-    PRIMARY KEY (agent_name, contract_name, cloud_scope)
-);
-
-CREATE INDEX IF NOT EXISTS idx_agent_contract_perms_agent
-    ON agent_contract_permissions(agent_name);

package/scripts/migrations/v2_to_v3_merge.sql

@@ -1,69 +0,0 @@
--- Migration v2 -> v3 (merge path).
---
--- Runs when the guard probe in bootstrap_database.sh detects "state 3" --
--- both `context_contracts` (legacy v2 table) AND `project_context_contracts`
--- (new v3 table) exist.  This happens when an earlier bootstrap under v3
--- code applied schema.sql (which created the new table with IF NOT EXISTS)
--- but the old table was never dropped because schema.sql no longer declares
--- it and IF NOT EXISTS only creates -- it never drops.
---
--- See v2_to_v3.sql for the rename path (state 1) and for the full discussion
--- of the three entry states.
---
--- Strategy
--- --------
--- The new table is created in v3 shape (column `contract_name`), the old
--- table is in v2 shape (column `section_name`).  The two columns are
--- semantically identical, so we copy rows with column aliasing:
---
---   INSERT INTO project_context_contracts (workspace, contract_name, ...)
---   SELECT workspace, section_name, ...
---   FROM context_contracts
---   WHERE (workspace, section_name) NOT IN (
---       SELECT workspace, contract_name FROM project_context_contracts
---   );
---
--- The NOT IN guard makes the copy idempotent: rows that were already
--- migrated by a prior partial run are skipped instead of duplicating PK
--- conflicts.  Once the copy is complete and verified, the legacy table is
--- dropped along with its index.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.  If
--- the copy or the drop fails, the transaction rolls back, the ledger is
--- NOT stamped, and the next bootstrap retry observes state 3 again.
-
--- 1. Copy rows from the legacy table into the new one, skipping any whose
---    primary key already exists in the new table.
-INSERT INTO project_context_contracts (workspace, contract_name, payload, metadata, updated_at)
-SELECT workspace, section_name, payload, metadata, updated_at
-FROM context_contracts
-WHERE (workspace, section_name) NOT IN (
-    SELECT workspace, contract_name FROM project_context_contracts
-);
-
--- 2. Drop the legacy index explicitly.  SQLite drops indexes with their
---    table on DROP TABLE, but being explicit catches the case where the
---    index was created standalone or renamed without us noticing.
-DROP INDEX IF EXISTS idx_context_contracts_workspace;
-
--- 3. Drop the legacy table.  Its rows have already been copied above.
-DROP TABLE context_contracts;
-
--- 4. Ensure the new index exists with the canonical name (in case an
---    earlier partial run created the table but not its index).
-CREATE INDEX IF NOT EXISTS idx_project_context_contracts_workspace
-    ON project_context_contracts(workspace);
-
--- 5. Permissions table + index.  IF NOT EXISTS makes this safe whether
---    schema.sql already created them in a previous bootstrap or not.
-CREATE TABLE IF NOT EXISTS agent_contract_permissions (
-    agent_name    TEXT NOT NULL,
-    contract_name TEXT NOT NULL,
-    can_read      INTEGER NOT NULL DEFAULT 0,
-    can_write     INTEGER NOT NULL DEFAULT 0,
-    cloud_scope   TEXT,
-    PRIMARY KEY (agent_name, contract_name, cloud_scope)
-);
-
-CREATE INDEX IF NOT EXISTS idx_agent_contract_perms_agent
-    ON agent_contract_permissions(agent_name);

package/scripts/migrations/v3_to_v4.sql

@@ -1,67 +0,0 @@
--- Migration v3 -> v4 (memory model: class + status + memory_links).
---
--- Background
--- ----------
--- v3 schema had:
---   memory(workspace, name, type, description, body, origin_session_id, updated_at)
---   PK: (workspace, name)
---   type CHECK constraint: ('project','user','feedback','atom','decision','negative')
---
--- v4 schema adds two ortogonal axes to the memory model:
---   * class  -- semantic role (anchor | thread | log), nullable for legacy rows.
---   * status -- lifecycle for class=thread (open | carry_forward | graduated | closed).
---
--- Plus a new table:
---   memory_links(workspace, src_name, dst_name, kind, created_at)
---   PK: (workspace, src_name, dst_name, kind)
---   kind CHECK: ('relates_to','supersedes','derived_from','graduated_to')
---
--- Design decision: NO CHECK constraint on memory.class / memory.status
--- ---------------------------------------------------------------------
--- SQLite's ALTER TABLE ADD COLUMN cannot attach a CHECK that depends on
--- the new column's enum values. The standard workaround is a full table
--- rebuild (CREATE new, INSERT SELECT, DROP old, RENAME), which would:
---   1. Force re-creation of memory_fts triggers (drift risk on live DBs).
---   2. Move all existing memory rows through a copy step, complicating the
---      AC-2 contract that "the 36 me-workspace rows survive intact" with
---      byte-identical bodies.
---   3. Add complexity disproportionate to the gain -- the writer layer
---      validates the enum on every upsert in T3 anyway.
---
--- Therefore: schema declares class/status as plain TEXT nullable columns.
--- Enum enforcement is the writer's job (gaia/store/writer.py, T3).
--- memory_links.kind keeps its CHECK because it is a brand-new table with
--- no rebuild cost.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT. A
--- failure mid-flight rolls back to v3 state and the ledger row is NOT
--- inserted, so the next bootstrap retry sees the same pending migration.
-
--- 1. Add the two nullable columns to memory. Existing rows get NULL,
---    which is the documented "legacy row" state and is what T8/T9 will
---    reclassify interactively.
-ALTER TABLE memory ADD COLUMN class TEXT;
-ALTER TABLE memory ADD COLUMN status TEXT;
-
--- 2. Index on (workspace, class, status) -- supports the injector path
---    that picks class=thread/status=carry_forward first.
-CREATE INDEX IF NOT EXISTS idx_memory_class_status
-    ON memory(workspace, class, status);
-
--- 3. New table memory_links + indexes. IF NOT EXISTS makes the script
---    idempotent if a partial earlier attempt already created them.
-CREATE TABLE IF NOT EXISTS memory_links (
-    workspace  TEXT NOT NULL,
-    src_name   TEXT NOT NULL,
-    dst_name   TEXT NOT NULL,
-    kind       TEXT NOT NULL CHECK (kind IN ('relates_to', 'supersedes', 'derived_from', 'graduated_to')),
-    created_at TEXT,
-    PRIMARY KEY (workspace, src_name, dst_name, kind),
-    FOREIGN KEY (workspace) REFERENCES workspaces(name) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS memory_links_src
-    ON memory_links(workspace, src_name);
-
-CREATE INDEX IF NOT EXISTS idx_memory_links_dst_kind
-    ON memory_links(workspace, dst_name, kind);

package/scripts/migrations/v3_to_v4_fresh.sql

@@ -1,20 +0,0 @@
--- v3 -> v4 fresh-install variant.
---
--- Used by bootstrap_database.sh Section 3c case 4 when the live DDL is
--- already at the v4 target state (memory.class column present, memory_links
--- table present). This happens on a clean install where schema.sql already
--- created the v4 column layout and the memory_links table.
---
--- The default v3_to_v4.sql cannot run here because ALTER TABLE ADD COLUMN
--- fails when the column already exists. This variant carries only the DDL
--- that schema.sql cannot declare safely:
---   * idx_memory_class_status -- references columns added at ALTER time,
---     so schema.sql cannot pre-declare it (the replay on v3 DBs would parse-
---     fail before the migration ran).
---
--- Everything else (memory_links table, memory_links indexes) is declared in
--- schema.sql and is therefore already present on a fresh install. CREATE
--- INDEX IF NOT EXISTS makes this script safe to re-run.
-
-CREATE INDEX IF NOT EXISTS idx_memory_class_status
-    ON memory(workspace, class, status);

package/scripts/migrations/v4_to_v5.sql

@@ -1,55 +0,0 @@
--- Migration v4 -> v5 (state-machine completion: status columns on AC + milestones).
---
--- Background
--- ----------
--- v4 schema has:
---   acceptance_criteria(id, brief_id, ac_id, description, evidence_type,
---                        evidence_shape, artifact_path)
---   milestones(id, brief_id, order_num, name, description)
---
--- v5 schema adds a status lifecycle column to both tables:
---   * acceptance_criteria.status  -- lifecycle (pending | done | blocked)
---   * milestones.status           -- lifecycle (pending | done | blocked)
---
--- Design decision: CHECK constraint inline on ADD COLUMN
--- -------------------------------------------------------
--- SQLite >= 3.37 supports ADD COLUMN with NOT NULL + DEFAULT + CHECK in a
--- single statement without a full table rebuild. The bootstrap environment
--- is confirmed at SQLite 3.45.1, so this is safe.
---
--- The enum values are intentionally small: pending (default), done (AC
--- satisfied / milestone reached), blocked (cannot progress, needs action).
--- They mirror the task lifecycle (pending|done|skipped) but substitute
--- 'blocked' for 'skipped' to distinguish an actively-stuck entity from one
--- that was explicitly bypassed.
---
--- D2 (backfill): explicit UPDATE after ALTER ensures pre-existing rows
--- carry 'pending'. The NOT NULL DEFAULT 'pending' covers new rows; the
--- UPDATE covers rows inserted before this migration.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- A failure mid-flight rolls back to v4 state and the ledger row is NOT
--- inserted, so the next bootstrap retry sees the same pending migration.
-
--- 1. Add status column to acceptance_criteria.
-ALTER TABLE acceptance_criteria
-    ADD COLUMN status TEXT NOT NULL DEFAULT 'pending'
-    CHECK (status IN ('pending', 'done', 'blocked'));
-
--- 2. Backfill existing AC rows (D2: explicit UPDATE, all rows -> 'pending').
-UPDATE acceptance_criteria SET status = 'pending' WHERE status IS NULL;
-
--- 3. Add status column to milestones.
-ALTER TABLE milestones
-    ADD COLUMN status TEXT NOT NULL DEFAULT 'pending'
-    CHECK (status IN ('pending', 'done', 'blocked'));
-
--- 4. Backfill existing milestone rows (D2).
-UPDATE milestones SET status = 'pending' WHERE status IS NULL;
-
--- 5. Indexes to support brief-scoped status queries efficiently.
-CREATE INDEX IF NOT EXISTS idx_ac_brief_status
-    ON acceptance_criteria(brief_id, status);
-
-CREATE INDEX IF NOT EXISTS idx_milestones_brief_status
-    ON milestones(brief_id, status);

package/scripts/migrations/v4_to_v5_fresh.sql

@@ -1,20 +0,0 @@
--- v4 -> v5 fresh-install variant.
---
--- Used by bootstrap_database.sh Section 3c case 5 when the live DDL is
--- already at the v5 target state (acceptance_criteria.status column present,
--- milestones.status column present). This happens on a clean install where
--- schema.sql already created the v5 column layout.
---
--- The default v4_to_v5.sql cannot run here because ALTER TABLE ADD COLUMN
--- fails when the column already exists. This variant carries only the DDL
--- that schema.sql cannot declare safely:
---   * idx_ac_brief_status       -- index on acceptance_criteria(brief_id, status)
---   * idx_milestones_brief_status -- index on milestones(brief_id, status)
---
--- Both indexes are CREATE INDEX IF NOT EXISTS, making this script safe to re-run.
-
-CREATE INDEX IF NOT EXISTS idx_ac_brief_status
-    ON acceptance_criteria(brief_id, status);
-
-CREATE INDEX IF NOT EXISTS idx_milestones_brief_status
-    ON milestones(brief_id, status);