pending-questions

pending-questions

One CLI over the owner's pending questions, and the one store behind them: the "Pending questions" database in the owner's room. Each question is a row carrying its Host; a host reads and writes only its own rows, and the owner sets a row's Status himself (code never writes it — its own marks live in the Recovery and Closed cells).

The room is PENDING_QUESTIONS_ROOM: env, then this manifest's config, then the host's <workspace>/state/pending-questions-room; unset, the owner's DM. Point every host of the owner at one room shared by him and all his Sutandos. The collab service is the room capability's own, unless PENDING_QUESTIONS_COLLAB_URL names one (env, then this manifest's config, per skills/MANIFEST.md); the adapter's room_store(..., collab_url=) is the CLI tier above both.

python3 skills/pending-questions/scripts/pq.py ask "<question>" [--context "<why / options>"] \
    [--task-file <workspace>/tasks/<task>.txt] [--urgency live|durable] \
    [--default-action "<what Approve does>" --reason "<why>"] [--option "Hold=wait"] \
    [--priority High|Medium|Low]
python3 skills/pending-questions/scripts/pq.py list [--json]
python3 skills/pending-questions/scripts/pq.py reconcile
python3 skills/pending-questions/scripts/pq.py resolve <ask-id> [--answered]
python3 skills/pending-questions/scripts/pq.py remind [--force]

Trigger: any time you would write a question for the owner into terminal or summary text, file it instead with ask (or scripts/ask-owner.py; add --unless-open to file nothing when an open row already has that question — it reports already open: [<id>]). The terminal and a compaction summary reach no one. This skill's hooks/compact-carry.py keeps owner questions out of compaction summaries and, after one, has the core file any never-asked question it carried; session-state.md shows only the count (python3 src/pending_questions_reader.py summary).

• ask queues the question to the owner (the task's conversation only for an owner-tier task in his DM; otherwise his DM), saves it to the outbox, writes the row born with its **Sent:** record, and once that exact row is confirmed complete commits the store-history marker and THEN deletes the outbox file — a marker that cannot be written keeps the file (history: FAILED in the report) so the local evidence outlives the failure. Only after that confirmation does it reconcile the older backlog. Room subprocess calls share one operation budget (90 seconds by default), so failures cannot renew the timeout for each older question; the held entries remain for a later explicit reconcile. The shared reconcile pass applies that budget to every caller, including pq reconcile and reminders. Resolving an answer shares it across reconciliation and the row close. If the outbox cannot hold the question, NO row is written: the owner is still asked, and the report says nothing holds it. Read the output: a FAILED line is not an ask. Then continue; never block.
• list is READ-ONLY — it writes no file, not even the history marker — and lists each ask id in exactly one bucket, by precedence: a terminal or locally closed row is done; a complete open row waits; an open row whose body has not landed is stood in for by its held entry; a held entry with no row waits, marked (not yet in the room), or is done when closed locally; a local close naming neither is closed locally; its row is not in view yet (neither open nor done, pending_close in count). When the room cannot be read it prints pending questions: UNKNOWN — room unreachable (…) and only what is held locally; it never prints a zero it did not measure. Once a row of this workspace was ever confirmed (written, replayed, ingested or observed by a reconcile), a room that cannot be reached is an outage, not an empty outbox — whatever became of the one-time introduction message.
• reconcile is the explicit pass: outbox replay, local close records, stale marks, the transitional legacy ingest, and the history backfill for rows that predate the marker. Legacy ingest refuses an archive boundary hidden by damaged Markdown before creating rows or marking source entries moved; it reports the affected line numbers. Every step commits the history marker before it releases local evidence (an outbox entry, a close record, a legacy file entry), and keeps that evidence when the commit fails. ask and remind run it; list does not.
• resolve closes a row as Resolved (or Answered with --answered). It never reopens a closed row. When the room cannot be written, the closure is recorded locally (<outbox>/closed/<ask_id>.json) and applied by the next reconcile — but only for a question the outbox holds, or in outage mode (a row was confirmed here before); an unknown id with neither is refused and changes no count. The replay retires a local close only once its row is closed (or seen closed) AND complete — its body landed; a row the store view does not show is ambiguous and an incomplete one is still being filed, so in both cases the record stays and reconcile reports it.
• remind is the only way a reminder is sent (src/check-pending-questions.py --notify with this skill's adapter). Nothing is scheduled, and no pass surfaces questions: the owner is asked once, as questions come up, and reminded when he asks.