@jaguilar87/gaia 5.0.4 → 5.0.6

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

package/scripts/migrations/v5_to_v6.sql

@@ -1,48 +0,0 @@
--- Migration v5 -> v6 (evidence three-tier storage: dedicated evidence table).
---
--- Background
--- ----------
--- v5 schema has:
---   acceptance_criteria(id, brief_id, ac_id, description, evidence_type,
---                        evidence_shape, artifact_path, status)
---   milestones(id, brief_id, order_num, name, description, status)
---
--- v6 schema adds the evidence table for structured per-AC evidence storage.
--- Each row is one evidence artifact tied to a brief_id + ac_id pair.
--- Two storage modes:
---   inline: text IS NOT NULL, artifact_path IS NULL  (payload <= 4096 bytes)
---   blob:   text IS NULL,     artifact_path IS NOT NULL (payload on filesystem)
---
--- Design decision: independent migration version
--- ------------------------------------------------
--- Evidence is an independent feature (Plan B). Extending v4_to_v5 with this
--- DDL would have conflated two unrelated concerns in one migration version.
--- The override decision (D4 of Plan A) establishes that each independent
--- feature gets its own migration version -- evidence belongs in v6.
---
--- brief_id FK CASCADE ensures cleanup when a brief is deleted.
--- type CHECK enforces the evidence taxonomy at the DB layer (new table,
--- no rebuild penalty unlike the memory.class situation).
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- A failure mid-flight rolls back to v5 state and the ledger row is NOT
--- inserted, so the next bootstrap retry sees the same pending migration.
-
--- 1. Create the evidence table.
-CREATE TABLE IF NOT EXISTS evidence (
-    id               INTEGER PRIMARY KEY AUTOINCREMENT,
-    brief_id         INTEGER NOT NULL,
-    ac_id            TEXT NOT NULL,
-    task_id          TEXT,
-    type             TEXT NOT NULL CHECK (type IN ('text', 'file', 'command_output', 'url', 'screenshot')),
-    text             TEXT,
-    artifact_path    TEXT,
-    size_bytes       INTEGER,
-    created_at       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
-    created_by_agent TEXT,
-    FOREIGN KEY (brief_id) REFERENCES briefs(id) ON DELETE CASCADE
-);
-
--- 2. Indexes to support brief-scoped and AC-scoped evidence queries.
-CREATE INDEX IF NOT EXISTS idx_evidence_brief ON evidence(brief_id);
-CREATE INDEX IF NOT EXISTS idx_evidence_ac ON evidence(brief_id, ac_id);

package/scripts/migrations/v5_to_v6_fresh.sql

@@ -1,17 +0,0 @@
--- v5 -> v6 fresh-install variant.
---
--- Used by bootstrap_database.sh Section 3c case 6 when the live DDL is
--- already at the v6 target state (evidence table present). This happens on
--- a clean install where schema.sql already created the evidence table.
---
--- The default v5_to_v6.sql cannot run here because CREATE TABLE IF NOT EXISTS
--- is a no-op when the table already exists, but the indexes must still be
--- stamped. This variant carries only the DDL that schema.sql cannot declare
--- safely for older DBs:
---   * idx_evidence_brief -- index on evidence(brief_id)
---   * idx_evidence_ac    -- index on evidence(brief_id, ac_id)
---
--- Both indexes are CREATE INDEX IF NOT EXISTS, making this script safe to re-run.
-
-CREATE INDEX IF NOT EXISTS idx_evidence_brief ON evidence(brief_id);
-CREATE INDEX IF NOT EXISTS idx_evidence_ac ON evidence(brief_id, ac_id);

package/scripts/migrations/v6_to_v7.sql

@@ -1,26 +0,0 @@
--- Migration v6 -> v7 (agent-contract-handoff M1: workspaces.last_scan_at)
---
--- Background
--- ----------
--- v6 schema has:
---   workspaces(name, identity, created_at)
---
--- v7 adds last_scan_at (ISO8601 TEXT, nullable) to workspaces.
--- NULL means "never scanned via gaia scan" -- not 'pending'.
--- The column is written by bin/cli/scan.py after a successful scan run.
---
--- Design decision: independent migration version
--- -----------------------------------------------
--- workspaces.last_scan_at is the first column added to workspaces.
--- It belongs in v7, owned by the agent-contract-handoff brief (M1).
--- M3 and M4 will add further columns in later v7 sub-tasks of the
--- same migration file (both will extend this file in their dispatches).
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- A failure mid-flight rolls back to v6 state and the ledger row is NOT
--- inserted, so the next bootstrap retry sees the same pending migration.
-
--- 1. Add last_scan_at column to workspaces.
---    SQLite ALTER TABLE ADD COLUMN is safe for nullable columns.
-ALTER TABLE workspaces ADD COLUMN last_scan_at TEXT;
-

package/scripts/migrations/v6_to_v7_fresh.sql

@@ -1,13 +0,0 @@
--- Migration v6 -> v7 fresh-install variant (agent-contract-handoff M1)
---
--- Used by bootstrap_database.sh when the live DB already has last_scan_at
--- (i.e. schema.sql ran first on a clean install and created workspaces with
--- the v7 column already present). This variant is a no-op -- it only exists
--- so the bootstrap guard-probe branch can select it and stamp the ledger.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- No DDL is executed; the COMMIT is harmless.
-
--- No-op: column already exists on fresh install (schema.sql created it).
--- This variant only exists to stamp the ledger without applying DDL.
-SELECT 1;

package/scripts/migrations/v7_to_v8.sql

@@ -1,44 +0,0 @@
--- Migration v7 -> v8 (agent-contract-handoff M3: approval_grants table)
---
--- Background
--- ----------
--- v7 schema has:
---   workspaces(name, identity, created_at, last_scan_at)
---
--- v8 adds the approval_grants table for DB-backed T3 command approval storage.
--- This replaces the filesystem JSON approval store (.claude/cache/approvals/).
--- Per D5 / D10: no TTL column (enforced at query time via created_at + 10 min);
--- byte-for-byte command match; each command_set item is single-use.
---
--- Design decision: v8 bump (option a)
--- ------------------------------------
--- The approval_grants table was previously appended to v6_to_v7.sql as a
--- supplemental idempotent block.  That approach conflated two unrelated
--- concerns in one migration version.  v8 is the correct version for M3:
--- each independent feature gets its own migration version (precedent from
--- v5->v6 evidence table decision).  The M3 appended block has been removed
--- from v6_to_v7.sql and moved here.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- A failure mid-flight rolls back to v7 state and the ledger row is NOT
--- inserted, so the next bootstrap retry sees the same pending migration.
-
--- 1. Create the approval_grants table.
-CREATE TABLE IF NOT EXISTS approval_grants (
-    approval_id          TEXT PRIMARY KEY,           -- nonce, e.g. 32-char hex
-    agent_id             TEXT,                       -- agent that initiated the request
-    session_id           TEXT,                       -- CLAUDE_SESSION_ID at grant time
-    command_set_json     TEXT NOT NULL,              -- JSON array of {command, rationale}
-    scope                TEXT NOT NULL DEFAULT 'COMMAND_SET',  -- grant scope type
-    created_at           TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
-    expires_at           TEXT,                       -- ISO8601 or NULL (TTL enforced at query time)
-    status               TEXT NOT NULL DEFAULT 'PENDING',  -- PENDING|CONSUMED|REVOKED|EXPIRED
-    consumed_indexes_json TEXT,                      -- JSON array of consumed command_set indexes
-    consumed_at          TEXT,                       -- ISO8601 when all items consumed
-    revoked_at           TEXT                        -- ISO8601 when explicitly revoked
-);
-
--- 2. Indexes to support agent- and session-scoped approval queries.
-CREATE INDEX IF NOT EXISTS idx_approval_grants_agent   ON approval_grants(agent_id);
-CREATE INDEX IF NOT EXISTS idx_approval_grants_session ON approval_grants(session_id);
-CREATE INDEX IF NOT EXISTS idx_approval_grants_status  ON approval_grants(status);

package/scripts/migrations/v7_to_v8_fresh.sql

@@ -1,14 +0,0 @@
--- Migration v7 -> v8 fresh-install variant (agent-contract-handoff M3)
---
--- Used by bootstrap_database.sh when the live DB already has the approval_grants
--- table (i.e. schema.sql ran first on a clean install and created the table
--- in v8 target state already present).  This variant is a no-op -- it only
--- exists so the bootstrap guard-probe branch can select it and stamp the ledger.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- No DDL is executed; the COMMIT is harmless.
-
--- No-op: approval_grants table already exists on fresh install (schema.sql created it).
--- The indexes are also created by schema.sql on fresh install.
--- This variant only exists to stamp the ledger without applying DDL.
-SELECT 1;

package/scripts/migrations/v8_to_v9.sql

@@ -1,87 +0,0 @@
--- Migration v8 -> v9 (agent-contract-handoff M4: handoff persistence)
---
--- Background
--- ----------
--- v8 schema has:
---   approval_grants(approval_id, agent_id, session_id, command_set_json, ...)
---
--- v9 adds:
---   agent_contract_handoffs           -- persisted SubagentStop contract envelopes
---   agent_contract_handoff_approvals  -- approval decisions linked to handoffs
---   project_context_contracts_history -- audit trail for PCC mutations
---   trg_pcc_history                   -- AFTER UPDATE trigger on project_context_contracts
---
--- Design decisions
--- ----------------
--- * brief_id is NULLABLE -- subagents that return without a brief context
---   still get a handoff row. EXTENSION_POINT for state-machine-completion:
---   downstream briefs can query WHERE brief_id = <N> to verify completion
---   invariants across the handoff record.
--- * agent_contract_handoff_approvals CASCADE-deletes when the handoff row
---   is removed. approval_id FK references approval_grants for audit integrity.
--- * project_context_contracts_history captures before/after payloads at the
---   SQL layer -- no Python path can bypass the trigger.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- A failure mid-flight rolls back to v8 state; the ledger row is NOT
--- inserted, so the next bootstrap retry sees the same pending migration.
-
--- 1. Create the agent_contract_handoffs table.
-CREATE TABLE IF NOT EXISTS agent_contract_handoffs (
-    id               INTEGER PRIMARY KEY AUTOINCREMENT,
-    agent_id         TEXT NOT NULL,               -- e.g. "a1b2c3d4e5"
-    session_id       TEXT,                        -- CLAUDE_SESSION_ID at SubagentStop time
-    workspace        TEXT NOT NULL,               -- FK -> workspaces.name
-    brief_id         INTEGER,                     -- NULLABLE FK -> briefs.id; EXTENSION_POINT
-    task_status      TEXT NOT NULL,               -- resolved plan_status from contract envelope
-    raw_handoff_json TEXT NOT NULL,               -- full contract envelope serialized
-    created_at       TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
-    FOREIGN KEY (workspace) REFERENCES workspaces(name),
-    FOREIGN KEY (brief_id)  REFERENCES briefs(id)
-);
-
-CREATE INDEX IF NOT EXISTS idx_agent_contract_handoffs_workspace ON agent_contract_handoffs(workspace);
-CREATE INDEX IF NOT EXISTS idx_agent_contract_handoffs_brief     ON agent_contract_handoffs(brief_id);
-CREATE INDEX IF NOT EXISTS idx_agent_contract_handoffs_session   ON agent_contract_handoffs(session_id);
-
--- 2. Create the agent_contract_handoff_approvals table.
-CREATE TABLE IF NOT EXISTS agent_contract_handoff_approvals (
-    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    handoff_id  INTEGER NOT NULL,                -- FK -> agent_contract_handoffs.id
-    approval_id TEXT NOT NULL,                   -- FK -> approval_grants.approval_id
-    decision    TEXT NOT NULL CHECK (decision IN ('APPROVED', 'REJECTED', 'EXPIRED', 'REVOKED')),
-    decided_at  TEXT NOT NULL,
-    FOREIGN KEY (handoff_id)  REFERENCES agent_contract_handoffs(id) ON DELETE CASCADE,
-    FOREIGN KEY (approval_id) REFERENCES approval_grants(approval_id)
-);
-
-CREATE INDEX IF NOT EXISTS idx_agent_contract_handoff_approvals_handoff ON agent_contract_handoff_approvals(handoff_id);
-
--- 3. Create the project_context_contracts_history table.
-CREATE TABLE IF NOT EXISTS project_context_contracts_history (
-    id                  INTEGER PRIMARY KEY AUTOINCREMENT,
-    contract_key        TEXT NOT NULL,            -- project_context_contracts.contract_key
-    workspace           TEXT NOT NULL,            -- FK -> workspaces.name
-    before_payload_json TEXT,                     -- NULL on first insert (no prior value)
-    after_payload_json  TEXT NOT NULL,            -- new payload value
-    changed_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now')),
-    changed_by_agent    TEXT,                     -- optional: GAIA_DISPATCH_AGENT at write time
-    FOREIGN KEY (workspace) REFERENCES workspaces(name)
-);
-
-CREATE INDEX IF NOT EXISTS idx_pcc_history_contract ON project_context_contracts_history(contract_key);
-
--- 4. Create the AFTER UPDATE trigger on project_context_contracts.
-CREATE TRIGGER IF NOT EXISTS trg_pcc_history
-AFTER UPDATE ON project_context_contracts
-BEGIN
-    INSERT INTO project_context_contracts_history (
-        contract_key, workspace, before_payload_json, after_payload_json, changed_at
-    ) VALUES (
-        OLD.contract_key,
-        OLD.workspace,
-        OLD.payload_json,
-        NEW.payload_json,
-        strftime('%Y-%m-%dT%H:%M:%SZ', 'now')
-    );
-END;

package/scripts/migrations/v8_to_v9_fresh.sql

@@ -1,15 +0,0 @@
--- Migration v8 -> v9 fresh-install variant (agent-contract-handoff M4)
---
--- Used by bootstrap_database.sh when the live DB already has the
--- agent_contract_handoffs table (i.e. schema.sql ran first on a clean
--- install and created the tables in v9 target state).
---
--- This variant is a no-op -- it only exists so the bootstrap guard-probe
--- branch can select it and stamp the ledger without applying DDL.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- No DDL is executed; the COMMIT is harmless.
-
--- No-op: all v9 tables and trigger already exist on fresh install (schema.sql).
--- This variant only exists to stamp the ledger.
-SELECT 1;

package/scripts/migrations/v9_to_v10.sql

@@ -1,109 +0,0 @@
--- Migration v9 -> v10 (episodic-workflow-to-db: episodes workspace canonical)
---
--- Background
--- ----------
--- v9 schema has the episodes table with these columns:
---   episode_id, workspace, timestamp, session_id, task_id, agent,
---   type, title, prompt, enriched_prompt, wf_prompt, clarifications,
---   keywords, tags, commands_executed, context_metrics, relevance_score,
---   outcome, duration_seconds, exit_code, plan_status, output_length,
---   output_tokens_approx
---
--- v10 adds:
---   episodes.tier           -- security tier (T0/T1/T2/T3), promoted from context_metrics blob
---   episode_anomalies       -- structured anomaly records extracted from context_metrics blob
---
--- Design decisions
--- ----------------
--- D1: tier -> top-level column (not blob)
---   Rationale: tier is a single short TEXT value (T0/T1/T2/T3) with a clear
---   compliance query pattern: "COUNT(*) WHERE tier='T3' AND outcome='partial'".
---   Keeping it in the context_metrics JSON blob would require a full-table
---   JSON parse for every compliance query. With 10,000+ rows in workspace 'me'
---   alone, this is a significant performance cost. A column + index reduces
---   that to a B-tree lookup. The schema cost is one ALTER TABLE + one index.
---   Alternative considered: keep in blob. Rejected because the query pattern
---   is both real (used by context_injector.py anomaly surfacing) and frequent
---   (every compliance dashboard query). No reason to pay JSON parsing overhead
---   when the data is a four-value enum.
---
--- D2: episode_anomalies -> separate table (not blob)
---   Rationale: anomalies have a stable schema {type, severity, message} per
---   object. The query "all anomalies of type X in the last 7 days" is a real
---   operational need -- context_injector.py currently reads anomalies.jsonl
---   to surface critical anomalies in orchestrator context. That reader must
---   be ported post-migration. A separate table with a type index enables
---   `SELECT * FROM episode_anomalies JOIN episodes ON ... WHERE type=? AND
---   episodes.timestamp > ?` without JSON parsing any rows. With anomalies
---   present in a large fraction of episodes (4 anomalies in the 12 observed
---   sessions), the cardinality justifies a separate table. The anomalies[]
---   array is still preserved inside context_metrics for backward compatibility
---   with any reader that parses the full blob -- the table is an additional
---   queryable index, not a replacement.
---   Alternative considered: keep in context_metrics blob. Rejected because
---   the type-filtered cross-episode query has no efficient implementation
---   without the table. GROUP BY type reports are otherwise O(N) full scans
---   with JSON parsing per row.
---
--- Column notes
--- ------------
--- episodes.workspace: already present in the v9 schema; NO ALTER TABLE needed.
---   Live DB confirmed: workspace column exists and has data ('me', 'bildwiz',
---   'nfi'). The default 'me' for legacy rows is unnecessary -- workspace is
---   already populated. This step is a no-op in terms of DDL.
---
--- Atomicity: bootstrap_database.sh wraps this script in BEGIN/COMMIT.
--- A failure mid-flight rolls back to v9 state; the ledger row is NOT
--- inserted, so the next bootstrap retry sees the same pending migration.
--- Closes AC-2 of brief episodic-workflow-to-db (brief_id=72).
-
--- Step 1: Add tier column to episodes.
--- SQLite does not support CHECK constraints in ALTER TABLE ADD COLUMN without
--- a DEFAULT, so the CHECK is omitted here; validation is enforced at the
--- application layer (episodic.py / workflow_recorder.py writers).
-ALTER TABLE episodes ADD COLUMN tier TEXT;
-
--- Step 2: Index tier for compliance queries.
-CREATE INDEX IF NOT EXISTS idx_episodes_tier ON episodes(tier);
-
--- Step 3: Compound index for the primary compliance query pattern:
--- "T3 operations with non-COMPLETE outcomes in time window".
-CREATE INDEX IF NOT EXISTS idx_episodes_tier_outcome ON episodes(tier, outcome);
-
--- Step 4: Create episode_anomalies table.
--- Each row is one anomaly record extracted from an episode's context_metrics
--- blob. The payload column holds the full original JSON object for forward
--- compatibility (additional keys in future anomaly schemas are preserved).
-CREATE TABLE IF NOT EXISTS episode_anomalies (
-    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    episode_id  TEXT NOT NULL,              -- FK -> episodes.episode_id
-    workspace   TEXT NOT NULL,              -- denormalized for partition queries without JOIN
-    timestamp   TEXT NOT NULL,              -- denormalized from parent episode for time-range queries
-    type        TEXT NOT NULL,              -- e.g. "investigation_skip", "no_tool_use"
-    severity    TEXT,                       -- e.g. "warning", "error", "info"
-    message     TEXT,                       -- human-readable description
-    payload     TEXT,                       -- full JSON object (forward-compat for extra keys)
-    FOREIGN KEY (episode_id) REFERENCES episodes(episode_id) ON DELETE CASCADE
-);
-
--- Step 5: Indexes on episode_anomalies.
--- Primary query patterns:
---   (a) All anomalies of type X: WHERE type = ?
---   (b) Cross-episode anomaly report in time window: WHERE type = ? AND timestamp > ?
---   (c) Anomalies for a specific episode: WHERE episode_id = ?
---   (d) Workspace-scoped anomaly dashboard: WHERE workspace = ? AND timestamp > ?
-CREATE INDEX IF NOT EXISTS idx_episode_anomalies_type      ON episode_anomalies(type);
-CREATE INDEX IF NOT EXISTS idx_episode_anomalies_workspace  ON episode_anomalies(workspace, timestamp DESC);
-CREATE INDEX IF NOT EXISTS idx_episode_anomalies_episode    ON episode_anomalies(episode_id);
-
--- Step 6: Bump schema_version to 10.
-INSERT OR IGNORE INTO schema_version (version, applied_at, description)
-VALUES (10, strftime('%Y-%m-%dT%H:%M:%SZ', 'now'),
-        'episodes.tier column + idx + episode_anomalies table (brief episodic-workflow-to-db AC-2)');
-
--- Verification queries (run after applying):
--- SELECT MAX(version) FROM schema_version;           -- expect: 10
--- PRAGMA table_info(episodes);                       -- expect: tier column present (after output_tokens_approx)
--- SELECT * FROM sqlite_master WHERE type='index' AND name LIKE 'idx_episodes_tier%';  -- expect: 2 rows
--- PRAGMA table_info(episode_anomalies);              -- expect: 7 columns
--- SELECT COUNT(*) FROM episode_anomalies;            -- expect: 0 (populated by T3 migration task)