docs: activate universal repository task ledger

.claude/hooks/issues-surface.sh

@@ -1,11 +1,10 @@
 #!/usr/bin/env bash
 # SessionStart hook — surface the outstanding-work memory into context.
 #
-# Reads docs/outstanding-issues.md (the /issues ledger) and prints a compact,
-# glanceable summary of the OPEN items so every session starts already aware of
-# what is outstanding. When the trigger is a context reset (compact / resume /
-# clear) it also emits a reminder to run `/issues capture` — that is the moment
-# a session's in-flight follow-ups are most likely to be lost.
+# Reads docs/outstanding-issues.md (the universal /issues ledger) and prints the
+# ordered recommended tasks plus open-item counts so every session starts with
+# the same repository-wide priorities. When the trigger is a context reset
+# (compact / resume / clear) it also emits a reminder to run `/issues capture`.
 #
 # Contract: READ-ONLY. Never writes, never commits, never fails a session — it
 # always exits 0, and every step is guarded so a parse error just yields less
@@ -43,25 +42,29 @@ 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:]]*\|/ {
+# --- parse the ordered recommended execution queue --------------------------
+# Emit "ORDER<TAB>ID<TAB>SUMMARY<TAB>ACUITY<TAB>WHEN<TAB>ESTIMATE" per recommended row.
+recommended="$(awk '
+  /^## Recommended execution queue/ { inrecommended=1; next }
+  /^## /                             { if (inrecommended) inrecommended=0 }
+  inrecommended && /^\|[[: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)
+    order=c[2]; id=c[3]; summary=c[4]; acuity=c[5]; timing=c[6]; estimate=c[7]
+    gsub(/^[ \t]+|[ \t]+$/, "", order)
+    gsub(/^[ \t]+|[ \t]+$/, "", id)
+    gsub(/^[ \t]+|[ \t]+$/, "", summary)
     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
+    gsub(/^[ \t]+|[ \t]+$/, "", estimate)
+    if (length(summary) > 100) summary=substr(summary, 1, 97) "..."
+    printf "%s\t%s\t%s\t%s\t%s\t%s\n", order, id, summary, acuity, timing, estimate
   }
 ' "$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 …"
+recommended_total="$(printf '%s' "$recommended" | grep -c . || true)"
+if [ "${total:-0}" -eq 0 ] && [ "${recommended_total:-0}" -eq 0 ]; then
+  echo "[issues] Universal task ledger (docs/outstanding-issues.md): no recommended or open items. Record one with /issues add …"
   exit 0
 fi
 
@@ -70,25 +73,25 @@ count() { printf '%s' "$1" | grep -c . || true; }
 p1="$(group P1)"; p2="$(group P2)"; p3="$(group P3)"
 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
+echo "[issues] Universal task ledger — ${recommended_total} recommended · ${total} open (${c1}×P1, ${c2}×P2, ${c3}×P3). Source of truth: docs/outstanding-issues.md · read the full ledger with /issues."
 
-# 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_recommended() { # $1=max-to-list
+  local limit="$1" shown=0 more=0 order id summary acuity timing estimate
+  [ -z "$recommended" ] && return 0
+  while IFS=$'\t' read -r order id summary acuity timing estimate; do
+    [ -z "$order" ] && continue
+    if [ "$shown" -lt "$limit" ]; then
+      echo "  ${order} ${id} ${acuity} — ${summary} (${timing}; ${estimate})"
+      shown=$((shown + 1))
+    else
+      more=$((more + 1))
+    fi
+  done <<EOF
+$recommended
+EOF
+  [ "$more" -gt 0 ] && echo "  … +${more} more recommended tasks in ledger order (see /issues)"
+  return 0
+}
 
 print_group() { # $1=rows  $2=max-to-list
   local data="$1" limit="$2" shown=0 more=0 pri id typ sum
@@ -108,10 +111,15 @@ EOF
   return 0
 }
 
-# P1 = do-next, list all. P2 = should-do, list up to 8. P3 = collapse to a count.
-[ "$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"
+# Prefer the universal recommended order. Fall back to priority groups for an
+# older ledger that does not yet have the recommended execution section.
+if [ "${recommended_total:-0}" -gt 0 ]; then
+  print_recommended 10
+else
+  [ "$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"
+fi
 
 # --- capture reminder ---------------------------------------------------------
 case "$source_val" in

.claude/skills/issues/SKILL.md

@@ -3,14 +3,16 @@ name: issues
 description: Track and recall all outstanding tasks, recommendations, and issues for this repo as durable cross-session memory. Use when the user types "/issues" (state the open items back), or asks to add/close/update/capture an outstanding task, recommendation, or issue. The memory lives in docs/outstanding-issues.md; a plain "/issues" is read-only.
 ---
 
-# issues — the outstanding-work memory
+# issues — the universal repository task ledger
 
 `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.
+recall — always read the file first, so the answer is correct even in a fresh session. The ordered
+**Recommended execution queue** is the active task view; the wider open table preserves issues,
+conditional ideas, and audit history that are not necessarily recommended now.
 
 ## Trigger
 
@@ -20,11 +22,11 @@ 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 **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)`.
-4. End with a one-line open/recommended count.
-5. Do **not** mutate the file or commit on a plain read.
+2. State the **Recommended execution queue** back in its recorded order, including ID, acuity,
+   intelligence, timing, estimate, and completion signal.
+3. End with recommended/open counts and the open priority split, e.g.
+   `4 recommended · 7 open: 1×P1, 4×P2, 2×P3`.
+4. Do **not** mutate the file or commit on a plain read.
 
 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` /
@@ -37,9 +39,12 @@ Parse the intent from natural language too — the exact syntax is a convenience
 - **`/issues add <text>`** — append a row to **Open items**. Infer `Pri`/`Type` from the text
   (ask only if genuinely ambiguous; default `P2`/`task`). Allocate the ID from the
   `<!-- issues:next-id=NNN -->` marker, then bump that marker. Fill `Source` with
-  `session <today>` unless the user names one; `Added` is today's date.
+  `session <today>` unless the user names one; `Added` is today's date. If the work is currently
+  recommended, also add it to the ordered execution ledger with acuity, intelligence, timing,
+  estimate, dependency, and completion signal; otherwise retain it only in Open items.
 - **`/issues done <id> [outcome]`** — move that row from **Open items** to **Resolved / archive**
-  with today's date and a one-line outcome. Archive, never delete.
+  with today's date and a one-line outcome, remove it from the recommended execution queue, and
+  close the order gap. Archive, never delete.
 - **`/issues update <id> <text>`** — edit an open row's summary or next action in place.
 - **`/issues capture`** — scan the current session for recommendations, follow-ups, deferrals, and
   unfixed problems that surfaced but were not recorded. Propose them as a numbered list and add the
@@ -60,6 +65,9 @@ paragraph; put the smallest next action in **Detail / next action**.
 - 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.
+- Keep the recommended execution queue dependency-ordered, gap-free, deduplicated, and synchronized
+  with its referenced open rows. Never add refuted, parked, superseded, resolved, or decision-only
+  records to the active recommendation view.
 - 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
   surface — recording it here is fine, but acting on it later still needs the usual gate.

AGENTS.md

@@ -448,28 +448,29 @@ Run the matching planner command in `docs/productivity-workflows.md` without sid
 
 <!-- END:repo-productivity-skills -->
 
-## Outstanding-work memory (`/issues`)
+## Universal repository task ledger (`/issues`)
 
 `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.
-
+outstanding **task**, **recommendation**, and **issue** in this repo. It owns the recommended
+execution order, acuity, required capability, timing, effort, approvals, evidence, status, success
+criteria, stop rules, and resolution history. Chat context resets between sessions; that file does
+not, so anything worth remembering after a session ends belongs there. Do not create or maintain a
+second task ledger.
+
+- Before starting or recommending repository work, read the ordered **Recommended execution
+  queue** and the referenced open item. Only rows in that ordered view are active recommendations;
+  refuted, parked, superseded, resolved, and decision-only records remain audit history, not tasks.
 - When the user types `/issues`, invoke the `issues` skill (`.claude/skills/issues/SKILL.md`): read
-  `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.
+  `docs/outstanding-issues.md` and state the recommended execution queue in order, then summarize
+  the wider open-item counts. 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
   before a session's context is lost — that is what keeps it a memory rather than a stale list.
 - A `SessionStart` hook (`.claude/hooks/issues-surface.sh`, wired in `.claude/settings.json`)
-  auto-surfaces the open items into context at the start of every session and, on a context reset
-  (`compact`/`resume`/`clear`), nudges a `/issues capture`. It is read-only — it never writes the
-  ledger. `/issues` is still the way to read the full list or mutate it.
+  auto-surfaces the ordered recommended tasks plus open-item counts at the start of every session
+  and, on a context reset (`compact`/`resume`/`clear`), nudges a `/issues capture`. It is read-only —
+  it never writes the ledger. `/issues` is still the way to read the full list or mutate it.
 
 ## Codex GitHub review behavior
 

docs/README.md

@@ -72,6 +72,7 @@ npm run docs:check-links
 
 ## Plans and workstreams (living)
 
+- [outstanding-issues.md](outstanding-issues.md) — universal task ledger, recommended execution order, evidence, status, and resolution history
 - [maturity-backlog-workorders.md](maturity-backlog-workorders.md) — actionable work orders tracking the repository-maturity audit backlog
 - [framework-dependency-modernization-checklist.md](framework-dependency-modernization-checklist.md) — ordered Next.js 16, runtime, dependency, Turbopack, and verification migration program
 - [search-rag-master-plan.md](search-rag-master-plan.md) / [search-rag-master-context.md](search-rag-master-context.md) — search/RAG roadmap and shared context