# Work Tracking — [Your Project Name]

How this project tracks planned work. Skills that manage work items
(/plan, /execute, and the session loop) reference this file.

## Work Item Storage
*Where work items live.*
*Example: SQLite `tasks` table, or `backlog.md`, or GitHub Issues*

## Query Interface
*How to search open items.*
*Example: `sqlite3 project.db "SELECT * FROM tasks WHERE status != 'done'"`*
*Example: `gh issue list --state open --json number,title`*

## Mutation Interface
*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, the session
loop 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 — UNLESS the sentence names another action, in which case
it is a dependency (below), not a trigger.

**Dependency** is for work blocked by another *action* you are already
tracking. State it with `pib_add_dependency` (blocker first, waiter
second) rather than writing it into a title, notes, or a trigger — a
stated edge is read by `pib_next_actions`, prose is read by nobody, and
the write boundary refuses an `act:` fid inside a trigger condition for
that reason. Edges may cross project boundaries, which is what lets a
group of items waiting on one shared gate become a query instead of a
folder.

**`pib_next_actions` is the payoff**: open actions with no unfinished
blocker and no unfired trigger, recomputed on every call. Prefer it over
`pib_list_actions` when choosing what to work on — `pib_list_actions`
returns everything open, including work that cannot be started yet. Its
complement, `pib_list_blocked`, answers "what is waiting, and on what."

Nothing needs undoing when a blocker finishes: blocked-ness is derived on
every read, so completing a blocker releases its dependents immediately,
and reopening one re-blocks them. The edge itself stays as the durable
record of why the wait existed.