workflow: add risk-scoped productivity toolkit

.agents/skills/clinical-change-proof/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: clinical-change-proof
+description: Build evidence for Database changes affecting clinical output, ingestion, retrieval, ranking, answers, citations, source rendering, privacy, owner scoping, document access, Supabase, or production behavior. Use for implementation, review, readiness, or handoff work that must satisfy clinical governance and conservative failure requirements.
+---
+
+# Clinical Change Proof
+
+1. Generate the scoped evidence plan:
+   `npm run workflow:clinical-proof -- --write-evidence`
+2. Read only the relevant sections of `.github/pull_request_template.md`, `docs/clinical-governance.md`, and the domain runbook selected by the change.
+3. Trace the full behavior boundary: input, authorization/owner scope, retrieval or write path, output contract, source evidence, logs, and failure fallback.
+4. Prove locally that:
+   - private or service-role data remains server-only and fail-closed;
+   - source-backed claims and conservative unknown/outdated behavior are preserved;
+   - demo data remains distinct from clinical sources;
+   - rollback or feature-disable behavior is documented;
+   - affected behavior has focused regression coverage.
+5. Run the local checks in the plan, narrowest first. The offline RAG contract is mandatory when retrieval or answer behavior is involved.
+6. Treat every command in the plan's `approvalRequired` list as an independent confirmation-required action, including retrieval, deployment, release, remote Git, hosted CI, Supabase, OpenAI, and production-readiness commands. Never bundle approvals, infer approval from another action, or execute one indirectly through a local gate or wrapper.
+7. Complete the Clinical Governance Preflight and report evidence, gaps, rollback, and any SaMD implication.

.agents/skills/clinical-change-proof/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Clinical Change Proof"
+  short_description: "Build clinical governance evidence"
+  default_prompt: "Use $clinical-change-proof to assess this clinical change and produce the required local evidence, governance checks, and provider approval gates."

.agents/skills/database-flightplan/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: database-flightplan
+description: Plan safe, risk-scoped work in the Database repository by inspecting the current diff, selecting the smallest local verification ladder, and separating provider-backed checks into explicit approval gates. Use before non-trivial source, config, test, UI, database, retrieval, clinical, dependency, CI, or deployment changes, or when the user asks what checks a change needs.
+---
+
+# Database Flightplan
+
+1. Run the repository task-start preflight if it has not run for the current task. Inspect branch and full Git status; preserve unrelated work.
+2. Generate the plan:
+   `npm run workflow:flightplan -- --write-evidence`
+   Use `--files pathA,pathB` when planning proposed paths before editing.
+3. Confirm the risk classes match the actual behavior, not only filenames. Add a focused check when the change crosses an unclassified boundary.
+4. Execute the narrowest relevant check first. Use `--run` only when running the full printed local/offline sequence is proportionate.
+5. Never execute anything listed under `approvalRequired` without explicit user confirmation. Treat indirect provider calls the same way.
+6. After fixes, run `npm run verify:pr-local` when the change is ready for handoff. Add UI or domain gates only when the plan selects them.
+7. Report changed files, checks and results, checks not run, approval gates, branch state, and residual risk.
+
+Keep the planner authoritative for deterministic selection. Do not reproduce its path tables in the skill.

.agents/skills/database-flightplan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Database Flightplan"
+  short_description: "Plan safe repo changes and verification"
+  default_prompt: "Use $database-flightplan to inspect the current Database repo change and produce a risk-scoped local verification and approval plan."

.agents/skills/live-design-sweep/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: live-design-sweep
+description: Inspect and improve the running Database application across routes, responsive breakpoints, keyboard interaction, accessibility modes, and shared UI surfaces. Use for design reviews, UI polish, browser QA, screenshots, mobile checks, accessibility work, or requests to find and fix visual or interaction defects across the app.
+---
+
+# Live Design Sweep
+
+1. Run `npm run workflow:design-sweep` to print the proof contract.
+2. Run `npm run ensure` before opening the app. Use only the identity-verified URL it prints.
+3. Derive route coverage from `docs/site-map.md` and changed navigation. Inspect representative content-rich, empty, loading, error, dialog, and long-scroll states.
+4. Cover 320, 390, 639, 768, 1440, and 1920 px where applicable. Check horizontal overflow, single-scrollport ownership, sticky/fixed collisions, tap targets, wrapping, and safe-area behavior.
+5. Check keyboard order, visible focus, dialog focus trapping and restoration, accessible names, contrast, reduced motion, forced colors, zoom, and screen-reader semantics.
+6. Record reproducible defects with route, viewport, trigger, expected behavior, and screenshot or test evidence. Fix shared primitives before duplicating route-specific patches.
+7. Add the smallest regression proof, then run focused Playwright, accessibility, `verify:ui`, and `verify:cheap` in that order as warranted.
+8. Write durable route/breakpoint coverage to the task report or `docs/archive/design-qa.md` when the pass is broad.
+
+Do not claim external design fidelity unless a target design or screenshot was supplied.

.agents/skills/live-design-sweep/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Live Design Sweep"
+  short_description: "Inspect and polish every live route"
+  default_prompt: "Use $live-design-sweep to inspect the running Database app across routes and breakpoints, fix confirmed UI issues, and verify accessibility."

.agents/skills/operator-closeout/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: operator-closeout
+description: Convert pending Database operator, deployment, migration, secret, live-service, and governance debt into a current, deduplicated, dependency-ordered, approval-gated execution batch with pre-state, post-state, rollback, and evidence requirements. Use when closing operator backlog items, preparing launch actions, or reconciling confirmation-required follow-ups.
+---
+
+# Operator Closeout
+
+1. Inventory candidates with:
+   `npm run workflow:operator-closeout -- --write-evidence`
+2. Treat the output as discovery, not truth. Verify each candidate against its linked runbook and current local state; remove completed, superseded, duplicate, or stale items.
+3. Group remaining actions by provider and blast radius. Order prerequisites, read-only probes, reversible writes, irreversible writes, and post-verification.
+4. For every action record:
+   - exact target and environment;
+   - external effect and credentials required;
+   - pre-state query or evidence;
+   - exact command or dashboard action;
+   - success condition and post-state proof;
+   - rollback or recovery path;
+   - expected cost or downtime.
+5. Ask for explicit approval for the concrete batch. Approval for one provider or command does not authorize another.
+6. Execute approved actions one at a time, stop on unexpected state, and update durable operator documentation only with observed evidence.
+
+The planner is intentionally plan-only. Never add automatic provider execution to it.

.agents/skills/operator-closeout/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Operator Closeout"
+  short_description: "Turn operator debt into safe batches"
+  default_prompt: "Use $operator-closeout to inventory pending operator actions, deduplicate them, and prepare a safe approval-gated execution batch."

.agents/skills/rag-change-lab/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: rag-change-lab
+description: Validate Database retrieval, ranking, chunking, query classification, source selection, citations, answer synthesis, grounding, and RAG privacy changes with focused tests and provider-free golden evaluation before requesting live evaluation approval. Use for RAG implementation, refactoring, debugging, regression analysis, or merge-readiness work.
+---
+
+# RAG Change Lab
+
+1. Generate the lab plan:
+   `npm run workflow:rag-lab -- --write-evidence`
+2. Read `docs/retrieval-quality-runbook.md` and only the change-relevant RAG architecture or threat-model sections.
+3. Define the invariant before editing: retrieval recall/ranking, owner scope, grounding, citation correctness, unsupported-query behavior, latency, cache invalidation, or prompt-injection resistance.
+4. Run the closest unit/property tests first, followed by `npm run eval:rag:offline`. Inspect cases and metrics rather than relying only on exit status.
+5. Make minimal changes and compare against the accepted baseline. Treat recall, MRR, grounded support, citation failure, numeric grounding, source governance, and strategy mix as separate signals.
+6. Run `verify:cheap` after focused proof. Use `verify:pr-local` for handoff.
+7. Stop before `eval:retrieval:quality`, `eval:rag`, `eval:quality`, or any live corpus/provider operation. Present the exact command, expected cost/effect, required environment, baseline, and success threshold for explicit approval.
+8. Report whether remaining uncertainty is code, corpus, owner configuration, live-provider variance, or environment.

.agents/skills/rag-change-lab/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RAG Change Lab"
+  short_description: "Validate retrieval and answer changes"
+  default_prompt: "Use $rag-change-lab to select and run the safe offline checks for this RAG change and prepare any live evaluation approval request."

.agents/skills/session-lifecycle/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: session-lifecycle
+description: Manage Database repository work safely from task start through verification, handoff, merge proof, and conservative worktree or branch cleanup. Use when starting a task, checking session state, preparing completed work for handoff, confirming a squash merge landed, or cleaning up only proven-redundant task state.
+---
+
+# Session Lifecycle
+
+1. Select the phase and generate its plan:
+   `npm run workflow:lifecycle -- --phase <status|start|handoff|landed|cleanup>`
+2. At task start, run the mandatory task-start preflight command configured by the active host or root `AGENTS.md`, then read applicable repo instructions and preserve all existing work. On this Windows Codex installation, resolve the installation-managed script from the user profile (for example, `& (Join-Path $env:USERPROFILE '.codex\scripts\start-codex-task.ps1') -TaskSlug <slug>`); it is intentionally not repo-local. Do not use the shared stash across worktrees.
+3. During work, recheck branch and status before edits and before handoff. Use `database-flightplan` for non-trivial change verification.
+4. At handoff, stage explicit coherent paths only, verify locally, and inspect the staged diff. Commit, push, PR creation, hosted CI, and merge remain authorization-bound.
+5. After a squash merge, verify the reviewed content against fetched `origin/main`; do not rely on ancestry alone. Check for late orphaned commits before cleanup.
+6. Remove a worktree or branch only after exact path/ref resolution, clean-state proof, and content-equivalence evidence. Preserve dirty, active, ambiguous, open-PR, or patch-unique work.
+7. Record the outcome in `docs/branch-review-ledger.md` when the repo review protocol requires it.
+
+The older `.claude/skills/newtask`, `handoff`, and `prlanded` remain compatibility surfaces. Use this skill as the agent-neutral orchestration contract.

.agents/skills/session-lifecycle/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Session Lifecycle"
+  short_description: "Manage safe task start through cleanup"
+  default_prompt: "Use $session-lifecycle to inspect and advance this Database task through start, verification, handoff, merge proof, or safe cleanup."

.agents/skills/verify-triage-fix/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: verify-triage-fix
+description: Diagnose and fix local Database repository verification failures using the smallest reproducible target, failure classification, known-flake evidence, and narrow reruns before broader gates. Use when lint, typecheck, Vitest, Playwright, build, offline RAG, workflow tooling, or another local check fails or appears hung.
+---
+
+# Verify Triage Fix
+
+1. Capture the exact failed command, exit code, complete actionable error, and relevant artifact path. Do not combine more checks until the failure is understood.
+2. Classify a saved log with:
+   `npm run workflow:triage -- --log <path>`
+   Without `--log`, the planner uses `.local/workflow-last-failure.json` when present.
+3. Verify the classification:
+   - regression: reproduce the smallest test, typecheck target, or build surface;
+   - environment: inspect runtime, paths, dependencies, process ownership, and timeouts;
+   - provider/configuration: stop and request approval or missing configuration;
+   - known flake: prove the signature matches `tests/flake-ledger.json` before treating it as such.
+4. Change only the smallest confirmed cause. Do not hide failures by weakening assertions, increasing timeouts blindly, or broad refactoring.
+5. Rerun the smallest failing target after each fix. Widen to `verify:cheap`, `verify:ui`, or `verify:pr-local` only after it passes.
+6. Distinguish code defects, pre-existing failures, environment blockers, and provider gates in the final report.
+
+Never use provider access to diagnose a local failure without explicit confirmation.

.agents/skills/verify-triage-fix/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Verify Triage Fix"
+  short_description: "Diagnose and fix verification failures"
+  default_prompt: "Use $verify-triage-fix to diagnose the current local verification failure, fix the smallest confirmed cause, and rerun focused checks."

.gitignore

@@ -18,11 +18,15 @@
 /playwright-cli/
 /.playwright-cli/
 /playwright/.auth/
+/.local/
 /.codex/
 /.agents/*
 !/.agents/plugins/
+/.agents/plugins/**
 !/.agents/plugins/marketplace.json
 !/.agents/plugins/api_marketplace.json
+!/.agents/skills/
+!/.agents/skills/**
 /skills-lock.json
 
 # next.js

AGENTS.md

@@ -317,6 +317,24 @@ After completing `upload`, summarize the current branch and worktree state, whet
 
 <!-- END:codex-productivity-defaults -->
 
+<!-- BEGIN:repo-productivity-skills -->
+
+## Repository productivity skills
+
+Use the repo-local skills under `.agents/skills/` when their descriptions match. They are thin orchestration layers over `scripts/productivity-workflow.mjs`; do not copy their procedures into this file.
+
+- `database-flightplan`: plan risk-scoped verification before non-trivial changes.
+- `verify-triage-fix`: diagnose and repair local verification failures with the smallest reproducer.
+- `clinical-change-proof`: assemble clinical, privacy, source, and rollback evidence.
+- `live-design-sweep`: inspect the running app across routes, breakpoints, and accessibility modes.
+- `rag-change-lab`: validate retrieval and answer changes offline first, then prepare live-eval approval gates.
+- `operator-closeout`: turn pending operator debt into a deduplicated, approval-gated batch.
+- `session-lifecycle`: manage safe start, handoff, merge proof, and cleanup transitions.
+
+Run the matching planner command in `docs/productivity-workflows.md` without side effects by default. Add `-- --run` only to execute its local/offline checks. The workflow engine must never execute commands listed under `approvalRequired`.
+
+<!-- END:repo-productivity-skills -->
+
 ## Codex GitHub review behavior
 
 These instructions apply to Codex GitHub pull request reviews and Codex tasks started from PR comments.

docs/branch-review-ledger.md

@@ -569,3 +569,4 @@ Use this ledger to prevent repeated branch and PR reviews when the reviewed HEAD
 | 2026-07-17 | codex/historical-branch-cleanup-20260717 | e36ac0c6628264c7ed6c494a597a62d0214b68f6 | branch-cleanup and historical-content recovery | Completed the pending historical cleanup: deleted 55 exact-SHA remote refs and 20 redundant local refs, removed nine clean merged worktrees, preserved every dirty, active, open-PR, or patch-unique worktree, and recovered the still-useful governance incident runbook from `codex/domain-1-governance-remediation`. Historical code changes were either tied to merged PRs or reviewed as superseded by current implementations; open PRs #699, #700, #702, and #704 remain protected. | Fresh `git fetch --prune`; GitHub PR inventory and exact commit-to-merged-PR associations; exact remote SHA rechecks before deletion; cherry-pick-aware logs; two-dot tree and branch-only-file review; Codex task-to-worktree cross-check; focused documentation validation recorded in the cleanup PR. No OpenAI, Supabase, production-data, or live clinical workflow was run. |
 | 2026-07-17 | PR #704 / codex/scroll-geometry-stability-20260717 | 35e74ddbd61bacc5b34f06efbd58091f092665fd | nested scroll-source review follow-up | Confirmed the outside-diff CodeRabbit finding: the standalone shell shared one intent history across main and descendant scroll containers, so a switch from a deep main offset to a near-zero nested offset could falsely reveal chrome. Scroll metrics now identify their source, source changes rebase direction and travel while preserving visibility, and unit/UI regressions cover the switch. No unresolved actionable review finding remains. | Focused Vitest 9/9; TypeScript; scoped ESLint; Prettier; `git diff --check`. Exact-head hosted CI and UI remain required after push. No Supabase/OpenAI/live-provider checks run. |
 | 2026-07-17 | codex/scrolling-cleanup-20260717 | ff77cd06c + latest origin/main sync | cross-page scrolling and interaction stability review | Fixed two confirmed P2 defects: desktop action-popup placement performed synchronous geometry work for every captured scroll event, and submitted differential searches with zero document matches fell back to the home state. Placement is now coalesced per animation frame with passive scroll listeners, and submitted empty-evidence results remain visible. Hardened three popup/navigation browser helpers that reproduced hydration timing failures. No other high-confidence defect remains in the scoped diff. | Scroll-focused Chromium 28/28; final affected Chromium 5/5; source regressions 2/2; scoped ESLint; Prettier; TypeScript and production build passed before the final upstream-only sync; `git diff --check`. The aggregate local Vitest/UI runs were affected by concurrent-worktree resource contention, so exact-head hosted CI remains required before merge. No Supabase/OpenAI/live-provider checks run. |
+| 2026-07-17 | PR #713 / codex/chat-workflow-ideas-0916 | b52112df6aa36311d7420189064acd79dcf2c3f5 + reviewed follow-up diff | workflow toolkit review follow-up | Fixed all 14 actionable Codex and CodeRabbit threads: cross-platform path fixtures, installation-managed preflight guidance, complete Supabase-backed API database scoping, per-command approval boundaries, plugin-ignore narrowing, isolated CI-scope proof, remote-Git command guarding, repository-skill verification classification, `TypeError` diagnosis, strict CLI option values, machine-parseable JSON evidence output, and preservation of baseline database/clinical approval gates in the RAG lab. No unresolved actionable finding remains in the reviewed scope. | `npm run verify:cheap` passed with 273 files and 2,599 tests; focused toolkit Vitest 20/20; CI-scope self-test; plugin-ignore proof; `git diff --check`. Exact-head hosted CI remains required after the follow-up push. No Supabase, OpenAI, or other live product-provider command was run. |