diff --git a/AGENTS.md b/AGENTS.md index 32d9bc6c06..16b09555f4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -450,17 +450,19 @@ 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 this repository's single universal task ledger. Its active table keeps +only evidence-supported work still worth doing and records order, acuity, classification, executor +capability, timing, effort, dependencies, approvals, success criteria, verification and stopping +conditions. Completed, stale, duplicate, superseded, speculative and no-longer-recommended claims may +remain only in its archive/history, never as active work. Do not create a second task ledger. - 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` + `docs/outstanding-issues.md` and state the open items back in recommended order. 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. +- `/issues add|done|update|capture …` mutate the ledger only when requested. Committing, pushing or + opening a PR remains a separate Git workflow requiring the usual authorization. +- Before capture, verify and deduplicate each candidate. Add only work that remains recommended; + archive or omit completed, stale, duplicate, superseded, speculative or uneconomic suggestions. - 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 diff --git a/docs/README.md b/docs/README.md index 0b743e80cb..391038b6be 100644 --- a/docs/README.md +++ b/docs/README.md @@ -71,7 +71,8 @@ npm run docs:check-links ## Plans and workstreams (living) -- [maturity-backlog-workorders.md](maturity-backlog-workorders.md) — actionable work orders tracking the repository-maturity audit backlog +- [outstanding-issues.md](outstanding-issues.md) — the single universal task ledger; its active table contains only recommended work in execution order +- [maturity-backlog-workorders.md](maturity-backlog-workorders.md) — historical maturity work-order evidence; not an independent active queue - [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 - [rag-hybrid-findings-and-todo.md](rag-hybrid-findings-and-todo.md) — hybrid retrieval findings backlog diff --git a/docs/maturity-backlog-workorders.md b/docs/maturity-backlog-workorders.md index 2c3a945c9d..b57e6245d4 100644 --- a/docs/maturity-backlog-workorders.md +++ b/docs/maturity-backlog-workorders.md @@ -1,11 +1,11 @@ -# Maturity backlog — work orders +# Maturity audit work-order history -Living tracker that turns the deferred backlog from +Supporting history for work orders derived from [`docs/audit/2026-07-20-repository-maturity.md`](audit/2026-07-20-repository-maturity.md) §10 -into actionable, sequenced work orders. Each item states its **outcome**, **approach**, **key -files**, **risk**, **verification**, and **status**. High-risk items are deliberately kept as -their own work order — the audit's rule is one dedicated PR + full-suite verification per -structural change, not a single mixed PR. +with their **outcome**, **approach**, **key files**, **risk**, **verification**, and **status**. +This is not an independent active backlog. A maturity item is current work only when promoted to the +active table in [`outstanding-issues.md`](outstanding-issues.md), the repository's single universal +task ledger. Historical `READY`, `OPEN` or `PROVIDER-GATED` labels below do not override that ledger. **Status legend:** `DONE` (landed) · `IN PROGRESS` (partially landed; more PRs remain) · `READY` (scoped, safe to start) · `OPEN` (needs a decision or a dedicated PR) · diff --git a/docs/operator-backlog.md b/docs/operator-backlog.md index eb749675b1..ee4f12f255 100644 --- a/docs/operator-backlog.md +++ b/docs/operator-backlog.md @@ -1,10 +1,12 @@ -# Operator backlog +# Operator runbook index -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. +This file preserves provider-action detail and runbook links. It is **not** an independent task queue: +[`outstanding-issues.md`](outstanding-issues.md) is the repository's single universal ledger, and an +operator row is executable only while a corresponding active row exists there. Status here is +supporting evidence that must be reconciled with that ledger and verified live before action. -**How to use:** work top to bottom; each row links to the detailed runbook. `Status` values are +**How to use:** follow the active ledger order, then use the matching row here for provider detail. +`Status` values are `⏳ pending`, `🔎 verify` (may already be done — confirm before repeating), `✅ done`, `—` (n/a). Update the row (and its runbook) when an action lands. The sequenced flow with exact commands and approval gates is [launch-operator-runbook.md](launch-operator-runbook.md); this table is the index. @@ -12,8 +14,9 @@ Code + ops remediation waves from the 2026-07-14 multi-skill audit live in [audit-remediation-plan-2026-07-14.md](audit-remediation-plan-2026-07-14.md). Findings inventory for handover: [audit-handover-2026-07-14.md](audit-handover-2026-07-14.md). -> Status column is seeded from repo runbooks + session memory and **must be confirmed against live -> state** before acting — do not treat a `🔎 verify` row as authoritative. +> Status is historical/runbook evidence and **must be confirmed against live state** before acting. +> A pending row that is absent from the active universal ledger is not authorization or recommended +> work. ## Launch-gating actions @@ -23,7 +26,7 @@ Findings inventory for handover: [audit-handover-2026-07-14.md](audit-handover-2 | Apply drift-codify forward migration (step 1h) | ✅ done | — | Applied and drift/readiness verified 2026-07-13; verify only unless new reviewed drift is found | [database-drift-detection.md](database-drift-detection.md) | | Apply repo-ahead migrations to live (post-2026-07-13) | ✅ done | — | Zero unsafe title-word rows; `npm run check:drift`; then `eval:retrieval:quality` (36/36) for the corrector | [deploy-corrector-public-titles.md](deploy-corrector-public-titles.md) · [operator-apply-performance-latency-remediation.md](operator-apply-performance-latency-remediation.md) | | Full release gate (bounded OpenAI spend) | ⏳ pending | migrations 1 applied | `npm run verify:release`; `npm run eval:quality -- --rag-only` | [launch-operator-runbook.md §2](launch-operator-runbook.md) | -| Provision staging Supabase project (`Clinical KB Staging`, ap-southeast-2) | ⏳ pending | — | `npm run check:indexing` after `db push` | [staging-setup.md](staging-setup.md) | +| Provision staging Supabase project (`Clinical KB Staging`, ap-southeast-2) | ✅ done | — | Archived run `29795051547` proves the dedicated staging tenancy harness and cleanup; do not reprovision | [staging-setup.md](staging-setup.md) · [archived evidence](archive/staging-tenancy-evidence-29795051547/staging-tenancy-evidence.json) | | Staging soak + rollback rehearsal on Railway | ⏳ pending | staging provisioned | `scripts/soak-test.ts --confirm-staging` (answer p95 ≤ 25 s) | [launch-operator-runbook.md §4](launch-operator-runbook.md) · [capacity-review.md](capacity-review.md) | | Production deploy to Railway | ✅ done | — | App deployment recorded live 2026-07-14; re-verify with `GET /api/health` and deployment readiness | [deployment-architecture.md](deployment-architecture.md) |