docs: make outstanding issues the universal task ledger

.claude/hooks/issues-surface.sh

@@ -43,6 +43,22 @@ rows="$(awk '
   }
 ' "$ledger" 2>/dev/null || true)"
 
+# --- parse the recommended execution queue ----------------------------------
+queue_rows="$(awk '
+  /^## Recommended execution queue/ { inqueue=1; next }
+  /^## /                            { if (inqueue) inqueue=0 }
+  inqueue && /^\|[[:space:]]*[0-9]+[[:space:]]*\|/ {
+    n=split($0, c, "|")
+    ord=c[2]; ids=c[3]; acuity=c[4]; capability=c[5]; timing=c[6]
+    gsub(/^[ \t]+|[ \t]+$/, "", ord)
+    gsub(/^[ \t]+|[ \t]+$/, "", ids)
+    gsub(/^[ \t]+|[ \t]+$/, "", acuity)
+    gsub(/^[ \t]+|[ \t]+$/, "", capability)
+    gsub(/^[ \t]+|[ \t]+$/, "", timing)
+    printf "%s\t%s\t%s\t%s\t%s\n", ord, ids, acuity, capability, timing
+  }
+' "$ledger" 2>/dev/null || true)"
+
 total="$(printf '%s' "$rows" | grep -c . || true)"
 if [ "${total:-0}" -eq 0 ]; then
   echo "[issues] Outstanding-work memory (docs/outstanding-issues.md): no open items. Record one with /issues add …"
@@ -56,6 +72,24 @@ c1="$(count "$p1")"; c2="$(count "$p2")"; c3="$(count "$p3")"
 
 echo "[issues] Outstanding-work memory — ${total} open (${c1}×P1, ${c2}×P2, ${c3}×P3). Source of truth: docs/outstanding-issues.md · read the full list back with /issues."
 
+queue_total="$(printf '%s' "$queue_rows" | grep -c . || true)"
+if [ "${queue_total:-0}" -gt 0 ]; then
+  echo "[issues] Recommended execution queue — ${queue_total} retained tasks (first 8):"
+  printf '%s\n' "$queue_rows" | head -n 8 | while IFS=$'\t' read -r ord ids acuity capability timing; do
+    echo "  ${ord}. ${ids} · ${acuity} · ${timing} · ${capability}"
+  done
+fi
+
+# Keep the priority summary complementary to the queue instead of repeating
+# the same recommended IDs in both sections.
+queued_ids=" $(printf '%s\n' "$queue_rows" | grep -oE '#[0-9]+' | tr '\n' ' ' || true)"
+unqueued_rows="$(printf '%s\n' "$rows" | awk -F'\t' -v queued="$queued_ids" '
+  index(queued, " " $2 " ") == 0
+' || true)"
+ungroup() { printf '%s\n' "$unqueued_rows" | awk -F'\t' -v p="$1" '$1==p'; }
+u1="$(ungroup P1)"; u2="$(ungroup P2)"; u3="$(ungroup P3)"
+uc1="$(count "$u1")"; uc2="$(count "$u2")"; uc3="$(count "$u3")"
+
 print_group() { # $1=rows  $2=max-to-list
   local data="$1" limit="$2" shown=0 more=0 pri id typ sum
   [ -z "$data" ] && return 0
@@ -75,9 +109,9 @@ EOF
 }
 
 # P1 = do-next, list all. P2 = should-do, list up to 8. P3 = collapse to a count.
-[ "$c1" -gt 0 ] && print_group "$p1" 999
-[ "$c2" -gt 0 ] && print_group "$p2" 8
-[ "$c3" -gt 0 ] && echo "  ${c3} × P3 (nice-to-have / revisit-when) — see /issues"
+[ "$uc1" -gt 0 ] && print_group "$u1" 999
+[ "$uc2" -gt 0 ] && print_group "$u2" 8
+[ "$uc3" -gt 0 ] && echo "  ${uc3} × P3 (nice-to-have / revisit-when) — see /issues"
 
 # --- capture reminder ---------------------------------------------------------
 case "$source_val" in

.claude/skills/issues/SKILL.md

@@ -5,9 +5,9 @@ description: Track and recall all outstanding tasks, recommendations, and issues
 
 # issues — the outstanding-work memory
 
-`docs/outstanding-issues.md` is the durable, cross-session memory of everything still outstanding:
-open **tasks**, **recommendations** not yet acted on, and **issues** not yet resolved. Chat context
-resets; that file does not. This skill reads it back and keeps it current.
+`docs/outstanding-issues.md` is the single universal, durable, cross-session ledger for recommended
+execution order, open **tasks**, **recommendations**, **issues**, provider/operator work, and archive
+history. Chat context resets; that file does not. This skill reads it back and keeps it current.
 
 **The ledger is the source of truth, not chat memory.** Never answer `/issues` from conversation
 recall — always read the file first, so the answer is correct even in a fresh session.
@@ -20,13 +20,15 @@ recall — always read the file first, so the answer is correct even in a fresh
 ## Default: `/issues` (read-only)
 
 1. Read `docs/outstanding-issues.md`.
-2. State the **open items** back, grouped by priority (P1 → P3), each as
+2. State the **Recommended execution queue** back in order, including acuity, timing, and gate.
+3. Summarize any open items not represented in that queue, grouped by priority (P1 → P3), each as
    `#ID · type · summary — next action (source)`.
-3. End with a one-line count, e.g. `5 open: 0×P1, 3×P2, 2×P3 · 0 resolved this session`.
-4. Do **not** mutate the file or commit on a plain read.
+4. End with a one-line open/recommended count.
+5. Do **not** mutate the file or commit on a plain read.
 
-If a filter is given, narrow step 2: `/issues P1` (by priority), `/issues issues` / `/issues recs`
-/ `/issues tasks` (by type), `/issues <keyword>` (summary/detail substring match).
+If a filter is given, filter the open items before rendering steps 2–3, then show only matching
+queued tasks and matching non-queued items: `/issues P1` (by priority), `/issues issues` /
+`/issues recs` / `/issues tasks` (by type), `/issues <keyword>` (summary/detail substring match).
 
 ## Mutating subcommands
 
@@ -53,6 +55,10 @@ paragraph; put the smallest next action in **Detail / next action**.
 ## Writing rules
 
 - Keep the table format and column order exactly as in `docs/outstanding-issues.md`. One row per item.
+- Add a retained task to the recommended queue with order, acuity, capability, timing, estimate,
+  gate, success criteria, verification, and stop rule. Reorder rather than duplicate related work.
+- Remove a task from the recommended queue when it completes or is no longer recommended; retain
+  its evidence in the open or resolved table as appropriate.
 - IDs are monotonic and never reused — always allocate from the `issues:next-id` marker and bump it.
 - Escape `|` inside cell text (write `\|`) so the markdown table stays intact.
 - Respect the repo's RAG/clinical/privacy flagging rules if an item _itself_ touches a protected

AGENTS.md

@@ -450,13 +450,18 @@ Run the matching planner command in `docs/productivity-workflows.md` without sid
 
 ## Outstanding-work memory (`/issues`)
 
-`docs/outstanding-issues.md` is the durable, cross-session memory of every outstanding **task**,
-**recommendation**, and **issue** for this repo. Chat context resets between sessions; that file does
-not, so anything worth remembering after a session ends belongs there.
+`docs/outstanding-issues.md` is the single universal, durable, cross-session ledger for every
+outstanding **task**, **recommendation**, and **issue** in this repo. It owns evidence, resolution
+history, recommended order, acuity, capability, timing, effort, approvals, verification, and stop
+rules. Chat context resets; this file does not, so anything worth remembering belongs there.
+Detailed runbooks such as `docs/operator-backlog.md` may support a task but must not become a second
+status ledger. Update the universal ledger when work completes, is dropped, becomes stale, or is
+materially re-scoped. Never restore completed, duplicate, speculative, superseded, or rejected work
+to the recommended queue.
 
 - When the user types `/issues`, invoke the `issues` skill (`.claude/skills/issues/SKILL.md`): read
-  `docs/outstanding-issues.md` and state the open items back, grouped by priority. A plain `/issues`
-  is read-only — it mutates and commits nothing.
+  `docs/outstanding-issues.md`, state the recommended queue in order, then summarize other open
+  items by priority. A plain `/issues` is read-only — it mutates and commits nothing.
 - `/issues add|done|update|capture …` mutate the ledger; each mutation commits **only**
   `docs/outstanding-issues.md` (no push unless the user asks or you are already handing off).
 - Proactively offer to `capture` unresolved follow-ups, deferrals, and known risks into the ledger

docs/README.md

@@ -45,7 +45,8 @@ npm run docs:check-links
 - [supabase-migration-reconciliation.md](supabase-migration-reconciliation.md) — migration drift and repair policy
 - [observability-slos.md](observability-slos.md) — health probes, SLO counters, degraded modes
 - [openai-rag-operations.md](openai-rag-operations.md) — OpenAI/RAG provider operations and modes
-- [operator-backlog.md](operator-backlog.md) — pending operator debt backlog
+- [outstanding-issues.md](outstanding-issues.md) — single universal task ledger and repository memory
+- [operator-backlog.md](operator-backlog.md) — provider/operator runbook detail (status is canonical in the universal ledger)
 - [deploy-corrector-public-titles.md](deploy-corrector-public-titles.md) — public-title corrector deploy notes
 
 ## Governance, safety, privacy

docs/branch-review-ledger.md

@@ -20,7 +20,8 @@ Use this ledger to prevent repeated branch and PR reviews when the reviewed HEAD
 
 | Date       | Branch or ref                                            | Reviewed HEAD                            | Scope                                                      | Outcome                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Checks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | ---------- | -------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 2026-07-24 | `codex/supabase-document-change-trigger` | `9c7d9edf509a51478f5bebbabcca64e3926dc877` + reviewed working diff | Document-change ingestion trigger migration, schema mirror, grants, privacy and fail-safe delivery | APPROVE. No P0-P2 finding. The trigger is update-only, acts solely on a strict JSON boolean false/absent-to-true transition, sends only the receiver's allowlisted owner-scoped fields, fails open for document writes when Vault/GUC/pg_net is unavailable, and revokes execution from public/anon/authenticated. No production URL fallback exists. Highest residual risk is deliberate pg_net at-most-once delivery; the clear-then-flip recovery and data-preserving rollback are documented, and the trigger remains inert until both the Vault secret and environment base-URL GUC are configured. | Disposable `supabase/postgres:17.6.1.127` schema replay and drift-manifest regeneration passed (16s; scratch container removed); focused schema/drift/receiver Vitest 89/89; migration-role, function-grant (30 SECURITY DEFINER functions) and owner-scope guards; production-readiness CI mode READY with expected secretless-worktree warnings; offline RAG 21 suites/307 tests; `verify:cheap` 365 files, 3,241 passed/1 skipped; static trace of receiver payload, authoritative owner-scoped reload and idempotent enqueue path. No live provider mutation or migration apply. |
+| 2026-07-24 | PR #1106 / `codex/task-ledger-final-11318f` | `5d128a2844c2298d0da36df64e5e2f7dda11e14b` + reviewed follow-up diff | Universal task-ledger workflow and protected-main merge readiness | APPROVE after follow-up. `docs/outstanding-issues.md` is the single durable task ledger, with retained work carrying order, acuity, timing, capability, effort, dependencies, success criteria, verification and stop rules. Four actionable review findings were fixed: filtered `/issues` reads now apply the filter to open items before rendering queued and non-queued results; the session hook excludes queued IDs from its priority summary; `#030` is consistently P2/A2 in the canonical open table and queue; and the sole A1/P1 blocker is first while `#052` is explicitly the first code task. No other actionable review thread remains in the reviewed scope. | Protected CI at the initial reviewed head passed policy, static, safety/config, unit coverage, Semgrep, Gitleaks, GitGuardian and the required aggregate; UI, build, migration replay and release browser matrix were correctly skipped for the docs/workflow scope. Follow-up proof: scoped Prettier; hook syntax/runtime plus exact ID-deduplication, P2-count and A1-first assertions; docs links (1,136 references); canonical skill catalog (32 skills, 8 aliases); `git diff --check`. Exact-head hosted CI remains required after the follow-up push. No OpenAI, Supabase, Railway, deployment or production-data operation ran. |
+| 2026-07-24 | `codex/supabase-document-change-trigger` | `9c7d9edf509a51478f5bebbabcca64e3926dc877` + reviewed working diff | Document-change ingestion trigger migration, schema mirror, grants, privacy and fail-safe delivery | APPROVE. No P0-P2 finding. The trigger is update-only, acts solely on a strict JSON boolean false/absent-to-true transition, sends only the receiver's allowlisted owner-scoped fields, fails open for document writes when Vault/GUC/pg_net is unavailable, and revokes execution from public/anon/authenticated. No production URL fallback exists. Highest residual risk is deliberate pg_net at-most-once delivery; the clear-then-flip recovery and data-preserving rollback are documented, and the trigger remains inert until both the Vault secret and environment base-URL GUC are configured. | Disposable Supabase Postgres `17.6.1.127` schema replay and drift-manifest regeneration passed (16s; scratch container removed); focused schema/drift/receiver Vitest 89/89; migration-role, function-grant (30 SECURITY DEFINER functions) and owner-scope guards; production-readiness CI mode READY with expected secretless-worktree warnings; offline RAG 21 suites/307 tests; `verify:cheap` 365 files, 3,241 passed/1 skipped; static trace of receiver payload, authoritative owner-scoped reload and idempotent enqueue path. No live provider mutation or migration apply. |
 | 2026-07-23 | PR #1090 / `cursor/fix-phone-dock-edge-1b1d` | `761de7e9ad623b6bd8d634d849a9eb465d622e48` (merged as `09028ef217209fceb53f1122ac7738b509bce323`) | Phone safe-area and edge-to-edge search-dock UI review | MERGED. No P0-P2 finding. The branch was three commits behind, so current `origin/main` was merged before landing; the actual merge tree matched the reviewed synthetic tree. The dock remains flush to the viewport with safe-area padding inside the form, and the phone shell no longer retains the `dvh` clamp that created the Safari toolbar band. Zero actionable review threads. | `npm run ensure`; focused `ui-tools.spec.ts` phone-home and edge-to-edge scenarios: Chromium 2/2 and WebKit 2/2; refreshed hosted policy, security, unit, build, advisory UI, Production UI and required aggregate checks green; exact-head ancestry and local-main tree equality proved after merge. |
 | 2026-07-22 | PR #1087 / `codex/reconcile-product-truth` | `edbc2260fef59ca2fa7c6973dffb85e32354bce1` (merged as `05dc52fd8408a65117e22a6236e43252203bea92`) | Product-truth copy, account persistence and unavailable-SSO presentation | MERGED. Cross-device claims now match favourites/preferences persistence; recent searches are identified as browser-session data; the contradictory “never shared” statement is removed. All unavailable setup providers and Apple elsewhere use the connected accessible “coming soon” placeholder pattern. The single review finding was fixed, replied to and resolved. | Red DOM proof; focused 19/19; `verify:cheap` 3,220 passed / 1 skipped; `verify:ui` 265/265; PR-local build/secret scan/offline RAG; final hosted required, Production UI, policy and security checks green. No provider calls or RAG spend. |
 | 2026-07-22 | PR #1086 / `codex/reconcile-xlsx-budgets` | `5376880a40749b6526fd7e4603a7be9d04bc9624` (merged as `2963fba46eacd644618a588fa283f7597faa2644`) | XLSX resource-boundary review | MERGED. Enforces worksheet, non-empty-row, rendered-cell and UTF-8 output ceilings before result fragments are appended; sparse-column output is preserved. No actionable review threads. | Red 257-sheet reproducer; focused 4/4; `verify:cheap` 3,218 passed / 1 skipped; PR-local build/scan/offline RAG; hosted required/security/policy green. |

docs/codebase-index.md

@@ -334,6 +334,7 @@ One shared composer (`master-search-header.tsx`) serves every mode. Placement:
 | Full documentation index | `docs/README.md`                                                 |
 | Routes and modes         | `docs/site-map.md`                                               |
 | Search/RAG roadmap       | `docs/search-rag-master-plan.md`                                 |
+| Universal task ledger    | `docs/outstanding-issues.md`                                     |
 | Reindex operations       | `docs/reindex-runbook.md`                                        |
 | Production readiness     | `docs/production-readiness-checklist.md`                         |
 | Capacity / scale-up      | `docs/capacity-review.md`, `docs/auth-connection-cap-runbook.md` |

docs/operator-backlog.md

@@ -1,8 +1,9 @@
-# Operator backlog
+# Operator action detail
 
-Single source of truth for **human-only / provider-gated actions** that cannot be done from a coding
-session (they touch Supabase, Railway, OpenAI, or GitHub settings, per the AGENTS.md provider boundary).
-This exists so that launch-blocking state lives in the repo instead of chat memory.
+Detailed runbook index for **human-only / provider-gated actions** that cannot be done from a coding
+session. Canonical task status, order, acuity, and completion live only in
+[`outstanding-issues.md`](outstanding-issues.md); this file supplies provider-specific steps and
+presence claims that must be verified before acting.
 
 **How to use:** work top to bottom; each row links to the detailed runbook. `Status` values are
 `⏳ pending`, `🔎 verify` (may already be done — confirm before repeating), `✅ done`, `—` (n/a).