create-claude-cabinet 0.20.0 → 0.22.0

package/README.md

@@ -178,6 +178,7 @@ source code.
 ├── skills/          # orient, debrief, plan, execute, audit, etc.
 │   └── cabinet-*/   # 31 cabinet member definitions
 ├── cabinet/         # committees, lifecycle, composition patterns
+│                    #   (incl. pib-db-access.md, pib-db-triggers.md)
 ├── briefing/        # project briefing templates
 ├── hooks/           # git guardrails, telemetry
 ├── rules/           # enforcement pipeline

package/lib/omega-setup.js

@@ -121,6 +121,39 @@ function setupOmega() {
           results.push('Downloaded cross-encoder reranker model');
         }
       } catch { /* non-fatal */ }
+
+      // Ensure MCP server extra is installed (added in v0.21)
+      try {
+        execSync(`"${VENV_PYTHON}" -c "import mcp"`, { stdio: 'pipe' });
+      } catch {
+        console.log('  Installing MCP server support...');
+        try {
+          execSync(`"${VENV_PYTHON}" -m pip install --quiet "omega-memory[server]"`, {
+            stdio: 'pipe', timeout: 120000,
+          });
+          results.push('Installed MCP server support');
+        } catch { /* non-fatal */ }
+      }
+
+      // Ensure omega MCP server is registered in global settings
+      try {
+        const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+        let settings = {};
+        if (fs.existsSync(settingsPath)) {
+          try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { settings = {}; }
+        }
+        if (!settings.mcpServers) settings.mcpServers = {};
+        if (!settings.mcpServers.omega) {
+          settings.mcpServers.omega = {
+            command: path.join(VENV_DIR, 'bin', 'omega'),
+            args: ['serve'],
+          };
+          fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+          fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+          results.push('Registered omega MCP server (global settings)');
+        }
+      } catch { /* non-fatal */ }
+
       return results;
     } catch {
       // Venv is broken — nuke and rebuild (D5)
@@ -133,13 +166,13 @@ function setupOmega() {
   execSync(`"${pythonPath}" -m venv "${VENV_DIR}"`, { stdio: 'pipe' });
   results.push('Created venv at ~/.claude-cabinet/omega-venv/');
 
-  // 4. Install omega-memory
+  // 4. Install omega-memory (with MCP server support)
   console.log('  Installing omega-memory...');
-  execSync(`"${VENV_PYTHON}" -m pip install --quiet omega-memory`, {
+  execSync(`"${VENV_PYTHON}" -m pip install --quiet "omega-memory[server]"`, {
     stdio: 'pipe',
     timeout: 120000,
   });
-  results.push('Installed omega-memory');
+  results.push('Installed omega-memory (with MCP server)');
 
   // 5. Download embedding model at install time (D4)
   console.log('  Downloading embedding model...');
@@ -179,6 +212,41 @@ function setupOmega() {
     results.push('Omega hooks setup skipped (run `omega hooks setup` manually)');
   }
 
+  // 8. Register omega MCP server in global settings
+  //    This enables omega_store(), omega_query(), etc. as MCP tools
+  //    available to Claude Code directly (not just via hooks).
+  console.log('  Registering omega MCP server...');
+  try {
+    // Smoke-test: verify `omega serve` can start (requires mcp package)
+    execSync(
+      `echo '{}' | "${path.join(VENV_DIR, 'bin', 'omega')}" serve 2>&1 | head -1`,
+      { stdio: 'pipe', timeout: 10000 }
+    );
+
+    const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { settings = {}; }
+    }
+    if (!settings.mcpServers) settings.mcpServers = {};
+
+    // Only add if not already configured
+    if (!settings.mcpServers.omega) {
+      settings.mcpServers.omega = {
+        command: path.join(VENV_DIR, 'bin', 'omega'),
+        args: ['serve'],
+      };
+      fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+      results.push('Registered omega MCP server (global settings)');
+    } else {
+      results.push('Omega MCP server already registered');
+    }
+  } catch {
+    // Non-fatal — MCP tools are a convenience, hooks still work
+    results.push('Omega MCP server registration skipped (run `omega serve` manually to test)');
+  }
+
   return results;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/briefing/_briefing-work-tracking-template.md

@@ -16,3 +16,23 @@ How this project tracks planned work. Skills that manage work items
 *How to create, update, and close items.*
 *Example: `POST /api/tasks` with JSON body*
 *Example: `gh issue create --title "..." --body "..."`*
+
+## Deferring work
+
+*When to defer plainly vs. attach a trigger condition.*
+
+Plain deferral (`status='deferred'` on actions, `status='someday'`
+on projects) is for work that's blocked by something else you're
+already tracking. It sits quietly until you unblock it yourself.
+
+**Trigger-gated deferral** is for work waiting on an identifiable
+external condition — a dependency landing, a stack decision
+finalizing, a referenced file appearing. Every session, orient
+re-evaluates each trigger against the current session's context
+and surfaces items whose conditions have fired. Use
+`pib_defer_with_trigger` (or `defer-with-trigger` CLI). See
+`cabinet/pib-db-triggers.md` for the full convention.
+
+Rule of thumb: if you can write one sentence describing what would
+have to be true for this item to matter again, that sentence is
+the trigger.

package/templates/cabinet/pib-db-access.md

@@ -25,18 +25,32 @@ Check: are pib_* MCP tools available?
 
 ## Available Operations
 
-| MCP Tool               | CLI Equivalent                          | Description                    |
-| ---------------------- | --------------------------------------- | ------------------------------ |
-| pib_create_project     | create-project "name" --area X          | Create a project               |
-| pib_list_projects      | list-projects                           | List active projects           |
-| pib_create_action      | create-action "text" --notes X          | Create an action (work item)   |
-| pib_list_actions       | list-actions [--status X]               | List actions                   |
-| pib_update_action      | update-action fid --status X            | Update action fields           |
-| pib_complete_action    | complete-action fid                     | Mark action done               |
-| pib_ingest_findings    | ingest-findings run-dir                 | Ingest audit findings          |
-| pib_triage             | triage finding-id status [notes]        | Triage a finding               |
-| pib_triage_history     | triage-history                          | Get suppression list           |
-| pib_query              | query "SQL"                             | Run arbitrary SQL              |
+| MCP Tool                   | CLI Equivalent                                  | Description                    |
+| -------------------------- | ----------------------------------------------- | ------------------------------ |
+| pib_create_project         | create-project "name" --area X                  | Create a project               |
+| pib_list_projects          | list-projects                                   | List active projects           |
+| pib_create_action          | create-action "text" --notes X                  | Create an action (work item)   |
+| pib_list_actions           | list-actions [--status X]                       | List actions                   |
+| pib_update_action          | update-action fid --status X                    | Update action fields           |
+| pib_complete_action        | complete-action fid                             | Mark action done               |
+| pib_defer_with_trigger     | defer-with-trigger fid --trigger "<text>"       | Defer with a return condition  |
+| pib_list_triggered         | list-triggered [--include-done]                 | List items waiting on triggers |
+| pib_mark_trigger_checked   | mark-trigger-checked fid --result <value>       | Record a trigger evaluation    |
+| pib_ingest_findings        | ingest-findings run-dir                         | Ingest audit findings          |
+| pib_triage                 | triage finding-id status [notes]                | Triage a finding               |
+| pib_triage_history         | triage-history                                  | Get suppression list           |
+| pib_query                  | query "SQL"                                     | Run arbitrary SQL              |
+
+## Deferred triggers
+
+When deferring an item that waits on a specific identifiable
+condition — a dependency landing, a stack decision finalizing, a
+referenced file appearing — use `pib_defer_with_trigger` instead of
+plain `status='deferred'`. Orient re-evaluates each trigger every
+session and surfaces items whose conditions have become true. See
+[pib-db-triggers.md](pib-db-triggers.md) for the full convention:
+result vocabulary, cascade semantics for projects, migration
+guarantees, and known limitations.
 
 ## Surface Area Validation
 

package/templates/cabinet/pib-db-triggers.md

@@ -0,0 +1,192 @@
+# pib-db Deferred Triggers
+
+How to defer work items with structured return conditions and how
+orient re-evaluates them each session.
+
+## Purpose
+
+Big ideas tend to rot. Someone raises an infrastructure proposal, a
+platform-auth gap, or a stack-choice pivot — the idea is real, but it
+cannot be acted on today. Without structure, it lands in `feedback/`
+or a `status='deferred'` row and sits there forever. Nobody re-reads
+`feedback/`. Nobody scans deferred items.
+
+Deferred triggers turn those items into structurally-encoded work:
+each one carries a natural-language condition describing what would
+have to change to reactivate it. Orient surfaces them every session
+and evaluates the condition against the current session's context.
+The item sits in the queue, not on a reminder list.
+
+## Schema
+
+- `actions.trigger_condition TEXT` — natural-language predicate.
+  `NULL` means the action is not trigger-gated. Non-null means the
+  action is waiting on a specific condition.
+- `projects.trigger_condition TEXT` — same semantics for projects.
+- `trigger_checks` table — append-only history of evaluations.
+  Fields: `id`, `target_table`, `target_fid`, `checked_at`, `result`,
+  `notes`. No foreign key back to `actions`/`projects`, so history
+  is preserved even if the item is deleted.
+
+## API
+
+Three operations. Prefer MCP tools; fall back to CLI.
+
+### `pib_defer_with_trigger(fid, triggerCondition, cascade?)`
+
+Use when deferring with a specific return condition. Prefer over
+`pib_update_action` with `status='deferred'` when the deferral is
+conditional on something identifiable.
+
+- Action: sets `status='deferred'` and writes `trigger_condition`.
+- Project: sets `status='someday'` and writes `trigger_condition`.
+- If a project has open child actions, `cascade: true` is required.
+  See [Cascade semantics](#cascade-semantics-for-projects).
+
+CLI:
+```bash
+node scripts/pib-db.mjs defer-with-trigger <fid> --trigger "<text>" [--cascade]
+```
+
+### `pib_list_triggered({includeDone?})`
+
+Returns items with `trigger_condition` set. By default excludes
+completed items; pass `includeDone: true` to include them.
+
+CLI:
+```bash
+node scripts/pib-db.mjs list-triggered [--include-done]
+```
+
+### `pib_mark_trigger_checked(fid, result, notes?)`
+
+Records an evaluation outcome into `trigger_checks`. Does not change
+the item's `status` or `trigger_condition` — reactivation is a
+separate explicit action taken by the user or orient.
+
+CLI:
+```bash
+node scripts/pib-db.mjs mark-trigger-checked <fid> --result <value> [--notes "<text>"]
+```
+
+## Result vocabulary
+
+Four values. The CHECK constraint on `trigger_checks.result` rejects
+anything else.
+
+- `triggered` — the condition is now met; the item is ready to
+  reactivate. Surface in Attention Items. Do not auto-reopen —
+  leave the decision to the user.
+- `still-waiting` — condition checked, not yet met. Normal idle state.
+- `needs-info` — cannot evaluate from current session context. Flag
+  for the user; do not guess `triggered`. When in doubt, pick this.
+- `condition-obsolete` — the condition no longer makes sense. Example:
+  "when we add Postgres support" but Postgres was dropped from the
+  roadmap. Triggers a review of whether to drop the item entirely or
+  rewrite the trigger.
+
+## When to use vs plain deferred
+
+| Situation | Mechanism |
+|---|---|
+| Blocked by something else on your plate right now | `status='deferred'` (no trigger) |
+| Waiting for a specific external condition, needs monitoring | `trigger_condition` |
+| Vague future intent, no specific signal | project `status='someday'` (no trigger) |
+| "Someday, specifically when X happens" | project `trigger_condition` |
+
+Rule of thumb: if you can write one sentence describing what would
+have to be true for the item to matter again, that sentence is the
+trigger. If you can't, it's plain deferred/someday.
+
+## Cascade semantics for projects
+
+Deferring a project with open child actions requires `cascade: true`.
+The cascade:
+
+1. Sets each open child action to `status='deferred'`.
+2. Appends an inheritance line to each child's notes:
+   `_Deferred alongside parent prj:abc (trigger: <text>)_`
+3. Does NOT write `trigger_condition` to children. The parent's
+   trigger is the single source of truth.
+
+When the parent reopens (user flips status back to `active`, or
+orient surfaces it as `triggered` and the user accepts):
+
+- Children remain `deferred`.
+- The user decides which children to reopen. Reopening everything
+  automatically often resurrects stale subgoals that the deferral
+  period should have retired.
+
+## Orient integration
+
+The `deferred-check.md` phase fires after `work-scan.md`, before
+`auto-maintenance.md`. Every session:
+
+1. Orient calls `pib_list_triggered` (or CLI fallback).
+2. For each item, evaluates the trigger text against the current
+   session's context (new dependencies installed? a referenced file
+   now exists? a stack decision was finalized?).
+3. Records each evaluation via `pib_mark_trigger_checked`. Prefer
+   `needs-info` over guessing `triggered`.
+4. Items that evaluate to `triggered` appear in the briefing's
+   **Attention Items** section. Orient does not auto-reopen — the
+   user decides.
+
+Cost control: cap the phase at 30 seconds. If more than 10 items are
+triggered, evaluate only the 5 least-recently-checked.
+
+## Migration guarantees
+
+- **Additive-only.** New columns and new tables are allowed through
+  the `migrate()` path. Destructive changes (dropping columns,
+  changing types, removing constraints) require a new versioned
+  migration with explicit approval — they do not belong in the
+  default path.
+- **Gated on every startup.** Migrations run on every MCP startup
+  and every CLI invocation, gated by `PRAGMA user_version`. Only
+  pending migrations apply; the path is idempotent.
+- **Per-worktree.** Each worktree's local `pib.db` migrates
+  independently. Migrations run against whichever DB the process
+  opens. This is normal SQLite worktree behavior.
+- **Schema parity invariant.** Any new `trigger_*` column added to
+  `actions` MUST also be added to `projects` in the same migration.
+  The two tables mirror each other for trigger semantics.
+
+## Index placement rule
+
+If any future index references a column added through the `migrate()`
+path, the index must also be created via `migrate()`, NOT in the
+`SCHEMA` block's `CREATE INDEX IF NOT EXISTS` stanza.
+
+Reason: the `SCHEMA` block runs before ALTER TABLE migrations.
+Indexing a yet-to-exist column errors on existing databases. The
+rule is mechanical — add the column in migrate(), add the index in
+migrate(), in that order.
+
+## CLI equivalents
+
+```bash
+node scripts/pib-db.mjs defer-with-trigger <fid> --trigger "<text>" [--cascade]
+node scripts/pib-db.mjs list-triggered [--include-done]
+node scripts/pib-db.mjs mark-trigger-checked <fid> --result <value> [--notes "<text>"]
+```
+
+All three map 1:1 to the library functions in `pib-db-lib.mjs`. Use
+MCP tools when available; the CLI is the fallback for non-MCP
+contexts.
+
+## Known limitations
+
+- **Trigger evaluation is LLM-semantic, not deterministic.** Two
+  sessions may evaluate the same trigger differently. The
+  `trigger_checks` history is the audit trail — read it to see how
+  past sessions interpreted the same condition.
+- **No forcing function between sessions.** If a trigger sits
+  unchecked across many sessions (no orient runs), nothing forces
+  evaluation. Worst case: a `triggered` item sits unnoticed for a
+  week. Acceptable soft limit; the alternative (scheduled jobs) adds
+  infrastructure we don't want.
+- **Concurrent migration race, theoretical.** SQLite handles locking,
+  but a race on `PRAGMA user_version` is theoretically possible if
+  two MCP processes open the DB at the same instant. In practice,
+  MCP servers are per-session and the window is microseconds.

package/templates/hooks/omega-memory-guard.sh

@@ -27,14 +27,12 @@ if [ -z "$FILE_PATH" ]; then
 fi
 
 # Only care about memory directory paths
-case "$FILE_PATH" in
-  *.claude/memory/*|*.claude/projects/*/memory/*)
-    ;;
-  *)
-    echo '{"decision":"allow"}'
-    exit 0
-    ;;
-esac
+# Note: case patterns with * don't cross / boundaries in some shells,
+# so we use [[ ]] substring matching for absolute path compatibility.
+if [[ "$FILE_PATH" != *"/.claude/memory/"* ]] && [[ "$FILE_PATH" != *"/.claude/projects/"*"/memory/"* ]]; then
+  echo '{"decision":"allow"}'
+  exit 0
+fi
 
 # Allow MEMORY.md index files (structural, not memory content)
 BASENAME=$(basename "$FILE_PATH")

package/templates/rules/memory-capture.md

@@ -56,3 +56,24 @@ verbally, or a constraint discovered through external research).
 Over-capturing degrades retrieval quality. The test: *"Would a future
 session benefit from knowing this?"* If yes, capture it. If it's just
 noise or ephemera, skip it.
+
+## Known Limitation: Auto-Memory System Prompt Conflict
+
+Claude Code's built-in auto-memory system prompt describes a file-based
+`.md` memory system (`/Users/<user>/.claude/projects/<project>/memory/`).
+When omega is active, this conflicts — the system prompt tells Claude to
+write `.md` files while CLAUDE.md and this rules file tell it to use
+omega. The system prompt's instructions are strong and may override
+project-level rules in some sessions.
+
+**Mitigations:**
+- The `omega-memory-guard` PreToolUse hook blocks flat markdown writes
+  when omega is available (structural enforcement, ~100% reliable)
+- This rules file and CLAUDE.md omega instructions provide prompt-level
+  guidance (~80% reliable)
+- If Claude creates a `.md` memory file despite these, the guard will
+  block it and redirect to `omega_store()`
+
+This is a platform limitation — the auto-memory system prompt cannot
+be suppressed from project configuration. The guard hook is the
+primary defense.

package/templates/scripts/pib-db-lib.mjs

@@ -23,24 +23,68 @@ function today() {
 }
 
 // ---------------------------------------------------------------------------
-// Init — create tables from schema
+// Migrations — gated by PRAGMA user_version
+// ---------------------------------------------------------------------------
+// SCHEMA_VERSION history:
+//   1 — added actions.status CHECK constraint
+//   2 — added actions.tags
+//   3 — added trigger_condition on actions/projects + trigger_checks history
+//   4 — composite index on trigger_checks(target_fid, checked_at DESC) for listTriggered
+export const SCHEMA_VERSION = 4;
+
+// Each entry: { version, sql }. A single version may have multiple SQL
+// statements (e.g. column add + index). Statements run in array order;
+// each is wrapped in try/catch so re-running on a DB that already has
+// the column/table is a no-op. The user_version pragma is the primary
+// gate — try/catch is a safety net for pre-pragma DBs.
+const MIGRATIONS = [
+  { version: 1, sql: "ALTER TABLE actions ADD COLUMN status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open','in-progress','blocked','deferred','done'))" },
+  { version: 2, sql: "ALTER TABLE actions ADD COLUMN tags TEXT NOT NULL DEFAULT ''" },
+  { version: 3, sql: "ALTER TABLE actions ADD COLUMN trigger_condition TEXT" },
+  { version: 3, sql: "ALTER TABLE projects ADD COLUMN trigger_condition TEXT" },
+  { version: 3, sql: `CREATE TABLE IF NOT EXISTS trigger_checks (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    target_table  TEXT NOT NULL CHECK(target_table IN ('actions','projects')),
+    target_fid    TEXT NOT NULL,
+    checked_at    TEXT NOT NULL,
+    result        TEXT NOT NULL CHECK(result IN ('triggered','still-waiting','needs-info','condition-obsolete')),
+    notes         TEXT
+  )` },
+  { version: 3, sql: "CREATE INDEX IF NOT EXISTS idx_trigger_checks_fid ON trigger_checks(target_fid)" },
+  { version: 4, sql: "CREATE INDEX IF NOT EXISTS idx_trigger_checks_target_time ON trigger_checks(target_fid, checked_at DESC)" },
+];
+
+export function migrate(db) {
+  const current = db.pragma('user_version', { simple: true });
+  if (current >= SCHEMA_VERSION) return { from: current, to: current, applied: 0 };
+
+  // Wrap in a transaction so a real mid-migration failure (disk full,
+  // locked DB, constraint violation) rolls back user_version along with
+  // the partial DDL. Only swallow "already exists" errors from legacy
+  // pre-pragma DBs where columns may have been added before versioning.
+  const tx = db.transaction(() => {
+    let applied = 0;
+    for (const m of MIGRATIONS) {
+      if (m.version <= current) continue;
+      try { db.exec(m.sql); applied++; }
+      catch (e) {
+        if (!/already exists|duplicate column/i.test(e.message || '')) throw e;
+      }
+    }
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
+    return applied;
+  });
+  const applied = tx();
+  return { from: current, to: SCHEMA_VERSION, applied };
+}
+
+// ---------------------------------------------------------------------------
+// Init — create tables from schema, then migrate
 // ---------------------------------------------------------------------------
 export function init(db, { schemaPath }) {
   const schema = readFileSync(schemaPath, 'utf-8');
   db.exec(schema);
-
-  // Migrate existing DBs — add columns that may not exist yet
-  const migrations = [
-    { table: 'actions', column: 'status', sql: "ALTER TABLE actions ADD COLUMN status TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open','in-progress','blocked','deferred','done'))" },
-    { table: 'actions', column: 'tags', sql: "ALTER TABLE actions ADD COLUMN tags TEXT NOT NULL DEFAULT ''" },
-  ];
-  for (const m of migrations) {
-    const cols = db.prepare(`PRAGMA table_info(${m.table})`).all();
-    if (!cols.some(c => c.name === m.column)) {
-      try { db.exec(m.sql); } catch { /* column may already exist */ }
-    }
-  }
-
+  migrate(db);
   return { message: `Database initialized` };
 }
 
@@ -291,3 +335,132 @@ export function triageHistory(db) {
     deferredFingerprints: deferred.map(r => ({ 'cabinet-member': r.cabinet_member, title: r.title })),
   };
 }
+
+// ---------------------------------------------------------------------------
+// Deferred triggers
+// ---------------------------------------------------------------------------
+// Items (actions or projects) with a trigger_condition are waiting on a
+// specific condition. The orient skill re-evaluates them each session and
+// records each check in trigger_checks (append-only history).
+
+export const TRIGGER_RESULT_VOCABULARY = ['triggered', 'still-waiting', 'needs-info', 'condition-obsolete'];
+export const FID_PATTERN = /^(act|prj):[a-f0-9]{8}$/;
+const TRIGGER_CONDITION_MAX_LENGTH = 2000;
+
+function validateFid(fid) {
+  if (!fid || typeof fid !== 'string') {
+    return { error: 'missing_fid', message: 'fid is required' };
+  }
+  if (!FID_PATTERN.test(fid)) {
+    return { error: 'invalid_fid_format', message: `fid must match ${FID_PATTERN}, got "${fid}"` };
+  }
+  return null;
+}
+
+function tableForFid(fid) {
+  return fid.startsWith('prj:') ? 'projects' : 'actions';
+}
+
+export function deferWithTrigger(db, { fid, triggerCondition, cascade = false } = {}) {
+  const fidError = validateFid(fid);
+  if (fidError) return { error: fidError };
+  if (!triggerCondition || typeof triggerCondition !== 'string' || triggerCondition.trim() === '') {
+    return { error: { error: 'missing_trigger_condition', message: 'triggerCondition must be a non-empty string' } };
+  }
+  if (triggerCondition.length > TRIGGER_CONDITION_MAX_LENGTH) {
+    return { error: { error: 'trigger_condition_too_long', message: `triggerCondition must be ≤${TRIGGER_CONDITION_MAX_LENGTH} chars, got ${triggerCondition.length}` } };
+  }
+
+  const table = tableForFid(fid);
+  const row = db.prepare(`SELECT status, ${table === 'actions' ? 'completed' : "'0' as completed"} FROM ${table} WHERE fid = ? AND deleted_at IS NULL`).get(fid);
+  if (!row) return { error: { error: 'not_found', message: `No ${table} row with fid ${fid}` } };
+  if (row.status === 'done' || row.completed === 1) {
+    return { error: { error: 'already_done', message: `${fid} is already done; cannot defer` } };
+  }
+
+  let cascaded = 0;
+  if (table === 'projects') {
+    // Children with their own trigger_condition already carry their own
+    // return condition; cascade leaves them alone so the parent's trigger
+    // doesn't overwrite their independent wait state.
+    const openChildren = db.prepare(`SELECT fid FROM actions WHERE project_fid = ? AND status NOT IN ('done','deferred') AND trigger_condition IS NULL AND deleted_at IS NULL`).all(fid);
+    if (openChildren.length > 0 && !cascade) {
+      return {
+        error: {
+          error: 'has_open_children',
+          message: `Project ${fid} has ${openChildren.length} open action(s) without their own trigger. Pass cascade: true to defer them alongside.`,
+          openChildren: openChildren.map(c => c.fid),
+        },
+      };
+    }
+    if (cascade) {
+      const appendNote = `\n\n_Deferred alongside parent ${fid} (trigger: ${triggerCondition})_`;
+      const stmt = db.prepare(`UPDATE actions SET status = 'deferred', notes = notes || ? WHERE fid = ?`);
+      for (const child of openChildren) stmt.run(appendNote, child.fid);
+      cascaded = openChildren.length;
+    }
+  }
+
+  const newStatus = table === 'projects' ? 'someday' : 'deferred';
+  db.prepare(`UPDATE ${table} SET status = ?, trigger_condition = ? WHERE fid = ?`).run(newStatus, triggerCondition, fid);
+
+  return { fid, table, triggerCondition, status: newStatus, cascaded, message: `Deferred ${fid} with trigger` };
+}
+
+export function listTriggered(db, { includeDone = false } = {}) {
+  const actionsWhere = includeDone
+    ? 'a.trigger_condition IS NOT NULL AND a.deleted_at IS NULL'
+    : "a.trigger_condition IS NOT NULL AND a.deleted_at IS NULL AND a.status != 'done' AND (a.completed IS NULL OR a.completed = 0)";
+  const projectsWhere = includeDone
+    ? 'p.trigger_condition IS NOT NULL AND p.deleted_at IS NULL'
+    : "p.trigger_condition IS NOT NULL AND p.deleted_at IS NULL AND p.status != 'done'";
+
+  const actions = db.prepare(`
+    SELECT a.fid, a.text, a.trigger_condition, a.status, p.name AS project_name,
+      (SELECT checked_at FROM trigger_checks WHERE target_fid = a.fid ORDER BY checked_at DESC LIMIT 1) AS last_checked,
+      (SELECT result FROM trigger_checks WHERE target_fid = a.fid ORDER BY checked_at DESC LIMIT 1) AS last_result
+    FROM actions a
+    LEFT JOIN projects p ON a.project_fid = p.fid
+    WHERE ${actionsWhere}
+    ORDER BY last_checked IS NOT NULL, last_checked ASC
+  `).all();
+
+  const projects = db.prepare(`
+    SELECT p.fid, p.name, p.trigger_condition, p.status,
+      (SELECT checked_at FROM trigger_checks WHERE target_fid = p.fid ORDER BY checked_at DESC LIMIT 1) AS last_checked,
+      (SELECT result FROM trigger_checks WHERE target_fid = p.fid ORDER BY checked_at DESC LIMIT 1) AS last_result
+    FROM projects p
+    WHERE ${projectsWhere}
+    ORDER BY last_checked IS NOT NULL, last_checked ASC
+  `).all();
+
+  return { actions, projects };
+}
+
+export function markTriggerChecked(db, { fid, result, notes } = {}) {
+  const fidError = validateFid(fid);
+  if (fidError) return { error: fidError };
+  if (!TRIGGER_RESULT_VOCABULARY.includes(result)) {
+    return {
+      error: {
+        error: 'invalid_result',
+        message: `result must be one of: ${TRIGGER_RESULT_VOCABULARY.join(', ')}`,
+        got: result,
+      },
+    };
+  }
+  const table = tableForFid(fid);
+  const row = db.prepare(`SELECT status, ${table === 'actions' ? 'completed' : "'0' as completed"} FROM ${table} WHERE fid = ? AND deleted_at IS NULL`).get(fid);
+  if (!row) return { error: { error: 'not_found', message: `No ${table} row with fid ${fid}` } };
+  if (row.status === 'done' || row.completed === 1) {
+    return { error: { error: 'already_done', message: `${fid} is already done; recording a trigger check on a completed item is not allowed` } };
+  }
+
+  const checkedAt = new Date().toISOString();
+  db.prepare(`
+    INSERT INTO trigger_checks (target_table, target_fid, checked_at, result, notes)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(table, fid, checkedAt, result, notes || null);
+
+  return { fid, checkedAt, result, message: `Recorded trigger check for ${fid}: ${result}` };
+}