Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions AGENTS.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -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`
Comment on lines 459 to +460

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Align the issues reader with recommended ordering

When /issues is invoked, .claude/skills/issues/SKILL.md still requires grouping rows by priority rather than preserving the new recommended execution order; the existing ledger also retains its old columns and does not record executor capability, timing, effort, dependencies, approvals, success criteria, verification, or stopping conditions. Consequently the reader cannot satisfy the contract introduced here. Update the ledger schema and reader together before advertising this behavior.

AGENTS.md reference: AGENTS.md:L453-L460

Useful? React with 👍 / 👎.

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.
Comment on lines +462 to +463

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Remove the issues skill's unconditional commit

When a user requests /issues add, done, update, or capture without separately authorizing a Git handoff, .claude/skills/issues/SKILL.md still instructs the agent to stage and commit docs/outstanding-issues.md after every mutation, and the ledger's own usage text repeats that behavior. This directly contradicts the new separate-authorization rule and can create an unexpected commit; update those instructions in the same change.

AGENTS.md reference: AGENTS.md:L462-L463

Useful? React with 👍 / 👎.

- 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
Expand Down
3 changes: 2 additions & 1 deletion docs/README.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand Down
12 changes: 6 additions & 6 deletions docs/maturity-backlog-workorders.md
Original file line numberDiff line numberDiff line change
@@ -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) ·
Expand Down
19 changes: 11 additions & 8 deletions docs/operator-backlog.md
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,22 @@
# 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.
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.
Comment on lines +17 to +19

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Migrate operator work before gating the index

When the operator-closeout workflow runs, scripts/productivity-core.mjs:369 still scans docs/operator-backlog.md directly and returns 17 candidates, while the active universal ledger lacks corresponding rows for the full release gate, staging soak, production seed, SLO alerts, and most credential/DR tasks. These lines now declare absent rows unauthorized or unrecommended, so /issues can silently omit work that the operator workflow still proposes. Migrate and deduplicate the pending rows, then make the planner consume the universal ledger before enforcing this gate.

AGENTS.md reference: AGENTS.md:L453-L457

Useful? React with 👍 / 👎.


## Launch-gating actions

Expand All@@ -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) |

Expand Down
Loading