create-claude-cabinet 0.21.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.21.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/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}` };
+}

package/templates/scripts/pib-db-mcp-server.mjs

@@ -71,6 +71,12 @@ function getDb() {
   db = new Database(DB_PATH);
   db.pragma('journal_mode = WAL');
   db.pragma('foreign_keys = ON');
+
+  // Ensure schema exists, then apply pending migrations. Both are cheap:
+  // the schema file is idempotent (CREATE TABLE IF NOT EXISTS) and migrate()
+  // short-circuits when PRAGMA user_version is already current.
+  const schemaPath = join(__dirname, 'pib-db-schema.sql');
+  lib.init(db, { schemaPath });
   return db;
 }
 
@@ -191,6 +197,46 @@ const TOOLS = [
     description: 'Get the triage suppression list (rejected and deferred findings).',
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'pib_defer_with_trigger',
+    description: 'Defer an action or project with a free-text trigger condition describing what would reactivate it. Orient re-evaluates triggers each session. Use this INSTEAD of pib_update_action with status=deferred when the deferral is waiting for a specific condition.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fid: { type: 'string', description: 'Action or project fid (e.g., act:abc12345 or prj:abc12345)' },
+        triggerCondition: { type: 'string', description: 'Natural-language predicate describing when to reactivate (e.g., "3+ projects calling Claude API directly")' },
+        cascade: { type: 'boolean', description: 'When deferring a project with open child actions, also defer them. Required for projects with open children.' },
+      },
+      required: ['fid', 'triggerCondition'],
+    },
+  },
+  {
+    name: 'pib_list_triggered',
+    description: 'List all items (actions and projects) with an active trigger_condition. Returns two arrays: actions and projects, each with fid, trigger text, last check result, and days since last check.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        includeDone: { type: 'boolean', description: 'Include items already marked done. Default false.' },
+      },
+    },
+  },
+  {
+    name: 'pib_mark_trigger_checked',
+    description: 'Record that a trigger was evaluated. Use after orient\'s deferred-check phase evaluates triggers against session context. Result must be one of: triggered | still-waiting | needs-info | condition-obsolete.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fid: { type: 'string', description: 'Action or project fid' },
+        result: {
+          type: 'string',
+          enum: ['triggered', 'still-waiting', 'needs-info', 'condition-obsolete'],
+          description: 'Outcome of this evaluation',
+        },
+        notes: { type: 'string', description: 'Optional reasoning or context for the evaluation' },
+      },
+      required: ['fid', 'result'],
+    },
+  },
   {
     name: 'pib_query',
     description: 'Run an arbitrary SQL query against the pib database.',
@@ -209,14 +255,6 @@ const TOOLS = [
 // ---------------------------------------------------------------------------
 function handleToolCall(name, args) {
   const d = getDb();
-  const schemaPath = join(__dirname, 'pib-db-schema.sql');
-
-  // Auto-init: ensure tables exist
-  try {
-    d.prepare('SELECT 1 FROM projects LIMIT 0').run();
-  } catch {
-    lib.init(d, { schemaPath });
-  }
 
   switch (name) {
     case 'pib_create_project':
@@ -239,6 +277,12 @@ function handleToolCall(name, args) {
       return lib.triage(d, args);
     case 'pib_triage_history':
       return lib.triageHistory(d);
+    case 'pib_defer_with_trigger':
+      return lib.deferWithTrigger(d, args);
+    case 'pib_list_triggered':
+      return lib.listTriggered(d, args);
+    case 'pib_mark_trigger_checked':
+      return lib.markTriggerChecked(d, args);
     case 'pib_query':
       return lib.query(d, args);
     default:

package/templates/scripts/pib-db-schema.sql

@@ -7,34 +7,36 @@
 -- Query:      node scripts/pib-db.mjs query "SELECT ..."
 
 CREATE TABLE IF NOT EXISTS projects (
-  fid           TEXT PRIMARY KEY CHECK(fid GLOB 'prj:*'),
-  name          TEXT NOT NULL,
-  area          TEXT,
-  status        TEXT NOT NULL DEFAULT 'active'
-                  CHECK(status IN ('active','paused','done','dropped','someday')),
-  notes         TEXT NOT NULL DEFAULT '',
-  created       TEXT NOT NULL CHECK(created GLOB '????-??-??'),
-  completed_at  TEXT,
-  due           TEXT,
-  deleted_at    TEXT
+  fid                TEXT PRIMARY KEY CHECK(fid GLOB 'prj:*'),
+  name               TEXT NOT NULL,
+  area               TEXT,
+  status             TEXT NOT NULL DEFAULT 'active'
+                       CHECK(status IN ('active','paused','done','dropped','someday')),
+  notes              TEXT NOT NULL DEFAULT '',
+  created            TEXT NOT NULL CHECK(created GLOB '????-??-??'),
+  completed_at       TEXT,
+  due                TEXT,
+  deleted_at         TEXT,
+  trigger_condition  TEXT
 );
 
 CREATE TABLE IF NOT EXISTS actions (
-  fid           TEXT PRIMARY KEY CHECK(fid GLOB 'act:*'),
-  text          TEXT NOT NULL,
-  area          TEXT,
-  project_fid   TEXT REFERENCES projects(fid) ON DELETE SET NULL,
-  due           TEXT,
-  flagged       INTEGER NOT NULL DEFAULT 0 CHECK(flagged IN (0, 1)),
-  completed     INTEGER NOT NULL DEFAULT 0 CHECK(completed IN (0, 1)),
-  completed_at  TEXT,
-  status        TEXT NOT NULL DEFAULT 'open'
-                  CHECK(status IN ('open','in-progress','blocked','deferred','done')),
-  tags          TEXT NOT NULL DEFAULT '',
-  sort_order    INTEGER NOT NULL DEFAULT 0,
-  created       TEXT NOT NULL CHECK(created GLOB '????-??-??'),
-  notes         TEXT NOT NULL DEFAULT '',
-  deleted_at    TEXT
+  fid                TEXT PRIMARY KEY CHECK(fid GLOB 'act:*'),
+  text               TEXT NOT NULL,
+  area               TEXT,
+  project_fid        TEXT REFERENCES projects(fid) ON DELETE SET NULL,
+  due                TEXT,
+  flagged            INTEGER NOT NULL DEFAULT 0 CHECK(flagged IN (0, 1)),
+  completed          INTEGER NOT NULL DEFAULT 0 CHECK(completed IN (0, 1)),
+  completed_at       TEXT,
+  status             TEXT NOT NULL DEFAULT 'open'
+                       CHECK(status IN ('open','in-progress','blocked','deferred','done')),
+  tags               TEXT NOT NULL DEFAULT '',
+  sort_order         INTEGER NOT NULL DEFAULT 0,
+  created            TEXT NOT NULL CHECK(created GLOB '????-??-??'),
+  notes              TEXT NOT NULL DEFAULT '',
+  deleted_at         TEXT,
+  trigger_condition  TEXT
 );
 
 CREATE TABLE IF NOT EXISTS audit_runs (
@@ -66,3 +68,16 @@ CREATE TABLE IF NOT EXISTS audit_findings (
   triaged_at          TEXT,
   fix_description     TEXT
 );
+
+-- Append-only history of trigger-condition evaluations.
+-- No foreign key to actions/projects: if the target row is later deleted,
+-- we want the historical record preserved (orphan rows are acceptable).
+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
+);
+CREATE INDEX IF NOT EXISTS idx_trigger_checks_fid ON trigger_checks(target_fid);