From 52e2f0c15e79c2abbfe3a2569df38e11dab51aa3 Mon Sep 17 00:00:00 2001 From: BigSimmo <87357024+BigSimmo@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:48:37 +0800 Subject: [PATCH 01/13] docs: remediate documentation audit findings and add automated docs:maintain pipeline --- .claude/skills/gates/SKILL.md | 27 +- .claude/skills/handoff/SKILL.md | 14 +- .claude/skills/issues/SKILL.md | 22 +- .claude/skills/newtask/SKILL.md | 11 +- .env.example | 34 +- AGENTS.md | 113 +--- PROJECT-INSTRUCTIONS-CONTINUATION.md | 27 +- README.md | 4 +- data/hazard-register-snapshot.json | 2 +- data/repo-awareness-snapshot.json | 296 +++++---- docs/DOCS-SYSTEM.md | 10 +- docs/README.md | 40 +- docs/agents/bug-hunter-shortcut.md | 2 +- docs/agents/codex-review-throttling.md | 11 +- docs/agents/cursor-cloud.md | 2 +- docs/agents/external-skill-precedence.md | 15 +- docs/agents/pull-request-workflow.md | 16 +- docs/agents/verification-gates.md | 6 +- .../ABSOLUTE_FINAL_STATUS.md | 2 + .../ADDITIONAL_RECOMMENDATIONS.md | 2 + .../CODE_REVIEW_SUMMARY.md | 2 + .../COMPLETE_DOCUMENTATION_INDEX.md | 2 + .../COMPLETE_ISSUE_INVENTORY.md | 2 + .../DEPLOYMENT_CHECKLIST.md | 2 + .../DOCKERFILE_OPTIMIZATIONS.md | 2 + .../EXTENDED_ISSUE_INVENTORY.md | 2 + .../FINAL_ASSESSMENT.md | 2 + .../FINAL_VERDICT.md | 2 + .../IMPLEMENTATION_COMPLETE.md | 2 + .../MASTER_ISSUE_TRACKER.md | 2 + .../POST_FIX_CHECKLIST.md | 2 + .../PRODUCTION_DEPLOYMENT_GUIDE.md | 2 + .../QUICK_REFERENCE.md | 2 + .../README_CODE_REVIEW.md | 2 + .../READY_TO_DEPLOY.md | 2 + .../VERIFICATION_REQUIRED.md | 2 + docs/branch-review-index.md | 18 +- docs/branch-review-ledger.md | 9 +- docs/care-plan/crisis-lines-verification.md | 27 +- docs/ci-operations.md | 20 +- docs/cme-adoption-contract.md | 5 +- docs/codebase-index.md | 247 ++++--- docs/database-remediation-plan.md | 11 +- docs/database-remediation-playbook.md | 25 +- docs/db-maintenance.md | 2 +- .../2026-08-22-automated-review-coverage.md | 2 +- docs/deployment-architecture.md | 22 +- docs/design-system-contract.md | 2 +- docs/design-system.md | 33 +- docs/design-system/ADOPTION.md | 4 +- docs/design-system/DECISIONS.md | 15 +- docs/design-system/README.md | 1 + docs/design-system/SPEC.md | 37 +- docs/developer-area-access.md | 35 +- docs/development-speed-playbook.md | 9 +- docs/dictionary-editorial-drafts.md | 34 +- docs/disaster-recovery-runbook.md | 2 +- docs/docker-optimization-guide.md | 96 +-- docs/filter-contract.md | 46 +- ...rivacy-role-attestation-pack-2026-09-01.md | 6 +- docs/launch-operator-runbook.md | 8 +- docs/multi-user-auth-setup.md | 10 +- docs/observability-slos.md | 18 +- docs/organisation/pins.json | 42 +- docs/organisation/systems/answer-engine.json | 3 + docs/organisation/systems/app-experience.json | 34 +- .../systems/clinical-content.json | 2 + docs/organisation/systems/data-platform.json | 1 + docs/organisation/systems/delivery.json | 1 + docs/organisation/systems/design-system.json | 5 + docs/organisation/systems/knowledge.json | 2 +- .../systems/personal-practice.json | 2 +- docs/organisation/systems/prototypes.json | 2 +- .../plans/edge-ingestion-overhaul-3pr-plan.md | 9 +- docs/process-hardening.md | 24 +- docs/production-readiness-checklist.md | 5 +- docs/production-readiness.md | 4 +- ...chitecture-maintainability-ultra-review.md | 4 +- .../codex-cloud-design-status-semantics.md | 4 +- docs/prompts/codex-cloud-detailed-task.md | 2 +- ...codex-data-database-safety-ultra-review.md | 4 +- ...ex-documentation-ownership-ultra-review.md | 4 +- ...dex-functional-correctness-ultra-review.md | 4 +- ...ex-performance-reliability-ultra-review.md | 4 +- .../codex-tests-quality-gates-ultra-review.md | 4 +- ...aware-clinical-ask-codex-cloud-handover.md | 2 +- docs/prompts/rag-coverage-gate-extraction.md | 5 +- docs/rag-evaluation.md | 11 +- docs/reindex-runbook.md | 4 +- docs/scripts-index.md | 2 +- docs/search-results-bar-decisions.md | 33 +- docs/staging-setup.md | 12 +- docs/supabase-migration-reconciliation.md | 6 +- .../plans/2026-08-20-rag-adaptive-answer.md | 2 +- .../2026-08-20-rag-evaluation-rollout.md | 20 +- ...-08-21-trusted-admin-document-ingestion.md | 3 +- ...026-08-23-outstanding-p2-p3-remediation.md | 2 +- .../plans/2026-09-01-sources-mode.md | 9 +- .../plans/2026-08-20-rag-adaptive-answer.md | 2 +- .../2026-08-20-rag-evaluation-rollout.md | 20 +- ...-08-21-trusted-admin-document-ingestion.md | 3 +- .../plans/2026-08-20-rag-adaptive-answer.md | 2 +- .../2026-08-20-rag-evaluation-rollout.md | 20 +- ...-08-21-trusted-admin-document-ingestion.md | 3 +- docs/testing.md | 53 +- package.json | 4 +- scripts/check-docs-links.mjs | 2 +- scripts/check-docs-script-refs.mjs | 8 +- scripts/generate-hazard-register-snapshot.mjs | 70 +- scripts/generate-repo-awareness-snapshot.ts | 33 +- scripts/list-database-skills.mjs | 17 + scripts/maintain-docs-system.mjs | 616 ++++++++++++++++++ scripts/organisation/check-retired-rules.mjs | 2 + scripts/pr-policy.mjs | 17 +- tests/maintain-docs-system.test.ts | 253 +++++++ 115 files changed, 1946 insertions(+), 888 deletions(-) create mode 100644 scripts/maintain-docs-system.mjs create mode 100644 tests/maintain-docs-system.test.ts diff --git a/.claude/skills/gates/SKILL.md b/.claude/skills/gates/SKILL.md index 1f3408c727..02dc11c5a2 100644 --- a/.claude/skills/gates/SKILL.md +++ b/.claude/skills/gates/SKILL.md @@ -19,9 +19,10 @@ Check these before believing any result. - **`verify:ui` under heavy-lock contention waits, then fails — it does not soft-skip green.** When another worktree holds the exclusive lease, `acquireHeavyRunLock` queues Playwright admission for - up to 15 minutes and throws on timeout; `run-playwright.mjs` catches that error and exits `1`. Do - not treat a long wait or a red contention timeout as a false-green soft-skip. When the gate does - run, grep the output for the `N passed` line — exit `0` alone is never proof. + up to 15 minutes and throws on timeout; `scripts/run-playwright.mjs` catches that error and exits + **`75`** (`DATABASE_HEAVY_RUN_ADMISSION_BUSY`), not `1`. Do not treat a long wait or a contention + timeout (`75`) as a false-green soft-skip or a product test failure. When the gate does run, grep + the output for the `N passed` line — exit `0` alone is never proof. - **A stale worktree makes every downstream gate a lie.** `check:installed-lock-parity` fails closed for exactly this reason — if installed packages do not match `package-lock.json`, treat any test, lint, or typecheck result as void until `npm ci` has run. Its own failure message says as much. @@ -41,16 +42,16 @@ Match the gate to what actually changed. Running a broader gate is not more rigo observe the change; running a narrower one is not sloppy if it can. Add a second gate only when it covers a distinct plausible regression and the incremental confidence justifies its cost. -| Change | Gate that can actually fail | -| --------------------------- | --------------------------------------------------------------------------------------------------- | -| Markdown / docs only | `prettier --check`, `docs:check-links`, `docs:check-index` | -| Localised source behavior | `test:focused -- --files ` | -| Ordinary pre-PR check | `verify:cheap` — lock parity + lint + typecheck + unit tests | -| Cross-module/unknown scope | `verify:full` — 42 static gates then lint + typecheck + test (does not invoke cheap; check 2 of 45) | -| Before PR handoff | `verify:pr-local` (risk-routed; inspect with `--dry-run`) | -| UI, styling, routing, a11y | `npm run ensure`, affected journey, broad UI only when shared | -| Phone chrome | `verify:phone-chrome` (narrower than `verify:ui`; run it first) | -| Explicit release confidence | `verify:release` (provider approval still required) | +| Change | Gate that can actually fail | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Markdown / docs only | `prettier --check`, `docs:check-links`, `docs:check-index` | +| Localised source behavior | `test:focused -- --files ` | +| Ordinary pre-PR check | `verify:cheap` — `check:installed-lock-parity` + `check:diff-integrity` + `lint` + `typecheck` + `test` | +| Cross-module/unknown scope | `verify:full` — 42 static gates (`check:runtime` through `check:offline-pack` terminal static gate) then `lint` + `typecheck` + unit `test` (+ `build` in PRs) | +| Before PR handoff | `verify:pr-local` (risk-routed; inspect with `--dry-run`) | +| UI, styling, routing, a11y | `npm run ensure`, affected journey, broad UI only when shared | +| Phone chrome | `verify:phone-chrome` (narrower than `verify:ui`; run it first) | +| Explicit release confidence | `verify:release` (includes `build` + full Playwright + governance/eval; provider approval required) | `lint`, `typecheck`, and `test` cannot observe a markdown-only change. Say so rather than running them for appearance. diff --git a/.claude/skills/handoff/SKILL.md b/.claude/skills/handoff/SKILL.md index 3fe310fc2f..ffd11d4d8c 100644 --- a/.claude/skills/handoff/SKILL.md +++ b/.claude/skills/handoff/SKILL.md @@ -36,12 +36,11 @@ force-push, or discard work. blindly. Do not stage `.env*`, secrets, build output, logs, or unrelated WIP; if you see a possible secret, report the path (never the value) and stop. 3. **Format and verify.** From a fully owned feature worktree, run `npm run format`, inspect the - complete formatter diff, and include only intended formatting. Then invoke - `verification-router` (or the `gates` skill when scope is already clear) and run the one - smallest sufficient gate it selects. Default PR-ready work uses + complete formatter diff, and include only intended formatting. Then invoke the `gates` / `plan` + skills and run the one smallest sufficient gate they select. Default PR-ready work uses `npm run verify:pr-local`; inspect its selection with `--dry-run` when uncertain. For UI/routing/styling, prove the affected journey first and add `verify:ui` only for shared UI - foundations or when the router says its distinct coverage is necessary. Never stack + foundations or when the planner says its distinct coverage is necessary. Never stack `verify:cheap` + `verify:ui` + `verify:release` by default. - Touched `src/app/`, `src/components/`, or `tests/` (or design-system adoption inputs): run `npm run design-system:adoption:update` and stage any regenerated @@ -61,8 +60,11 @@ force-push, or discard work. a force-push or base change is not ([Merge authority](../../../docs/agents/pull-request-workflow.md#merge-authority)). Never pipe the push through `tail`, `head`, or another command that can mask its status. Confirm the remote tip equals local HEAD - with `git ls-remote` before reporting success. The pre-push guards run - (auto-merge sentinel, format, drift) — heed a block rather than overriding blindly. + with `git ls-remote` before reporting success. The pre-push guards in `scripts/guard-push.mjs` run + (non-bypassable auto-merge sentinel, plus scoped overrides `SKIP_STATIC_GUARD=1`, + `SKIP_DRIFT_GUARD=1`, `SKIP_FORMAT_GUARD=1`, `SKIP_BROWSER_GUARD=1`, + `SKIP_IN_FLIGHT_CI_GUARD=1`, and `SKIP_LEDGER_WRITE_GUARD=1`) — heed a block rather than + overriding blindly. **Restarting a branch whose PR already merged:** GitHub deletes the remote branch on merge, so the local `origin/` ref is stale and `--force-with-lease` fails with `stale info` diff --git a/.claude/skills/issues/SKILL.md b/.claude/skills/issues/SKILL.md index 2795826f29..e7bd399a65 100644 --- a/.claude/skills/issues/SKILL.md +++ b/.claude/skills/issues/SKILL.md @@ -5,9 +5,11 @@ description: Track and recall all outstanding tasks, recommendations, and issues # issues — the outstanding-work memory -`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. +`docs/outstanding-issues.md` is the repository outstanding-issues ledger — the single universal, +durable, cross-session register for recommended execution order, open **tasks**, **recommendations**, +**issues**, provider/operator work, and archive history (while `docs/task-receipts.md` governs +canonical task lifecycle and receipt handoff). Chat context resets; `docs/outstanding-issues.md` +does not. This skill reads it back and keeps it current. **The ledger on the remote `main` branch is the source of truth, not chat memory or a stale worktree.** Never answer `/issues` from conversation recall or by reading the checkout file @@ -60,8 +62,9 @@ read-only `/issues` needs no such check. Recorded as `#292`. Parse the intent from natural language too — the exact syntax is a convenience, not a requirement. - **`/issues add `** — queue an immutable `add` request. Infer `Pri`/`Type` from the text - (ask only if genuinely ambiguous; default `P2`/`task`). The serial reconciler allocates the - numeric issue ID later; a feature branch must never read or bump the `issues:next-id` marker. + (ask only if genuinely ambiguous; default `P2`/`task`). `scripts/outstanding-issues.mjs` and the + serial reconciler allocate ULID-backed 6-character Crockford Base32 `#XXXXXX` IDs; a feature + branch must never hand-allocate IDs or edit canonical rows directly. - **`/issues done [outcome]`** — queue an immutable `done` request for the existing canonical ID and its one-line outcome. Reconciliation moves the row to **Resolved / archive** and updates any recommended-queue references. @@ -91,14 +94,15 @@ paragraph; put the smallest next action in **Detail / next action**. ```bash npm run issues:add -- --pri P2 --type issue --summary "…" --detail "…" --source "…" -npm run issues:done -- '#151' --outcome "Resolved 2026-07-31 by PR #1494. …" -npm run issues:update -- '#151' --detail "…" -npm run issues:queue -- '#151' --acuity A3 --when "After the next release" +npm run issues:done -- '#M6JNR8' --outcome "Resolved 2026-07-31 by PR #1494. …" +npm run issues:update -- '#M6JNR8' --detail "…" +npm run issues:queue -- '#M6JNR8' --acuity A3 --when "After the next release" ``` Each command creates one validated UUID JSON file under `docs/outstanding-issues-inbox/`; it does not edit `docs/outstanding-issues.md`. Requests are immutable and merge independently. Only a -dedicated fresh-base ledger branch may run `npm run issues:reconcile`, which allocates IDs, applies +dedicated fresh-base ledger branch may run `npm run issues:reconcile`, which allocates ULID-backed +6-character Crockford Base32 `#XXXXXX` IDs via `scripts/outstanding-issues.mjs`, applies requests serially, and moves them to `docs/outstanding-issues-inbox/applied/`. Never reconcile as part of an ordinary product PR. diff --git a/.claude/skills/newtask/SKILL.md b/.claude/skills/newtask/SKILL.md index a31f46c551..9f64710fef 100644 --- a/.claude/skills/newtask/SKILL.md +++ b/.claude/skills/newtask/SKILL.md @@ -53,7 +53,7 @@ almost always has a pushed branch named after it. Report which check you used. O under `C:\Users\…`: ```bash - git worktree add -b claude/ D:/Repos/Database/.claude/worktrees/ origin/main + git worktree add -b claude/ D:/Repos/PsychSift/.claude/worktrees/ origin/main ``` Use a short, descriptive ``. @@ -73,12 +73,13 @@ almost always has a pushed branch named after it. Report which check you used. O and `C:\Users\joshs\.gemini\` belong to Codex and Antigravity sessions — leave them alone and do not count them. -3. **Install deps in the new worktree** (worktrees do NOT share `node_modules`; a cold - worktree fails `vitest`/`tsc`). `npm ci` keeps the lockfile untouched: +3. **Install deps in the new worktree** (a cold worktree fails `vitest`/`tsc`). Prefer + `node scripts/setup-codex-worktree.mjs`, which reuses a byte-identical donor `node_modules` + before falling back to `npm ci --include=dev --prefer-offline --no-audit --no-fund`: ```bash - cd D:/Repos/Database/.claude/worktrees/ && npm ci --no-audit --no-fund + cd D:/Repos/PsychSift/.claude/worktrees/ && npm ci --include=dev --prefer-offline --no-audit --no-fund ``` - `postinstall` installs the pre-push guards automatically. + `postinstall` writes the lock-parity stamp and installs the pre-push guards automatically. 4. **Confirm the base is current:** `node scripts/check-base-freshness.mjs` — expect `behind 0`. If it reports behind, the fetch/worktree base is stale; recreate. 5. **Warm routes before any browser/UI work** (fresh worktrees can hash onto a diff --git a/.env.example b/.env.example index 0aa75f3f8e..054ab4eabc 100644 --- a/.env.example +++ b/.env.example @@ -54,7 +54,7 @@ HEALTH_DEEP_PROBE_SECRET=your-long-random-health-deep-probe-secret # only by `npm run test:cross-tenant:staging`; never point them at production. # The two accounts must be distinct, non-human staging test users. The staging # app must use the same Supabase project and RAG_PROVIDER_MODE=offline. -#CROSS_TENANT_STAGING_APP_URL=https://clinical-kb-staging.example.org +#CROSS_TENANT_STAGING_APP_URL=https://psychsift-staging.example.org #CROSS_TENANT_SUPABASE_URL=https://your-staging-project-ref.supabase.co #CROSS_TENANT_PROJECT_REF=your-staging-project-ref #CROSS_TENANT_PUBLISHABLE_KEY=your-staging-publishable-key @@ -148,22 +148,29 @@ OPENAI_TEXT_VERBOSITY=low # offline: never call OpenAI; lexical retrieval + deterministic source-only answers only. RAG_PROVIDER_MODE=auto -# Optional server-only production error tracking. When SENTRY_DSN is absent the -# integration is inert. Events exclude request URLs/headers/bodies, user data, -# breadcrumbs, free-form context, and exception messages; browser replay stays off. +# Optional server-only production error tracking (see docs/error-tracking.md). +# When SENTRY_DSN is absent the integration is inert. Events exclude request +# URLs/headers/bodies, user data, breadcrumbs, free-form context, and exception +# messages; browser replay stays off. # Performance tracing defaults to 10% sampling for privacy-safe Supabase DB spans # (table/operation only — no query filters or mutation bodies). Set # SENTRY_TRACES_SAMPLE_RATE=0 to disable tracing while keeping error capture. # Structured Sentry Logs default on when DSN is set (allowlisted messages + # attributes only; no console capture). Set SENTRY_ENABLE_LOGS=false to disable. # Choose and document region, retention, access, and alert routing before enabling. -# Never expose this value as NEXT_PUBLIC_*. +# Never expose SENTRY_DSN as NEXT_PUBLIC_*. SENTRY_DSN= SENTRY_ENVIRONMENT=production # SENTRY_TRACES_SAMPLE_RATE=0.1 # SENTRY_ENABLE_LOGS=false # One-shot Sentry Logs wizard verify (emits "User triggered test log" at Node boot). # SENTRY_SEND_TEST_LOG=true +# Optional source-map upload (build/CI only). Set all three together, or leave all unset. +#SENTRY_ORG= +#SENTRY_PROJECT= +#SENTRY_AUTH_TOKEN= +# Optional explicit release tag for Sentry events; if blank, commit SHA is used. +#NEXT_PUBLIC_SENTRY_RELEASE= # Optional JSON override for app-layer ranking weights (see src/lib/ranking-config.ts). # Omit for current defaults. Example (enable diversity demotion + linear freshness): # RAG_RANKING_CONFIG={"documentDiversityPenalty":0.03,"freshness":{"mode":"linear"}} @@ -215,7 +222,7 @@ RAG_AWAIT_QUERY_LOGS=false # signed-in user whose Supabase app_metadata.site_role is "administrator". # Assign that claim only through the approval-gated auth:set-administrator script. # Optional canonical public origin for generated metadata, for example -# https://clinical-kb.example.org. Railway deployments otherwise use the +# https://psychsift.example.org. Railway deployments otherwise use the # provider-supplied RAILWAY_PUBLIC_DOMAIN; request hosts are only used in dev. #NEXT_PUBLIC_SITE_URL= # Persist raw clinical query text in logs. Default off; blocked in production readiness. @@ -336,21 +343,6 @@ TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe #RAILWAY_TOKEN= #RAILWAY_API_TOKEN= -# Optional privacy-safe production server error tracking (see docs/error-tracking.md). -# Server-side DSN only — leave unset to keep tracking inert. Do not set a browser -# NEXT_PUBLIC_SENTRY_DSN; browser telemetry and replay stay disabled. Server -# tracing defaults on at 10% with redacted Supabase DB spans when SENTRY_DSN is set. -# Structured Logs also default on with DSN (disable with SENTRY_ENABLE_LOGS=false). -#SENTRY_DSN= -#SENTRY_TRACES_SAMPLE_RATE=0.1 -#SENTRY_ENABLE_LOGS=false -# Optional source-map upload (build/CI only). Set all three together, or leave all unset. -#SENTRY_ORG= -#SENTRY_PROJECT= -#SENTRY_AUTH_TOKEN= -# Optional explicit release tag for Sentry events; if blank, commit SHA is used. -#NEXT_PUBLIC_SENTRY_RELEASE= - # --- Agent tooling only (not read by Next.js / env.ts) --- # Context7 MCP — versioned library docs for agents (Tailwind 4, Zod 4, Playwright, # Vitest, React 19, @supabase/supabase-js, …). Wired in `.cursor/mcp.json` as diff --git a/AGENTS.md b/AGENTS.md index 63a4f34f59..954f4d84ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -140,76 +140,23 @@ Read and follow [External skill precedence](docs/agents/native-startup/external- # Supabase project safety - This repo targets the live Supabase project `PsychSift Production`. -- **MERGING TO `main` DEPLOYS TO PRODUCTION.** The Supabase GitHub integration has **"Deploy to - production" ENABLED**, production branch **`main`** — confirmed by a dashboard read on 2026-08-21, - after two earlier sessions inferred it wrongly in both directions. Any migration merged to `main` is - applied to the live clinical database automatically, within seconds (measured at 34 s in - `docs/audit/live-drift-forensics-2026-08.md` §3.7). There is no separate deploy step to forget and no - window to hold it back. Therefore: - - **Treat merge approval as production-deploy approval.** Never merge a PR touching - `supabase/migrations/**` outside an approved window, and never enable auto-merge on one. - - **Never write PR metadata promising a deferred deploy.** There is no deploy step to defer to, - so "AWAITING DEPLOY WINDOW", "deployed manually after merge", "deployment is pending operator - approval" and "not yet applied" all describe a control this repository does not have — and they are dangerous exactly when believed, because - they invite a reviewer to merge a change they think is still parked. PR #2502 carried that - phrase in its own title and reached the live database within minutes of merge; the post-merge - `live-drift` run caught it as pending-apply drift. State the merge decision instead ("merge only - inside the approved window"), which is the control that actually exists. `scripts/pr-policy.mjs` - hard-blocks the claim on any PR touching `supabase/migrations/**` and quotes the offending - phrase back. The title is always in scope; body statements must name the database subject, so a - mixed PR keeps saying "do not deploy the staging worker until its image passes smoke tests" — - a real constraint on something merging does not do. Approval sought BEFORE merge is likewise - sanctioned and never matched. Patterns and their pinned behaviour table live in - `scripts/pr-policy.mjs` beside the RAG and governance gates. - - **After such a PR merges, the schema-application gate is the post-merge `live-drift` workflow** - (`.github/workflows/live-drift.yml`), which must complete with BOTH `npm run check:drift` and - `npm run check:migration-history` green. `supabase migration list` is not that gate: it reads the - recorded history only, so it cannot tell an applied migration from a history row whose statements - never executed — the exact shape of the fifteen no-statements rows `#Q5JHBJ` exists for. - `check:drift` compares the live schema itself. A manual `supabase migration list --linked ---project-ref sjrfecxgysukkwxsowpy` read is a useful supplement, but it is provider-backed and so - needs explicit user confirmation first, per "API and provider confirmation boundary" above. A - merged-but-unapplied migration is silent drift — the incident this whole programme exists to - close. - - **A migration that cannot run inside a transaction cannot ship this way.** The integration applies - each migration in one transaction, so a bare `CREATE INDEX CONCURRENTLY` migration fails outright. - Index work stays operator-prebuild + a validate-only guard migration (the `20260804110240` pattern, - see the guard-migration contract below). - - **Automatic branching is also ON** (one preview database per PR that changes `supabase/**`, limit - 3). Supabase warns that Branching Compute is **not covered by the organisation's Spend Cap**. CI's - `Migration replay` job (`db-reset-verify`, `supabase migration up --local`) independently replays - the whole chain on every database-touching PR, so preview branches are a second net rather than the - only one. +- **MERGING TO `main` DEPLOYS TO PRODUCTION.** The Supabase GitHub integration has **"Deploy to production" ENABLED** on branch **`main`** (confirmed 2026-08-21). Any migration merged to `main` applies to the live clinical database automatically within seconds (34 s in `docs/audit/live-drift-forensics-2026-08.md` §3.7), with no separate deploy step or hold window: + - **Treat merge approval as production-deploy approval.** Never merge a PR touching `supabase/migrations/**` outside an approved window, and never enable auto-merge on one. + - **Never write PR metadata promising a deferred deploy.** Phrases like "AWAITING DEPLOY WINDOW", "deployed manually after merge", "deployment is pending operator approval", and "not yet applied" describe a control this repo lacks and invite premature merges (as on PR #2502). State the merge gate instead ("merge only inside the approved window"). `scripts/pr-policy.mjs` hard-blocks deferred-deploy claims on PRs touching `supabase/migrations/**` (title always in scope; body statements must name the database subject; pre-merge approval phrasing and non-DB deploy constraints remain allowed). + - **After such a PR merges, the schema-application gate is the post-merge `live-drift` workflow** (`.github/workflows/live-drift.yml`), which must complete with BOTH `npm run check:drift` and `npm run check:migration-history` green. `supabase migration list` reads recorded history only and cannot detect no-statements rows (`#Q5JHBJ`), whereas `check:drift` compares the live schema. A manual `supabase migration list --linked --project-ref sjrfecxgysukkwxsowpy` read is an optional provider-backed supplement requiring explicit user confirmation first. + - **Transactional execution only.** Each migration runs in one transaction, so bare `CREATE INDEX CONCURRENTLY` fails; use operator-prebuild + a validate-only guard migration (`20260804110240` pattern below). + - **Automatic branching is ON** (one preview DB per `supabase/**` PR, limit 3; Branching Compute is **not covered by the Spend Cap**). CI's `Migration replay` job (`db-reset-verify`, `supabase migration up --local`) independently replays the chain on every DB PR. - Expected project ref: `sjrfecxgysukkwxsowpy`. - Older unused project ref `qjgitjyhxrwxsrydablr` belongs to `Database`; treat it as stale and do not use it. - Hosted migrations, `supabase/schema.sql`, `supabase/roles.sql`, CI, and deployment tooling must target role `postgres`; never assume a platform-reserved role. The single older applied migration is immutable and pinned by `npm run check:migration-role`. - Bare-image storage scaffolding must discover its local schema owner at runtime and must never be reused as hosted migration SQL. - Run `npm run check:migration-role` after changing Supabase SQL, migration tooling, CI replay, or disaster-recovery instructions. - Run `npm run check:supabase-project` after changing Supabase env values. -- **Guard-migration contract.** Any mark-applied version, `supabase migration repair --status applied`, - hand-applied SQL later recorded as a migration, or other history repair MUST ship a fail-fast - validation guard migration in the same change, following `20260804110240_restore_rag_search_health_indexes.sql` - exactly (validates presence + `indisvalid`/`indisready` + normalized definition, never builds, - `set local` timeouts, one `raise exception`). `schema_drift_snapshot()` v2 (`20260818090000`) reports every - `supabase_migrations` version recorded without executed statements; `check:drift` fails on any such row - that lacks a reviewed `migration_history` entry in `supabase/drift-allowlist.json` pointing at its guard - (`guard.class` `validation` is mandatory for versions from 2026-08-18; `superseded`/`no_ddl` are for - pre-contract history only). Never allowlist a history row bare, and never widen an entry's class to make - it pass. Enforced offline by `tests/migration-history-guards.test.ts`; index-monitoring decisions on the - retrieval-critical tables are enforced by `tests/search-health-index-coverage.test.ts` + - `supabase/search-health-unmonitored-indexes.json` (`required_indexes` changes travel by migration only). - Full contract: `docs/database-drift-detection.md`. +- **Guard-migration contract.** Any mark-applied version, `supabase migration repair --status applied`, hand-applied SQL recorded as a migration, or history repair MUST ship a fail-fast validation guard migration in the same change, following `20260804110240_restore_rag_search_health_indexes.sql` (validates presence + `indisvalid`/`indisready` + normalized definition, never builds, `set local` timeouts, one `raise exception`). `schema_drift_snapshot()` v2 (`20260818090000`) reports no-statement `supabase_migrations` versions; `check:drift` fails unless `supabase/drift-allowlist.json` has a reviewed `migration_history` entry pointing at its guard (`guard.class` `validation` mandatory from 2026-08-18; `superseded`/`no_ddl` pre-contract only; never allowlist bare or widen class). Enforced by `tests/migration-history-guards.test.ts` and `tests/search-health-index-coverage.test.ts` + `supabase/search-health-unmonitored-indexes.json` (`required_indexes` changes via migration only). See `docs/database-drift-detection.md`. ## Supabase merge caution -Merging a PR that touches `supabase/` applies its migrations to the live clinical database -within seconds — there is no separate deploy step. Treat that merge as a production deploy. -`PR policy` still blocks edits to applied migrations and out-of-order or future-dated -migrations: **a migration already on `main` must never be edited** — ship a new migration with the -newest timestamp. Clinical-content and RAG-ranking PRs keep the clinical governance preflight, -the `RAG impact:` body line, the canary-pair requirement, and exclusion from the unattended -`Clear PRs` batch (`clinical-review-required` and `rag-evidence-required` in -`scripts/pr-batch-core.mjs`). Full rule: [Merge authority](docs/agents/pull-request-workflow.md#merge-authority). +Merging a `supabase/` PR deploys to production within seconds. `PR policy` blocks edits to applied, out-of-order, or future-dated migrations: **never edit a migration already on `main`** — ship a new timestamped migration. Clinical-content and RAG-ranking PRs keep clinical governance preflight, the `RAG impact:` line, canary-pair proof, and exclusion from `Clear PRs` (`clinical-review-required` / `rag-evidence-required` in `scripts/pr-batch-core.mjs`). Full rule: [Merge authority](docs/agents/pull-request-workflow.md#merge-authority). @@ -220,46 +167,32 @@ the `RAG impact:` body line, the canary-pair requirement, and exclusion from the Retrieval/ranking behaviour is live-validated and safeguarded. Before touching any protected surface, read `docs/rag-behaviour/` (README → behaviour-map → refuted-approaches → safeguards). -- **Flag it.** Any task that will touch `src/lib/rag/**`, clinical-search, retrieval-selection, +- **Flag it.** Any task touching `src/lib/rag/**`, clinical-search, retrieval-selection, released-search-order, ranking-config, evidence/result-sort/answer-ranking, - evidence-relevance/semantic-rerank/eval-document-matching, the source-authority tiering + evidence-relevance/semantic-rerank/eval-document-matching, source-authority tiering (`src/lib/source-authority-registry.ts`, `src/lib/australian-source-priority.ts`), the eval harness (`scripts/eval-retrieval.ts`, `scripts/lib/clinical-aliases.ts`, ranking-tuning/snapshot - tooling), the golden fixture/snapshot, or the retrieval RPCs must say so to the user BEFORE - editing, even when the change looks incidental (refactor, rename, "just a comment"). The same - applies to the two producers of retrieval inputs that sit outside `src/lib/rag/**` and are - easy to mistake for plain ingestion: the text producers (`src/lib/chunking.ts`, - `src/lib/extractors/**`, `worker/python/extract_pdf_assets.py`), which decide what ever - becomes a chunk or a citation, and the structured-evidence producers + tooling), the golden fixture/snapshot, or retrieval RPCs must notify the user BEFORE + editing, even for incidental changes. The same applies to retrieval-input producers outside `src/lib/rag/**`: text producers (`src/lib/chunking.ts`, + `src/lib/extractors/**`, `worker/python/extract_pdf_assets.py`), structured-evidence producers (`src/lib/document-index-units.ts`, `src/lib/model-index-extraction.ts`, - `src/lib/deep-memory.ts`), whose index units are queried directly by the candidate fan-out and - whose `applyMemoryCardBoosts` rescores results. Added 2026-09-16; `pr-policy` classifies all - of these as RAG-ranking surfaces, and `docs/rag-behaviour/safeguards.md` carries the reasoning. - The other retrieval inputs are covered too (added 2026-09-25): retrieval RPC version choice + `src/lib/deep-memory.ts`, `applyMemoryCardBoosts`), retrieval RPC version choice and scoring helpers (`src/lib/retrieval-rpc-rollout.ts`, `clinical-evidence-haystack.ts`, - `cross-document-synthesis.ts`, `corpus-grounding.ts`, `keyword-query.ts`), and the producers of - enrichment, image-caption, embedding-field, table-fact and assertion rows + `cross-document-synthesis.ts`, `corpus-grounding.ts`, `keyword-query.ts`), and enrichment, image-caption, embedding-field, table-fact, and assertion producers (`src/lib/document-enrichment.ts`, `visual-intelligence.ts`, `image-filtering.ts`, `worker/embedding-fields.ts`, `worker/table-facts.ts`, `worker/assertion-tagging.ts`). - The authoritative list is `ragRankingPatterns` in `scripts/pr-policy.mjs`, which also protects - the ranking contract tests; where this sentence and that list ever differ, flag everything - either names (aligned 2026-09-25). + `docs/rag-behaviour/safeguards.md` explains why. The authoritative list (including ranking contract tests) is `ragRankingPatterns` in `scripts/pr-policy.mjs`; flag anything named by either list. - **PR nudge (advisory since 2026-09-17).** PRs touching those surfaces get a `pr-policy` - **warning** — not a block — when the body has no explicit `RAG impact:` line. Still write one, - because it is the fastest way to tell a reviewer whether ordering moved: either - `RAG impact: no retrieval behaviour change — ` or - `RAG impact: behaviour change — canary pair -> `. The real safeguards are - unchanged and both still fail closed: the live eval-canary below, and the source-pin contract - test (`tests/rag-imputation-contract.test.ts`), which goes red on any edit to the imputation - formulas or release-comparator key order. + **warning** — not a block — when the body has no explicit `RAG impact:` line. Still write one + (`RAG impact: no retrieval behaviour change — ` or + `RAG impact: behaviour change — canary pair -> `). Hard fail-closed safeguards remain + the live eval-canary below and `tests/rag-imputation-contract.test.ts` (imputation formulas and release-comparator key order). - **Canary for behaviour.** Any retrieval/ranking/ordering behaviour change requires a live - eval-canary before/after pair (doc/content recall pinned 1.0, zero per-case rr regressions) - before it is trusted; regression → immediate single-commit revert + confirmation run. - Dispatches are provider-backed (~$1–2) and always need explicit user approval. + eval-canary before/after pair (doc/content recall pinned 1.0, zero per-case rr regressions); + regression → immediate single-commit revert + confirmation run. Dispatches are provider-backed (~$1–2) and require explicit user approval. - **Never** insert a comparator key above the relevance score, bulk-merge the wide captured-case alias tier into the strict golden tier, relax the clamped-score contract, or - adopt tuner recommendations without a measured live gain. Offline-green + review-approved - was proven insufficient for this surface on 2026-07-20 (see refuted-approaches). + adopt tuner recommendations without a measured live gain (see `docs/rag-behaviour/refuted-approaches.md`). diff --git a/PROJECT-INSTRUCTIONS-CONTINUATION.md b/PROJECT-INSTRUCTIONS-CONTINUATION.md index 72270a08f1..3b82c99c8b 100644 --- a/PROJECT-INSTRUCTIONS-CONTINUATION.md +++ b/PROJECT-INSTRUCTIONS-CONTINUATION.md @@ -2,13 +2,13 @@ At task start, read [task lifecycle and receipt handoff](docs/task-receipts.md) and [the organisation map](docs/organisation/README.md). -Native loading: the core stays below the 24,000-byte per-file rule limit. Linked policy is mandatory when its topic applies. Antigravity loads the same canonical modules through `.agents/rules/project-*.md`; these wrappers contain references, not policy copies. Inspect fresh native context before claiming complete loading. +Native loading: the core stays below the 24,000-byte per-file rule limit. Linked policy is mandatory when its topic applies. On disk, `.agents/rules/project-*.md` are 5-line `@[...](../../docs/agents/native-startup/*.md)` wrappers without duplicated policy prose, which Antigravity expands inline at startup. Inspect fresh native context before claiming complete loading. `AGENTS.md` is the always-loaded core; this file is its required continuation, read before any repository write or publication. `AGENTS.md` carries the boundaries that prevent irreversible harm, -and the sections a committed gate parses by exact text. Every other rule keeps its heading in -`AGENTS.md` and its full text — verbatim, nothing dropped — in this continuation or a named -reference file. Open the file before acting in its area. +and the sections or pointers a committed gate parses. Every other rule keeps its heading in +`AGENTS.md` and its full text — verbatim, nothing dropped — in `docs/agents/native-startup/*.md`, +this continuation, or a named reference file. Open the file before acting in its area. **Read these first in `AGENTS.md`; they prevent damage that cannot be undone, and their full text is there:** `# Supabase project safety` (merging a migration reaches the live clinical database within @@ -29,13 +29,16 @@ seconds, with no deploy step in between), `# RAG ranking protection`, `# Railway | Repository skills, the `/issues` outstanding-work memory | [`docs/agents/repository-skills-and-issues.md`](docs/agents/repository-skills-and-issues.md) | | Codex dependency, review throttling, desktop worktree, reasoning effort, productivity, GitHub review, Cloud; Cursor Cloud | the `docs/agents/codex-*.md` and `docs/agents/cursor-cloud.md` pointers in `AGENTS.md` | -Five always-loaded sections stay in `AGENTS.md` in full. Exact-text gate protection is narrower than -that list: `# Search chrome behaviour` is pinned by `tests/ui-overlay-css-contract.test.ts` -(marker + “Hidden means zero reserve”); `## Codex Cloud environment` is pinned as a +In `AGENTS.md`, `# Search chrome behaviour`, `## Bare PR publication is not readiness work`, and +`## Anti-conflict and CI-speed operating procedure` delegate to `docs/agents/native-startup/*.md` +via 1-line links rather than keeping inline body copies. Exact-text gate protection applies to those +targets and pointers: `tests/ui-overlay-css-contract.test.ts` pins the `search-chrome-behaviour.md` +pointer in `AGENTS.md` and the marker + “Hidden means zero reserve” in +`docs/agents/native-startup/search-chrome-behaviour.md`; `## Codex Cloud environment` is pinned as a **pointer heading** by `scripts/check-codex-cloud-setup.mjs` (body lives in -`docs/agents/codex-cloud-environment.md`); `## Bare PR publication is not readiness work` -and the format-before-push rule stay in `AGENTS.md` and are enforced operationally via skills, -hooks, and `scripts/guard-push.mjs` rather than a body-text parser; `## Anti-conflict and -CI-speed operating procedure` stays in `AGENTS.md` by convention and is **not** exact-text pinned — -silent reword would still pass `verify:full`. Do not treat every always-loaded block as +`docs/agents/codex-cloud-environment.md`); `## Bare PR publication is not readiness work` and the +format-before-push rule in `docs/agents/native-startup/process-hardening.md` are enforced +operationally via skills, hooks, and `scripts/guard-push.mjs`; and `## Anti-conflict and CI-speed +operating procedure` in `docs/agents/native-startup/publication-workflows.md` is not exact-text +pinned — silent reword would still pass `verify:full`. Do not treat every startup module as gate-locked. diff --git a/README.md b/README.md index 21e7a0f9fd..3886416500 100644 --- a/README.md +++ b/README.md @@ -272,9 +272,9 @@ Verification gates (see `package.json` for the full chain): ```bash npm run verify:cheap # ordinary offline gate: check:installed-lock-parity - # + lint + typecheck + test (nothing else) + # + check:diff-integrity + lint + typecheck + test npm run verify:full # 42 static/consistency gates (check:runtime through - # check:instructions; `npm run check:gate-manifest` + # check:offline-pack; `npm run check:gate-manifest` # lists them from verify:full:internal) then lint + # typecheck + test — does not invoke the cheap script npm run verify:pr-local # risk-routed PR mirror: focused docs/workflow contracts diff --git a/data/hazard-register-snapshot.json b/data/hazard-register-snapshot.json index dea0ec6ec0..dcee58e881 100644 --- a/data/hazard-register-snapshot.json +++ b/data/hazard-register-snapshot.json @@ -1,6 +1,6 @@ { "version": "hazard-register-snapshot-v1", - "generatedAt": "2026-10-07", + "generatedAt": "2026-10-10", "counts": { "registers": 1, "registersMissing": 0, diff --git a/data/repo-awareness-snapshot.json b/data/repo-awareness-snapshot.json index 9c8b1da9be..03bab38426 100644 --- a/data/repo-awareness-snapshot.json +++ b/data/repo-awareness-snapshot.json @@ -2374,12 +2374,12 @@ { "path": "docs/superpowers/specs/2026-09-26-cpd-elevation-design.md", "section": "superpowers", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-16-withhold-unreliable-differential-bodies.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/developer-area-access.md", @@ -2389,7 +2389,7 @@ { "path": "docs/decisions/2026-09-19-registry-records-is-clinical-risk.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/agents/context7.md", @@ -2404,7 +2404,7 @@ { "path": "docs/decisions/2026-09-26-loose-around-pages-and-modes.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/interaction-matrix.md", @@ -2414,12 +2414,12 @@ { "path": "docs/decisions/2026-09-04-on-call-readable-by-every-visitor.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/codescene-non-rag-remediation-2026-10-09.md", "section": "audit", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/local/specs/2026-08-21-trusted-admin-document-ingestion-design.md", @@ -2449,7 +2449,7 @@ { "path": "docs/audit/full-repository-adversarial-audit-2026-10-09.md", "section": "audit", - "catalogued": false + "catalogued": true }, { "path": "docs/multi-user-auth-setup.md", @@ -2489,7 +2489,7 @@ { "path": "docs/decisions/2026-09-25-youth-crisis-wording-shows-both-lines.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/review-findings-2026-08-02.md", @@ -2524,7 +2524,7 @@ { "path": "docs/decisions/2026-09-26-keep-review-fallback-citations.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/BRANCH_ARCHIVE_20260709.md", @@ -2544,7 +2544,7 @@ { "path": "docs/superpowers/plans/2026-09-26-cpd-elevation.md", "section": "superpowers", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-08-23-platform-contracts-readiness.md", @@ -2554,7 +2554,7 @@ { "path": "docs/decisions/2026-09-26-remove-ward-flow-and-caring-contacts.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/repo-audit-2026-07-01.md", @@ -2574,12 +2574,12 @@ { "path": "docs/decisions/2026-08-27-evidence-preview-on-by-default.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-23-cme-explicit-capture-only.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/operations-runbook.md", @@ -2614,17 +2614,17 @@ { "path": "docs/decisions/2026-09-19-brand-sheet-self-hosts-fonts.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-08-31-source-drawer-opens-on-the-passage.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-25-medication-default-sources.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/reports/task-7-report.md", @@ -2659,7 +2659,7 @@ { "path": "docs/decisions/2026-09-13-on-call-section-pages-show-their-groups.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/redesign/08-design-review-prompt.md", @@ -2669,12 +2669,12 @@ { "path": "docs/decisions/2026-09-26-register-crisis-line-publishers.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-07-answer-matches-line-rests-open.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/rag-injection-threat-model.md", @@ -2714,7 +2714,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/README_CODE_REVIEW.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/operator-supabase-branching-cap.md", @@ -2729,7 +2729,7 @@ { "path": "docs/decisions/2026-08-26-answer-page-direction-b.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/tenancy-defense-in-depth-review.md", @@ -2764,12 +2764,12 @@ { "path": "docs/decisions/2026-08-29-compact-roles-tap-floor-40px.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-08-28-logo-single-colour.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/verification-report.md", @@ -2784,7 +2784,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/DEPLOYMENT_CHECKLIST.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/specs/2026-09-01-services-safety-provenance-design.md", @@ -2799,7 +2799,7 @@ { "path": "docs/decisions/2026-08-19-therapy-ships-with-review-state-disclosed.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/canonical/execution-order.md", @@ -2809,7 +2809,7 @@ { "path": "docs/decisions/2026-09-25-failure-alerts-reach-the-owners-phone.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/codex-review-protocol.md", @@ -2829,12 +2829,12 @@ { "path": "docs/decisions/2026-09-25-site-catalogue-first-publication.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-25-mha-timeline-outside-samd-note.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/rag-improvement/HANDOVER.md", @@ -2849,7 +2849,7 @@ { "path": "docs/decisions/2026-10-10-new-job-progress-shared-only-by-opt-in.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/cloud/START-HERE.md", @@ -2874,7 +2874,7 @@ { "path": "docs/decisions/2026-09-26-lapsed-review-date-blocks-only-its-own-edit.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/search-rag-phase-5-source-review-ux.md", @@ -2909,12 +2909,12 @@ { "path": "docs/decisions/2026-08-17-document-summary-rows-get-their-own-provenance.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-17-pr-description-checks-are-advisory.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/DOCS-SYSTEM.md", @@ -2939,7 +2939,7 @@ { "path": "docs/agents/shared-context-and-memory.md", "section": "agents", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/local/plans/2026-08-20-rag-australian-source-governance.md", @@ -2954,7 +2954,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/PRODUCTION_DEPLOYMENT_GUIDE.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/evidence/rag-irrelevant-at-10-disposition.md", @@ -3034,7 +3034,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/MASTER_ISSUE_TRACKER.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/reconciliation-playbook.md", @@ -3069,7 +3069,7 @@ { "path": "docs/decisions/2026-09-25-document-results-show-verdict-words.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/2026-09-16-registry-search-outage.md", @@ -3104,7 +3104,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/COMPLETE_DOCUMENTATION_INDEX.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-08-21-developer-hub-phase-1-WORKLOG.md", @@ -3139,7 +3139,7 @@ { "path": "docs/decisions/2026-09-18-specifier-sign-off-rules.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/search-rag-phase-2-answer-plan.md", @@ -3154,7 +3154,7 @@ { "path": "docs/superpowers/plans/2026-09-27-first-nations-mode-completion.md", "section": "superpowers", - "catalogued": false + "catalogued": true }, { "path": "docs/launch-operator-runbook.md", @@ -3189,12 +3189,12 @@ { "path": "docs/decisions/2026-08-17-rag-programme-routing-before-length.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-25-strong-support-label-needs-every-claim.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/local/plans/2026-08-20-rag-verified-incremental-delivery.md", @@ -3214,7 +3214,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/FINAL_ASSESSMENT.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/privacy-impact-assessment.md", @@ -3244,7 +3244,7 @@ { "path": "docs/decisions/2026-09-25-leave-the-app-update-notice.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/specs/2026-09-30-roster-team-calendar-and-swaps-design.md", @@ -3259,7 +3259,7 @@ { "path": "docs/decisions/2026-09-04-on-call-design-choices.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/prompts/codex-tests-quality-gates-ultra-review.md", @@ -3269,7 +3269,7 @@ { "path": "docs/decisions/2026-08-18-keep-live-search-memory-settings.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/reports/task-6-brief.md", @@ -3279,7 +3279,7 @@ { "path": "docs/decisions/2026-08-22-automated-review-coverage.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/brand/design-handover.md", @@ -3299,7 +3299,7 @@ { "path": "docs/decisions/2026-09-26-last-updated-date-model.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/reports/task-5-brief.md", @@ -3319,7 +3319,7 @@ { "path": "docs/decisions/2026-09-25-no-identifiable-patient-information.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/observability-slos.md", @@ -3349,12 +3349,12 @@ { "path": "docs/decisions/2026-09-17-split-quick-and-full-local-checks.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-08-25-answer-page-direction-a.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/specs/2026-08-05-editable-pin-menu-mockups-design.md", @@ -3364,7 +3364,7 @@ { "path": "docs/decisions/2026-08-19-docling-shadow-cohort-starts-at-2-percent.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/reports/task-11-report.md", @@ -3394,7 +3394,7 @@ { "path": "docs/decisions/2026-09-16-squash-is-the-preferred-merge-method.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/no-unchecked-indexed-access-migration-plan.md", @@ -3469,7 +3469,7 @@ { "path": "docs/decisions/2026-09-01-overdue-sources-inside-evidence-gaps.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/reports/task-6-report.md", @@ -3504,7 +3504,7 @@ { "path": "docs/decisions/2026-09-25-safety-chip-urgent-words-and-drug-passages.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/repo-wide-review-remediation-plan-2026-07-23.md", @@ -3549,7 +3549,7 @@ { "path": "docs/decisions/2026-09-17-disperse-source-acquisition-records.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/rag-improvement/baseline-record.md", @@ -3604,7 +3604,7 @@ { "path": "docs/decisions/2026-08-26-prototypes-are-standalone-sandboxes.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/accessibility-acceptance.md", @@ -3619,7 +3619,7 @@ { "path": "docs/decisions/2026-09-25-clinical-eval-battery-additions.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/outstanding-issues.md", @@ -3639,7 +3639,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/ADDITIONAL_RECOMMENDATIONS.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/prompts/mode-aware-clinical-ask-codex-cloud-handover.md", @@ -3654,7 +3654,7 @@ { "path": "docs/decisions/2026-08-26-hazard-register-in-developer-hub.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/reports/task-3-brief.md", @@ -3699,7 +3699,7 @@ { "path": "docs/decisions/2026-08-21-care-plan-memory-only-with-storage-seam.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/search-rag-phase-3-synthesis-output.md", @@ -3739,7 +3739,7 @@ { "path": "docs/decisions/2026-09-03-source-only-pill-folded-into-limitations.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/reindex-shadow-harness-design.md", @@ -3754,7 +3754,7 @@ { "path": "docs/decisions/2026-09-25-name-instruments-never-score-them.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/pwa.md", @@ -3774,7 +3774,7 @@ { "path": "docs/decisions/2026-09-03-safety-findings-below-the-prose.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/agents/native-startup/external-skill-precedence.md", @@ -3814,17 +3814,17 @@ { "path": "docs/evidence/pr-3143-owner-signoff-confirmation.md", "section": "evidence", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/2026-10-agent-code-reviews/EXTENDED_ISSUE_INVENTORY.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-08-27-sidebar-documents-points-at-shared-home.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/rag-improvement/data-flow-register.md", @@ -3854,22 +3854,22 @@ { "path": "docs/decisions/2026-09-25-reindex-approved-after-worker-check.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-16-on-call-overdue-entries-in-developer-hub.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-08-21-developer-hub-first-design.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-08-07-weak-evidence-banner-only-when-it-adds.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/agents/repository-skills-and-issues.md", @@ -3904,7 +3904,7 @@ { "path": "docs/decisions/2026-09-26-family-violence-helpline-leads.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/canonical/connected-execution.md", @@ -3919,12 +3919,12 @@ { "path": "docs/decisions/2026-09-26-keep-uploaded-local-retrieval-fail-closed.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-09-26-first-nations-mode.md", "section": "superpowers", - "catalogued": false + "catalogued": true }, { "path": "docs/evidence/performance-remediation-2026-08-23.md", @@ -3939,12 +3939,12 @@ { "path": "docs/decisions/2026-09-23-cme-year-close-snapshot.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-25-retire-answer-support-card.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/cloud/plans/2026-08-21-trusted-admin-document-ingestion.md", @@ -3959,7 +3959,7 @@ { "path": "docs/decisions/2026-09-17-clinical-risk-covers-database-clients.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/agents-guide.md", @@ -3979,7 +3979,7 @@ { "path": "docs/decisions/2026-09-16-differentials-sources-stay-held.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/db-maintenance.md", @@ -4034,7 +4034,7 @@ { "path": "docs/evidence/mha-timeframes-owner-attribution.md", "section": "evidence", - "catalogued": false + "catalogued": true }, { "path": "docs/codebase-index.md", @@ -4074,17 +4074,17 @@ { "path": "docs/decisions/2026-09-26-doppler-is-not-used.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/2026-10-agent-code-reviews/POST_FIX_CHECKLIST.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-08-28-logo-tail-tips-clean-cut.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/rag-behaviour/behaviour-map.md", @@ -4099,7 +4099,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/CODE_REVIEW_SUMMARY.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/redesign/03-decision-log.md", @@ -4129,7 +4129,7 @@ { "path": "docs/decisions/2026-09-19-escalation-and-monitoring-chip-words.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-09-27-on-call-completion.md", @@ -4149,7 +4149,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/VERIFICATION_REQUIRED.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/brand/psychsift-logo.md", @@ -4194,7 +4194,7 @@ { "path": "docs/mockup-audit-and-issues-report.md", "section": "root", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/HANDOFF-START-HERE.md", @@ -4209,7 +4209,7 @@ { "path": "docs/decisions/2026-08-24-answer-tables-fold-into-drawer.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/adr/0001-use-a-shared-local-first-clinical-ask-orchestrator.md", @@ -4219,12 +4219,12 @@ { "path": "docs/decisions/2026-08-21-clinical-ask-shared-local-first-orchestrator.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-17-remove-switched-off-automations.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-09-27-roster-mode-plan-a-database.md", @@ -4249,7 +4249,7 @@ { "path": "docs/decisions/2026-09-25-record-sign-off-questions.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/current-clinical-work-brief.md", @@ -4284,7 +4284,7 @@ { "path": "docs/decisions/2026-08-09-visual-baseline-off-pull-requests.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/rag-improvement/COORDINATION.md", @@ -4304,7 +4304,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/READY_TO_DEPLOY.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/canonical/approval-matrix.md", @@ -4339,7 +4339,7 @@ { "path": "docs/decisions/2026-10-05-alerts-agreed-decisions.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/redesign/crisp-white-colour-system-plan.md", @@ -4354,7 +4354,7 @@ { "path": "docs/decisions/2026-09-16-arm-auto-merge-when-opening-a-pr.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/audit-remediation-plan-2026-07-14.md", @@ -4364,7 +4364,7 @@ { "path": "docs/investigations/firefox-click-state-failures.md", "section": "investigations", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/rag-scalability-wip-remediation-2026-07-17.md", @@ -4399,12 +4399,12 @@ { "path": "docs/archive/2026-10-agent-code-reviews/QUICK_REFERENCE.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/specs/2026-09-26-first-nations-mode-design.md", "section": "superpowers", - "catalogued": false + "catalogued": true }, { "path": "docs/phone-chrome-physical-acceptance.md", @@ -4434,7 +4434,7 @@ { "path": "docs/decisions/2026-07-30-phone-chrome-device-acceptance-not-pursued.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/redesign/07-token-adoption-audit.md", @@ -4444,7 +4444,7 @@ { "path": "docs/live-browser-testing.md", "section": "root", - "catalogued": false + "catalogued": true }, { "path": "docs/redesign/09-page-polish-plan.md", @@ -4459,7 +4459,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/COMPLETE_ISSUE_INVENTORY.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/plans/document-viewer-phase2-unified-chrome.md", @@ -4484,7 +4484,7 @@ { "path": "docs/decisions/2026-09-25-source-tier-order-confirmed.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/operator-apply-july8-batch.md", @@ -4509,7 +4509,7 @@ { "path": "docs/decisions/2026-08-25-answer-provenance-line.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-09-27-roster-mode-build-brief.md", @@ -4519,7 +4519,7 @@ { "path": "docs/decisions/2026-09-26-register-wa-service-issuers.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/operator-decisions-2026-07-04.md", @@ -4569,7 +4569,7 @@ { "path": "docs/decisions/2026-09-25-railway-waits-for-ci-once-safe.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/dictionary-editorial-drafts.md", @@ -4579,7 +4579,7 @@ { "path": "docs/decisions/2026-09-25-rkpg-clozapine-guideline-handling.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/design-system/GATES.md", @@ -4589,12 +4589,12 @@ { "path": "docs/decisions/2026-09-13-on-call-section-header-row.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-20-cme-no-guided-reflection.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/prompts/rag-coverage-gate-extraction.md", @@ -4609,7 +4609,7 @@ { "path": "docs/decisions/2026-10-04-mha-countdowns-covered-by-samd-ruling.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/design-system/sweep-fix-missing-values.md", @@ -4654,7 +4654,7 @@ { "path": "docs/decisions/2026-09-26-leave-extended-rag-telemetry-off.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/wiring-conventions.md", @@ -4684,7 +4684,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/FINAL_VERDICT.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/local/sdd-execution.md", @@ -4714,7 +4714,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/IMPLEMENTATION_COMPLETE.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/deploy-corrector-public-titles.md", @@ -4769,7 +4769,7 @@ { "path": "docs/decisions/2026-09-26-organisation-check-warns-on-moves.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/primary-checkout-reconciliation-2026-07-24.md", @@ -4789,12 +4789,12 @@ { "path": "docs/decisions/2026-08-24-answer-citation-marks-one-colour.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/2026-10-agent-code-reviews/ABSOLUTE_FINAL_STATUS.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/site-map.md", @@ -4814,17 +4814,17 @@ { "path": "docs/decisions/2026-08-24-compact-citations-kept-for-the-rail.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-09-27-roster-mode-plan-d-release-3.md", "section": "superpowers", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-08-31-governed-caution-below-the-prose.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/performance-image-cwv-audit-2026-08-02.md", @@ -4859,7 +4859,7 @@ { "path": "docs/decisions/2026-08-25-unsupported-claims-carry-no-mark.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/audit/gate-consolidation-audit-2026-09-02.md", @@ -4879,7 +4879,7 @@ { "path": "docs/decisions/2026-08-27-favourites-phone-keeps-both-cards.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/rag-behaviour/refuted-approaches.md", @@ -4909,7 +4909,7 @@ { "path": "docs/decisions/2026-09-25-offline-pocket-pack.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/cloud/plans/2026-08-20-rag-adaptive-answer.md", @@ -4944,7 +4944,7 @@ { "path": "docs/decisions/2026-09-13-mode-identity-colours.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/archive/clinical-chat-ui-phase-checklist.md", @@ -4959,7 +4959,7 @@ { "path": "docs/decisions/2026-08-25-care-plan-records-when-patient-part-recorded.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/rag-upgrade/cloud/connected-execution.md", @@ -4984,7 +4984,7 @@ { "path": "docs/decisions/2026-08-25-care-plan-shorter-confidential-footer.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/openai-rag-operations.md", @@ -5014,12 +5014,12 @@ { "path": "docs/decisions/2026-08-23-two-favourites-surfaces.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-25-tablet-cross-mode-search-is-intended.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/reports/task-4-brief.md", @@ -5044,7 +5044,7 @@ { "path": "docs/decisions/2026-08-25-care-plan-no-false-joint-authorship.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/staging-tenancy-release-evidence.md", @@ -5079,12 +5079,12 @@ { "path": "docs/decisions/2026-08-18-gate-b-table-target-is-parity.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-25-calculator-governance-reference-not-linked.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-09-27-roster-mode-db-agreement.md", @@ -5094,7 +5094,7 @@ { "path": "docs/decisions/2026-08-22-accept-24-hour-recovery-point.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-08-20-rag-retrieval-composition.md", @@ -5109,17 +5109,17 @@ { "path": "docs/decisions/2026-09-03-evidence-preview-excludes-per-document.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/projects/design-system-remediation.md", "section": "projects", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-25-differential-badges-name-what-they-count.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/care-plan/sdd-ledger.md", @@ -5139,7 +5139,7 @@ { "path": "docs/decisions/2026-08-24-clinical-notes-sheet-removed.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/README.md", @@ -5154,7 +5154,7 @@ { "path": "docs/decisions/2026-09-17-differential-code-is-clinical-risk.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/design-system/sweep-fix-duration-display.md", @@ -5174,7 +5174,7 @@ { "path": "docs/audit/psychsift-ux-behavioral-audit-report-2026-10.md", "section": "audit", - "catalogued": false + "catalogued": true }, { "path": "docs/superpowers/plans/2026-08-23-lighthouse-local-build-reliability.md", @@ -5199,7 +5199,7 @@ { "path": "docs/decisions/2026-09-16-review-records-move-to-pr-comments.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/clinical-sign-off-how-to.md", @@ -5214,7 +5214,7 @@ { "path": "docs/decisions/2026-08-22-developer-hub-review-state-panel.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/source-acquisition-protocol.md", @@ -5224,12 +5224,12 @@ { "path": "docs/decisions/2026-08-29-missing-values-two-new-phrases.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/decisions/2026-09-12-mode-pill-opens-the-modes-pages-first.md", "section": "decisions", - "catalogued": false + "catalogued": true }, { "path": "docs/framework-dependency-modernization-checklist.md", @@ -5239,7 +5239,7 @@ { "path": "docs/archive/2026-10-agent-code-reviews/DOCKERFILE_OPTIMIZATIONS.md", "section": "archive", - "catalogued": false + "catalogued": true }, { "path": "docs/codex/tests-quality-gates/README.md", @@ -5249,7 +5249,7 @@ { "path": "docs/decisions/2026-08-18-plain-brief-replies.md", "section": "decisions", - "catalogued": false + "catalogued": true } ], "sections": [ @@ -17792,6 +17792,14 @@ "outcome": "No actionable findings in targeted review; live baseline pending", "checks": "50 focused tests and 630 offline RAG tests passed; typecheck passed; production readiness blocked by six existing governance approvals" }, + { + "date": "2026-10-13", + "ref": "codex/pr3509-preserved-source-guard-20261013", + "head": "919129dccf843ca676e0d79072ad2e395d80c610", + "scope": "PR3509 final guard snapshot acceptance", + "outcome": "Independent exact-head static acceptance: both strict-mode findings resolved; no remaining concrete guard blocker", + "checks": "Complete-scope independent review against 3e359e90953218918373010f4c9f37a8e2fd6723; normal format and typecheck passed; final focused suites 74 passed; subsequent push blocked by unused test binding, fixed in following test-only correction" + }, { "date": "2026-08-07", "ref": "cursor/site-testing-speed-08c1", @@ -25240,6 +25248,14 @@ "outcome": "P1 fixed locally: stale Chrome 150 baseline, unbounded runner phases, and live input/process limits hardened; advisory policy retained", "checks": "offline review; check:ci-scope PASS; test:ci-workflows 13 files 248 passed 11 skipped; check:github-actions PASS; verify:lighthouse dry-run PASS; no provider-backed checks run" }, + { + "date": "2026-10-13", + "ref": "codex/pr3509-preserved-source-guard-20261013", + "head": "edae591bf41f45643f34f739bfb4e1be2bfd759a", + "scope": "PR3509 preserved-source admission guard", + "outcome": "Blocked: independent review found missing-object admission and latest-commit masking gaps in strict mode", + "checks": "Read-only independent review against 3e359e90953218918373010f4c9f37a8e2fd6723; no reviewer tests or API calls; normal regression verification owned by implementation task" + }, { "date": "2026-07-22", "ref": "PR #1087 / `codex/reconcile-product-truth`", diff --git a/docs/DOCS-SYSTEM.md b/docs/DOCS-SYSTEM.md index 30d56effb4..d50375bf41 100644 --- a/docs/DOCS-SYSTEM.md +++ b/docs/DOCS-SYSTEM.md @@ -2,7 +2,15 @@ How Documentation keeps project docs accurate, logged, and non-stale across Joshua’s repos. **Process doc — no product DDL.** -_Owned by Documentation. Updated 2026-10-08 — clarified checkpoint, memory and communication authority; Documentation owns._ +_Owned by Documentation. Updated 2026-10-14 — added automated documentation and file-organisation maintenance pipeline (`npm run docs:maintain`, `npm run docs:maintain:check`, `node scripts/maintain-docs-system.mjs --classify `); Documentation owns._ + +## Automated Maintenance Pipeline + +All documentation edits and new files in `BigSimmo/PsychSift` are governed by the deterministic documentation and file-organisation pipeline (`scripts/maintain-docs-system.mjs` and `docs/organisation/`): + +- `npm run docs:maintain` (`node scripts/maintain-docs-system.mjs`) — runs `scripts/check-organisation.mjs`, auto-places any unplaced files into the matching `docs/organisation/systems/.json` manifest, regenerates `docs/README.md` (`generate-docs-index.mjs`), system diagrams (`generate-system-diagrams.mjs`), and the clinical hazard snapshot (`generate-hazard-register-snapshot.mjs`), refreshes reviewed commit pins in `docs/organisation/pins.json`, and re-verifies `check-organisation.mjs` (`unplaced === 0`) and `check-doc-governance.mjs`. +- `npm run docs:maintain:check` (`node scripts/maintain-docs-system.mjs --check`) — read-only verification gate running `check-organisation.mjs` (requiring `0` unplaced files), `generate-docs-index.mjs --check`, `generate-system-diagrams.mjs --check`, `check-doc-governance.mjs`, and `check-clinical-hazard-controls.mjs`. +- `node scripts/maintain-docs-system.mjs --classify ` — deterministically classifies one or more repository-relative paths into their target `docs/organisation/systems/.json` manifest and prints the JSON classification without modifying files. ## Principles diff --git a/docs/README.md b/docs/README.md index 231aa3140d..57d012183b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -87,7 +87,6 @@ repository gate. The generated inventories remain governed by their own contract - [design-system/ADOPTION.md](design-system/ADOPTION.md) — PR 13 registration record: adoption order, per-surface file allowlists, exclusions, pins, proof shots - [dictionary-editorial-drafts.md](dictionary-editorial-drafts.md) — the unpublished Dictionary draft layer: sense-first abbreviation drafts, hash-reconciled definition reviews, per-source acquisition outcomes, and what a register candidate is and is not - [comparison-behaviour.md](comparison-behaviour.md) — shared selection, state, responsive, and accessibility contract for comparison surfaces -- [clinical-chat-ui-component-map.md](clinical-chat-ui-component-map.md) — chat UI component inventory - [clinical-badge-system-guide.md](clinical-badge-system-guide.md) — clinical badge semantics - [multi-user-auth-setup.md](multi-user-auth-setup.md) — auth, sessions, owner scoping - [pwa.md](pwa.md) — PWA install assets, privacy-first service worker, offline shell @@ -217,6 +216,7 @@ Every remaining tracked document in this category, one line each; the descriptio - [process-hardening.md](process-hardening.md) — verification gates, CI expectations, known debts - [continuous-integration.md](continuous-integration.md) — workflow concurrency keys, push exemption, and Guard 2 in-flight CI push guard - [testing.md](testing.md) — test execution, focused/live commands, Playwright ownership, flake policy +- [live-browser-testing.md](live-browser-testing.md) — live browser testing architecture and operating guide - [development-speed-playbook.md](development-speed-playbook.md) — going faster without weakening any gate: receipts, narrow selection, worktree reuse - [phone-chrome-physical-acceptance.md](phone-chrome-physical-acceptance.md) — labelled Safari and cold-launch PWA acceptance matrix - [productivity-workflows.md](productivity-workflows.md) — repo workflow planners (flightplan, triage, rag-lab, …) @@ -249,6 +249,7 @@ Every remaining tracked document in this category (process, plus the `agents/` r - [agents/external-skill-precedence.md](agents/external-skill-precedence.md) — External Skill Precedence and Evidence — User-global skills and output-style plugins are installed outside this repo and know nothing about its contracts. - [agents/pull-request-workflow.md](agents/pull-request-workflow.md) — Pull Request Workflow — The one canonical pull-request rulebook for every AI tool: open, follow CI, review threads, records, merge authority, landed, branch sync, Run PR, Clear PRs, bundling. - [agents/repository-skills-and-issues.md](agents/repository-skills-and-issues.md) — Repository Skills and Outstanding-Work Memory — Select repo-local skills under `.agents/skills/` when their descriptions match the actual task and their use materially helps; read an explicitly named skill before acting. +- [agents/shared-context-and-memory.md](agents/shared-context-and-memory.md) — Context, adaptive agents and memory across local and cloud sessions — Read this reference when a task needs continuity, delegation, memory or a change of execution host. - [agents/test-deletion-guard.md](agents/test-deletion-guard.md) — Deleting tests, or letting a tool delete them for you — On 2026-08-31 a commit on PR #2481 titled "test(ui): - [agents/smart-agent-allocation.md](agents/smart-agent-allocation.md) — Default model/effort selection, independent ownership and review, evidence reuse, and portable Codex Cloud delivery. - [agents/task-efficiency.md](agents/task-efficiency.md) - On-demand task brief, one continuation record and private measurement using existing workflows. @@ -262,7 +263,7 @@ Every remaining tracked document in this category (process, plus the `agents/` r - [agents/native-startup/publication-workflows.md](agents/native-startup/publication-workflows.md) — Safe Git publication workflows, PR shortcuts, and anti-churn sync - [agents/native-startup/search-chrome-behaviour.md](agents/native-startup/search-chrome-behaviour.md) — Search chrome behaviour, composer ownership, and phone edge-to-edge contracts - [prompts/codex-architecture-maintainability-ultra-review.md](prompts/codex-architecture-maintainability-ultra-review.md) — Codex Local Ultra — Architecture & Maintainability Review Orchestrator — Perform a rigorous, evidence-based Architecture and Maintainability review of this repository using multi-agent coordination. -- [prompts/codex-cloud-design-status-semantics.md](prompts/codex-cloud-design-status-semantics.md) — Codex Cloud prompt — design-system clinical status semantics — Copy the complete prompt below into a new Codex Cloud task for the Database repository KB repository. +- [prompts/codex-cloud-design-status-semantics.md](prompts/codex-cloud-design-status-semantics.md) — Codex Cloud prompt — design-system clinical status semantics — Copy the complete prompt below into a new Codex Cloud task for the PsychSift (`BigSimmo/PsychSift`) repository. - [prompts/codex-cloud-detailed-task.md](prompts/codex-cloud-detailed-task.md) — Codex Cloud detailed-task prompt — Use this prompt when assigning a substantial implementation, refactor, defect fix, or other detailed task to Codex Cloud in this repository. - [prompts/codex-cloud-review/1-codex-full-stack-master-review-prompt.md](prompts/codex-cloud-review/1-codex-full-stack-master-review-prompt.md) — Codex Comprehensive Full-Stack Product, Design, Architecture, Engineering, Security, Quality and Refactoring Master Prompt — Keep this master specification as a normal Markdown file, for example: - [prompts/codex-cloud-review/2-codex-full-stack-master-prompt-review-and-stress-test.md](prompts/codex-cloud-review/2-codex-full-stack-master-prompt-review-and-stress-test.md) — Review and Adversarial Stress Test of the Codex Full-Stack Master Prompt — The original Cursor prompt had unusually strong domain coverage and quality controls. @@ -280,22 +281,15 @@ Every remaining tracked document in this category (process, plus the `agents/` r - [codex/functional-correctness/README.md](codex/functional-correctness/README.md) — Functional correctness review packets — Durable artifacts requested from the functional correctness review prompt belong here. - [codex/performance-reliability/README.md](codex/performance-reliability/README.md) — Performance and reliability review packets — Durable artifacts requested from the performance and reliability review prompt belong here. - [codex/tests-quality-gates/README.md](codex/tests-quality-gates/README.md) — Tests and quality-gates review packets — Durable artifacts requested from the tests and quality-gates review prompt belong here. -- [plans/design-system-live-convergence-plan.md](plans/design-system-live-convergence-plan.md) — Design-system live convergence programme — Status: execution-ready plan… -- [plans/document-viewer-phase2-unified-chrome.md](plans/document-viewer-phase2-unified-chrome.md) — Phase 2 — Unified viewing chrome (PDF + photo) — Status: plan only (no product behaviour change in this doc PR) Programme: -- [plans/document-viewer-phase3-handover.md](plans/document-viewer-phase3-handover.md) — Document viewer — Phase 3 handover — Execution brief for Phase 3 of docs/plans/document-viewer-redesign-plan.md. - [plans/document-viewer-redesign-plan.md](plans/document-viewer-redesign-plan.md) — Document viewer redesign — PDF + photo surfaces — Status: programme plan (Phases 0–3 landed; - [plans/edge-ingestion-overhaul-3pr-plan.md](plans/edge-ingestion-overhaul-3pr-plan.md) — Edge Ingestion Overhaul — 3-PR Execution Plan — Status: Planning only. - [plans/tooling-activation-implementation-plan.md](plans/tooling-activation-implementation-plan.md) — Tooling activation — implementation plan — Status: local workstreams (WS-B, WS-C) implemented 2026-08-01; ## Plans and workstreams (living) -- [mode-aware-clinical-ask-local-handover.md](mode-aware-clinical-ask-local-handover.md) — three-phase local integration, approval-gated staging/governance, and PR publication handover for Mode-aware Clinical Ask -- [answer-page-redesign-handover.md](answer-page-redesign-handover.md) — build-and-merge handover for the chosen answer-page design: what claim-level citation data already exists, the three-PR order it forces, the design contract, and the gates and PR-body requirements that block the merge - [maturity-backlog-workorders.md](maturity-backlog-workorders.md) — actionable work orders tracking the repository-maturity audit backlog - [no-unchecked-indexed-access-migration-plan.md](no-unchecked-indexed-access-migration-plan.md) — staged multi-PR rollout for the `noUncheckedIndexedAccess` TypeScript flag (ledger `#211`) -- [ledger-id-scheme-proposal.md](ledger-id-scheme-proposal.md) — design for collision-free outstanding-issue ids so concurrent sessions stop contending on `issues:next-id` (ledger `#168`) - [pr-handoff-stop-cross-agent-gap.md](pr-handoff-stop-cross-agent-gap.md) — why the PR-babysit budget is hook-enforced for Claude Code but prose-only for Codex and Cursor, and what parity would require (ledger `#258`) -- [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-improvement/README.md](rag-improvement/README.md) — reviewed/updated RAG improvement programme: answer-quality track (intent-aware related information, length) + corrected eval/safety infra track - [rag-improvement/HANDOVER.md](rag-improvement/HANDOVER.md) — multi-session handover: per-session work packets, status table, checklists, and paste-ready prompts for executing the programme @@ -306,6 +300,7 @@ Every remaining tracked document in this category (process, plus the `agents/` r - [rag-hybrid-findings-and-todo.md](rag-hybrid-findings-and-todo.md) — hybrid retrieval findings backlog - [reindex-shadow-harness-design.md](reindex-shadow-harness-design.md) — designed-only shadow reindex harness (driver not built) - [ingestion-concurrency-fix-workorder.md](ingestion-concurrency-fix-workorder.md) — ingestion concurrency workorder +- [projects/design-system-remediation.md](projects/design-system-remediation.md) — PsychSift design system, screen, accessibility, responsive & interaction remediation project plan - [redesign/](redesign/) — premium redesign plans, decision log, token adoption - [superpowers/](superpowers/) — agent-authored plans and specs - **Care Plan (prototype, developer-gated under `/mockups/care-plan`)** — [superpowers/specs/2026-08-20-care-plan-design.md](superpowers/specs/2026-08-20-care-plan-design.md) is the binding design spec, [care-plan-context.md](care-plan-context.md) the binding glossary, [superpowers/plans/2026-08-20-care-plan-implementation.md](superpowers/plans/2026-08-20-care-plan-implementation.md) the implementation plan, [care-plan/sdd-ledger.md](care-plan/sdd-ledger.md) the build ledger and [care-plan/complete-work-ledger.md](care-plan/complete-work-ledger.md) the record of what landed; the dated handoffs, transcripts and reports under [care-plan/](care-plan/) are point-in-time records @@ -333,6 +328,7 @@ Every remaining tracked document in this category, one line each; the descriptio - [superpowers/plans/2026-09-27-roster-mode-plan-a-database.md](superpowers/plans/2026-09-27-roster-mode-plan-a-database.md) — Roster mode plan A: the combined database change (PR #3117) - [superpowers/plans/2026-09-27-roster-mode-plan-b-release-1.md](superpowers/plans/2026-09-27-roster-mode-plan-b-release-1.md) — Roster mode plan B: Release 1, one doctor (PR #3118) - [superpowers/plans/2026-09-27-roster-mode-plan-c-release-2.md](superpowers/plans/2026-09-27-roster-mode-plan-c-release-2.md) — Roster mode plan C: Release 2, Roster for a health service (the plan to complete it) +- [superpowers/plans/2026-09-27-roster-mode-plan-d-release-3.md](superpowers/plans/2026-09-27-roster-mode-plan-d-release-3.md) — Roster maker: implementation plan (Release 3 preparation) - [superpowers/plans/2026-09-27-roster-mode-status.md](superpowers/plans/2026-09-27-roster-mode-status.md) — Roster mode: where the build stands and the plan to complete it - [superpowers/plans/2026-09-27-roster-mode-db-agreement.md](superpowers/plans/2026-09-27-roster-mode-db-agreement.md) — Roster mode: the Roster, On Call, Admin and Teaching agreement on the combined database change - [superpowers/plans/2026-09-27-roster-mode-build-brief.md](superpowers/plans/2026-09-27-roster-mode-build-brief.md) — Roster mode: the brief the build threads work from @@ -564,10 +560,34 @@ Every remaining tracked document in this category (dated records and the `eviden - [design-system/drift-measurement-2026-09-02.md](design-system/drift-measurement-2026-09-02.md) — Design-token drift measurement, 2026-09-02 - [design-system/sweep-fix-visible-live-regions.md](design-system/sweep-fix-visible-live-regions.md) — Sweep fix — visible live regions (closes finding 4 of the 2026-08-29 sweep) +### Also catalogued (2026-10-14) + +- [clinical-chat-ui-component-map.md](clinical-chat-ui-component-map.md) — Clinical chat UI component inventory (point-in-time architecture map) +- [mode-aware-clinical-ask-local-handover.md](mode-aware-clinical-ask-local-handover.md) — Three-phase local integration, approval-gated staging/governance, and PR publication handover for Mode-aware Clinical Ask (completed) +- [answer-page-redesign-handover.md](answer-page-redesign-handover.md) — Build-and-merge handover for the chosen answer-page design (completed) +- [ledger-id-scheme-proposal.md](ledger-id-scheme-proposal.md) — Design for collision-free outstanding-issue ids (`#168`, implemented via ULIDs) +- [framework-dependency-modernization-checklist.md](framework-dependency-modernization-checklist.md) — Ordered Next.js 16, runtime, dependency, Turbopack, and verification migration program (completed) +- [plans/design-system-live-convergence-plan.md](plans/design-system-live-convergence-plan.md) — Design-system live convergence programme (completed plan) +- [plans/document-viewer-phase2-unified-chrome.md](plans/document-viewer-phase2-unified-chrome.md) — Phase 2 — Unified viewing chrome (PDF + photo) plan (completed) +- [plans/document-viewer-phase3-handover.md](plans/document-viewer-phase3-handover.md) — Document viewer — Phase 3 handover (completed) +- [audit/codescene-non-rag-remediation-2026-10-09.md](audit/codescene-non-rag-remediation-2026-10-09.md) — CodeScene maintainability remediation: non-RAG phase (2026-10-09) +- [audit/full-repository-adversarial-audit-2026-10-09.md](audit/full-repository-adversarial-audit-2026-10-09.md) — Comprehensive repository-wide adversarial audit & reconciliation report (2026-10-09) +- [audit/psychsift-ux-behavioral-audit-report-2026-10.md](audit/psychsift-ux-behavioral-audit-report-2026-10.md) — PsychSift comprehensive app behavior, UX & clinical ergonomics audit report (2026-10) +- [evidence/mha-timeframes-owner-attribution.md](evidence/mha-timeframes-owner-attribution.md) — Mental Health Act timeframes: owner's attribution confirmed (2026-10-03) +- [evidence/pr-3143-owner-signoff-confirmation.md](evidence/pr-3143-owner-signoff-confirmation.md) — PR #3143: clinical owner's sign-off confirmation (2026-10-02) +- [investigations/firefox-click-state-failures.md](investigations/firefox-click-state-failures.md) — Firefox (Gecko) click state failures in Playwright (#33346A) +- [mockup-audit-and-issues-report.md](mockup-audit-and-issues-report.md) — Comprehensive mockup audit & issues report (2026-10-09) +- [superpowers/plans/2026-09-26-cpd-elevation.md](superpowers/plans/2026-09-26-cpd-elevation.md) — CPD mode elevation implementation plan (2026-09-26) +- [superpowers/plans/2026-09-26-first-nations-mode.md](superpowers/plans/2026-09-26-first-nations-mode.md) — First Nations mode implementation plan (shipped 2026-09-26, PR #3116) +- [superpowers/plans/2026-09-27-first-nations-mode-completion.md](superpowers/plans/2026-09-27-first-nations-mode-completion.md) — First Nations mode completion checkpoint (2026-09-27) +- [superpowers/specs/2026-09-26-cpd-elevation-design.md](superpowers/specs/2026-09-26-cpd-elevation-design.md) — CPD mode elevation design spec (2026-09-26) +- [superpowers/specs/2026-09-26-first-nations-mode-design.md](superpowers/specs/2026-09-26-first-nations-mode-design.md) — First Nations mode design spec (2026-09-26) +- [archive/2026-10-agent-code-reviews/](archive/2026-10-agent-code-reviews/) — Archived October 2026 point-in-time agent code reviews retained for audit history + ## Archive - [archive/](archive/) — completed phase plans, superseded designs, and old - progress logs kept for provenance. Never treat archive content as current + progress logs kept for provenance (including [archive/2026-10-agent-code-reviews/](archive/2026-10-agent-code-reviews/)). Never treat archive content as current guidance. ## Maintenance rules diff --git a/docs/agents/bug-hunter-shortcut.md b/docs/agents/bug-hunter-shortcut.md index bf37c4a304..6d7b09511d 100644 --- a/docs/agents/bug-hunter-shortcut.md +++ b/docs/agents/bug-hunter-shortcut.md @@ -8,7 +8,7 @@ When the user types exactly `bug-hunter` as the entire task message, after trimm Execution rules: -- Invoke the `bug-hunter` skill first. +- Invoke the `audit` skill (`.agents/skills/audit/SKILL.md`) first. - Prioritize reproducible defects over code style, naming, or formatting feedback. - Trace realistic failure paths: invalid input, empty states, retries, race/concurrency issues, stale state/cache, network/auth failures, permissions, and boundary values. - For each finding, include trigger, expected behavior, actual risk, and the smallest proof (or targeted test/check) that would catch it. diff --git a/docs/agents/codex-review-throttling.md b/docs/agents/codex-review-throttling.md index f54a982206..a0ec2eeefe 100644 --- a/docs/agents/codex-review-throttling.md +++ b/docs/agents/codex-review-throttling.md @@ -24,12 +24,11 @@ Before reviewing multiple branches: Review routing: -- `diff-review`: Use for explicit review of the current diff, PR, or named branch. Findings first, ordered by severity, with file/line evidence. -- `bug-hunter`: Use only for the exact `bug-hunter` shortcut or an explicit defect-hunt request. Prioritize reproducible bugs and smallest proof. -- `repo-auditor`: Use for explicit repo-wide audit/refactor/dead-code/import/dependency-structure requests. Treat outputs as triage, not automatic delete lists. -- `release-readiness`: Use for explicit release, merge, PR readiness, or handoff confidence requests. Do not run provider-backed gates without confirmation. -- `branch-cleanup`: Use only when the prompt explicitly asks for branch cleanup/hygiene or branch deletion candidates. Apply `docs/branch-cleanup-guide.md` and the review ledger before inspecting branch diffs. -- `pr-ci-fix`: Confirmation-required for this repo. GitHub/GitLab API calls, PR comments, CI reruns, commits, and pushes require explicit user approval and must respect the upload/handoff rules. Exception: an explicit `Run PR` sweep carries this approval (see "## Run PR shortcut"). +- `review` (legacy `diff-review`): Use for explicit review of the current diff, PR, or named branch. Findings first, ordered by severity, with file/line evidence. +- `audit` (legacy `bug-hunter` / `repo-auditor`): Use for the exact `bug-hunter` shortcut, explicit defect-hunt requests (prioritizing reproducible bugs and smallest proof), or repo-wide audit/refactor/dead-code/import/dependency-structure requests (treating outputs as triage, not automatic delete lists). +- `release` (legacy `release-readiness`): Use for explicit release, merge, PR readiness, or handoff confidence requests. Do not run provider-backed gates without confirmation. +- `prlanded` / `task` (legacy `branch-cleanup`): Use only when the prompt explicitly asks for branch cleanup/hygiene or branch deletion candidates. Apply `docs/branch-cleanup-guide.md` and the review ledger before inspecting branch diffs. +- `fix` (legacy `pr-ci-fix`): Use for local verification failures; GitHub/GitLab API calls, PR comments, CI reruns, commits, and pushes remain confirmation-required for this repo and must respect the upload/handoff rules. Exception: an explicit `Run PR` sweep carries this approval (see "## Run PR shortcut"). When a branch or PR review completes, record it with `npm run ledger:append -- --ref --head --scope --outcome --checks `. It creates one content-addressed immutable record file, so concurrent reviews never edit a shared Markdown hunk. Never hand-write a record: hand-written rows produced the mojibake, wrong-width, and duplicate records that the 2026-07-28 hygiene pass had to repair, and `see PR head` or abbreviated HEADs make the throttle unreliable. The legacy Markdown table is frozen for normal PRs; append a correction or superseding record (`--supersede`) instead. `npm run check:branch-review-ledger` validates all sources, while `check:ledger-write-discipline` rejects a legacy-table row change before it becomes a GitHub conflict. diff --git a/docs/agents/cursor-cloud.md b/docs/agents/cursor-cloud.md index 7910c4c9ff..72b8f269b6 100644 --- a/docs/agents/cursor-cloud.md +++ b/docs/agents/cursor-cloud.md @@ -19,7 +19,7 @@ the repository's provider boundary applies to live mode and documentation provid - Live-mode caveat: `RAG_PROVIDER_MODE=auto` attempts OpenAI (fast → strong route); if generation fails the built-in quality gates it silently degrades to a deterministic "Source-only" answer that still cites real documents — this is expected, not a failure. Anonymous answer requests are supported for the public corpus; signed-in access is scoped to the caller. Check `src/lib/public-api-access.ts` and `src/lib/owner-scope.ts` for the access rules; a server-side endpoint does not grant access to private documents. - What still won't run in this VM even with secrets: `npm run worker` also needs the Python OCR stack (`worker/python/requirements.txt`) and heavy parsing deps; Supabase edge functions need Deno v2.x + deployment. `verify:release` additionally runs governance/eval gates. Treat missing-secret failures of `check:supabase-project`/`verify:release` in demo mode as expected, not regressions. - Dev server: `npm run dev` selects a stable per-project localhost port (e.g. `4461`), binds `0.0.0.0`, and prints the exact URL. Never assume port 3000/3001/3002. `npm run ensure` starts/verifies it in the background. -- Verification without secrets: `npm run lint`, `npm run typecheck`, and `npm run test` (vitest) are intended local checks; select the relevant tier and report the actual outcome rather than assuming a pass. `npm run verify:cheap` is the ordinary offline gate: `check:installed-lock-parity` + lint + typecheck + test — it does **not** run runtime, GitHub Actions pin, CI-scope, sitemap, or the other static hygiene gates (those live in `npm run verify:full` / CI `static-pr`; see `docs/agents/verification-gates.md`). `npm run verify:pr-local` selects checks by changed paths: recognised documentation scopes use focused static checks, while executable or unknown scopes include lint, typecheck and the full unit suite, plus applicable build/domain checks. Inspect uncertain scope with `npm run verify:pr-local -- --dry-run`; do not run `verify:cheap` first merely to repeat coverage. Browser, Docker/Supabase, audit, and provider checks remain separate. See `docs/testing.md` for lock, live-test, Playwright, and flake-ledger rules. If `check:installed-lock-parity` or `check:playwright-browser-revision` reports Playwright/image drift (`#255`), do not force a mismatched Chromium path — leave browser proof unverified until the appropriate authorised environment supplies it (see `docs/testing.md` § Testing speed playbook). +- Verification without secrets: `npm run lint`, `npm run typecheck`, and `npm run test` (vitest) are intended local checks; select the relevant tier and report the actual outcome rather than assuming a pass. `npm run verify:cheap` is the ordinary offline gate: `check:installed-lock-parity` + `check:diff-integrity` + lint + typecheck + test — it does **not** run runtime, GitHub Actions pin, CI-scope, sitemap, or the other static hygiene gates (those live in `npm run verify:full` / CI `static-pr`; see `docs/agents/verification-gates.md`). `npm run verify:pr-local` selects checks by changed paths: recognised documentation scopes use focused static checks, while executable or unknown scopes include lint, typecheck and the full unit suite, plus applicable build/domain checks. Inspect uncertain scope with `npm run verify:pr-local -- --dry-run`; do not run `verify:cheap` first merely to repeat coverage. Browser, Docker/Supabase, audit, and provider checks remain separate. See `docs/testing.md` for lock, live-test, Playwright, and flake-ledger rules. If `check:installed-lock-parity` or `check:playwright-browser-revision` reports Playwright/image drift (`#255`), do not force a mismatched Chromium path — leave browser proof unverified until the appropriate authorised environment supplies it (see `docs/testing.md` § Testing speed playbook). - For GitHub-related work authorised in this session, prefer the connected GitHub connector/MCP tools first for PR, issue, comment, review-thread, and Actions tasks they support (including run/job/log/artifact inspection and review-thread replies/resolution). A missing `gh` CLI is not a blocker for connector-supported work; never add a PAT as a workaround. The intended connection is `BigSimmo` with repository write access. Reserve administrator access for separately approved operations. Verify the exact target and connector result before any write. Ordinary authorised shell `git` branch publication remains allowed; use shell `gh` only for a genuine connector gap and only when the task permits it. diff --git a/docs/agents/external-skill-precedence.md b/docs/agents/external-skill-precedence.md index 6d5b3fdc59..4429986592 100644 --- a/docs/agents/external-skill-precedence.md +++ b/docs/agents/external-skill-precedence.md @@ -44,13 +44,16 @@ Output-style plugins such as caveman mode may compress prose. They must never co network/provider access requires explicit user confirmation per the "API and provider confirmation boundary" section. - **PR titles and descriptions are parsed input, not prose.** `.github/workflows/pr-policy.yml` - runs `scripts/pr-policy.mjs` against the exact PR title/body text. It hard-blocks the merge - when a clinical-risk diff lacks a complete `## Clinical Governance Preflight` (every item from - `requiredClinicalGovernanceItems` checked), and warns (advisory since 2026-09-17) when a - RAG-ranking-surface diff lacks a satisfying `RAG impact:` line (see "RAG ranking protection" in - AGENTS.md). Caveman-style fragment-dropping breaks + runs `scripts/pr-policy.mjs` against the exact PR title/body text. Missing or incomplete + `## Clinical Governance Preflight` checklists (every item from `requiredClinicalGovernanceItems` + checked on a clinical-risk diff) and missing or unsatisfied `RAG impact:` lines on a + RAG-ranking-surface diff emit **advisory warnings** in `pr-policy` (since 2026-09-17, + `docs/process-hardening.md`; no longer hard-blocking merges), while contributors and agents are + still instructed to include them in full on relevant PRs (see "RAG ranking protection" in + `AGENTS.md`). Caveman-style fragment-dropping breaks this exact-format contract — a paraphrased checklist item or a shortened `RAG impact:` reason can - silently fail `governanceItemSatisfied`/`ragImpactDeclared` even though the PR is otherwise fine. + silently fail `governanceItemSatisfied`/`ragImpactDeclared` and trigger avoidable policy warnings + even though the PR is otherwise fine. `gh pr create`/`gh pr edit` bodies and any `PR_POLICY_BODY.md` content therefore always get written in full normal prose from `.github/pull_request_template.md`, regardless of the active output style — this is "commits" territory under the caveman carve-out, not chat. Before diff --git a/docs/agents/pull-request-workflow.md b/docs/agents/pull-request-workflow.md index b3073eb68c..46c1290ef3 100644 --- a/docs/agents/pull-request-workflow.md +++ b/docs/agents/pull-request-workflow.md @@ -50,19 +50,22 @@ sufficient gate (`npm run verify:pr-local` by default — see body. Write it from `.github/pull_request_template.md` in full normal prose, with the exact `## Summary` / `## Verification` / `## Risk and rollout` headings, a satisfying `RAG impact:` line when a RAG-ranking surface is touched, and — when `classifyPullRequestFiles` reports -clinical risk — a complete `## Clinical Governance Preflight`. Output-style compression never -applies to PR titles and bodies. +clinical risk — a complete `## Clinical Governance Preflight`. (Since 2026-09-17, missing or +incomplete `## Clinical Governance Preflight` and `RAG impact:` declarations emit **advisory +warnings** in `pr-policy` rather than hard-blocking merges — see `docs/process-hardening.md` — +but contributors and agents should still include them on every applicable PR.) Output-style +compression never applies to PR titles and bodies. `npm run pr:areas` prints the `Areas touched:` line from the organisation map and, when a ranking-protected file changed, a `RAG impact:` placeholder to replace; include both in the body. - Complete the Preflight **truthfully**: check only the boxes that are actually true for this change. Never tick every box to satisfy the parser. - `governanceItemSatisfied` compares with exact string equality, so a checked line must - reproduce the template wording and nothing else. Appending a reason (for example `- [x] — because ...`) silently fails to match. Copy the seven lines verbatim and put reasoning in a paragraph + reproduce the template wording and nothing else. Appending a reason (for example `- [x] — because ...`) silently fails to match and emits an advisory warning. Copy the seven lines verbatim and put reasoning in a paragraph beneath them. - Check a body offline before pushing rather than learning it from CI; `evaluatePullRequestPolicy` is the same function the workflow calls. Expect `ok: true` with - empty `errors`: + empty `errors` (and address any relevant `warnings`): ```bash node -e "import('./scripts/pr-policy.mjs').then(m=>{ @@ -249,8 +252,9 @@ human review comments must follow the repository's strict resolution discipline: are unavailable, failing, rate-limited, or unconfigured, no required test, check, lint, build, or security gate may be bypassed, skipped, or weakened. Required gates form the deterministic safety net and remain absolute. -- Clinical-risk and RAG-surface pull requests still require their PR-body preflight governance and - impact declarations in full (`scripts/pr-policy.mjs`). +- Clinical-risk and RAG-surface pull requests are still expected to include their PR-body preflight + governance and impact declarations in full (`scripts/pr-policy.mjs` emits advisory warnings since + 2026-09-17 when omitted rather than hard-blocking merges). - Never undraft a PR prematurely merely to obtain automated review; undrafting immediately triggers heavy browser and build shards and cancels in-flight CI runs. - Reduce PR churn by bundling low-risk append-only paperwork with product PRs (see diff --git a/docs/agents/verification-gates.md b/docs/agents/verification-gates.md index 4f338869c5..f6da3b1ed1 100644 --- a/docs/agents/verification-gates.md +++ b/docs/agents/verification-gates.md @@ -8,9 +8,9 @@ _Updated 2026-10-01 - distinguish scoped CI selection from completed verificatio - PR and merge-queue CI summaries include a **PR test recommendation** derived from the same event base/head and browser planner as local work. It names the relevant check groups and recommends complete owning browser specs, escalating shared or unknown browser inputs to the full local gate. The recommendation step runs no tests and does not narrow required CI. Draft summaries explicitly distinguish deferred checks from merge readiness. - Runtime manifests, Next/CSS/TypeScript configuration, shared browser hooks, theme state and the browser client/store are browser inputs even when no component changes. A build alone does not prove browser behaviour. The production-spec inventory guard catches configured browser tests missing from the selector. -- The post-merge browser matrix uses one Chromium runner, three Firefox partitions and two partitions for each WebKit project, retaining one worker and zero retries per runner. Its primary path excludes only projects already proved by the production shards; mobile WebKit and standalone PWA still run. This is test partitioning, not selective omission. The previous three-way WebKit engine split assigned a whole project to each runner and both mobile projects timed out. The revised within-project partitioning retains every test; its hosted speed and runner-minute effects still need measurement. Large test files can still produce uneven partitions. +- The post-merge browser matrix uses 23 legs across six non-production-Chromium projects (`chromium-mockups` 1, `firefox` 4, `webkit` 4, `mobile-webkit` 5, `mobile-pwa-standalone` 5, and `tablet` 4), retaining one worker and zero retries per runner. Its primary path excludes only production `chromium` when already proved by the in-run production shards; Chromium mockups, Firefox, WebKit, mobile WebKit, standalone PWA, and tablet all run. This is test partitioning, not selective omission. Within-project duration-balanced partitioning (`scripts/playwright-release-shards.mjs`) retains every test across those 23 legs. - Firefox/WebKit reuse the successful production browser build from the same workflow run. Chromium builds separately because its mockup-enabled public flag is compiled into the app. A skipped producer retains the normal build path; a failed producer or missing expected artifact must not silently become reused proof. Browser download caches are isolated by engine so one engine cannot fill an immutable shared key with an incomplete archive set. -- To get Firefox/WebKit results for a branch before merge, dispatch CI on it (`gh workflow run ci.yml --ref `). A manual run defaults to `scope: browser-matrix`: static checks, the shared Playwright build, production Chromium and the full release matrix, without re-running unit coverage, build, Lighthouse or migration replay that the branch's PR already runs. Use `-f scope=full` only when the whole suite is the point, and dispatch once per head: an identical second dispatch re-runs all 16 matrix legs. +- To get Firefox/WebKit results for a branch before merge, dispatch CI on it (`gh workflow run ci.yml --ref `). A manual run defaults to `scope: browser-matrix`: static checks, the shared Playwright build, production Chromium and the full release matrix, without re-running unit coverage, build, Lighthouse or migration replay that the branch's PR already runs. Use `-f scope=full` only when the whole suite is the point, and dispatch once per head: an identical second dispatch re-runs all 23 matrix legs. - Unit coverage runs in two partitions. Their required aggregate rejects any failed or missing partition and merges the blobs using the original coverage configuration and thresholds; partial coverage is never a passing coverage verdict. - Rerunning CI replaces same-run coverage/build and operator-consumed artifacts under stable consumer names, while diagnostic and timing artifacts include the run attempt so earlier evidence survives. A failed-job rerun can still download a successful producer's artifact from an earlier attempt of the same run. - Successful production and release UI partitions retain their JSON reports for seven days so future balancing can use current per-file timings. Do not treat historical zero-duration entries in the shard profile as measurements or automatically remove tests because they have recently passed. @@ -25,7 +25,7 @@ _Updated 2026-10-01 - distinguish scoped CI selection from completed verificatio | 3 — Domain gate | Shared UI/routing, dependencies, security, privacy, RAG, clinical output, production configuration, or another cross-cutting domain | The smallest applicable repository/domain selector, focused journey, or contract gate | | 4 — Broad handoff | The diff crosses multiple subsystems, cannot be bounded reliably, or the task explicitly requires PR/release confidence | One appropriate broad gate, selected rather than stacked by default | -- Do not run a broad baseline routinely before localized work, and do not select `verify:cheap` merely because a change is described as “non-trivial.” `npm run verify:cheap` is the ordinary offline gate (`check:installed-lock-parity` + `check:diff-integrity` + lint + typecheck + test). Use `npm run verify:full` when cross-module risk warrants the broad static set (41 static gates, then lint + typecheck + test). Use `npm run verify:pr-local` when a change is ready for PR handoff: it classifies the changed paths, runs focused documentation/workflow contracts for recognised low-risk scopes, and fails closed to lint, typecheck, the full unit suite, RAG fixture validation, and relevant build/domain gates for executable or unknown scope. If the diff has not changed, do not run `verify:cheap` first merely to repeat the same coverage. +- Do not run a broad baseline routinely before localized work, and do not select `verify:cheap` merely because a change is described as “non-trivial.” `npm run verify:cheap` is the ordinary offline gate (`check:installed-lock-parity` + `check:diff-integrity` + lint + typecheck + test). Use `npm run verify:full` when cross-module risk warrants the broad static set (42 static gates ending with `check:offline-pack`, then lint + typecheck + test). Use `npm run verify:pr-local` when a change is ready for PR handoff: it classifies the changed paths, runs focused documentation/workflow contracts for recognised low-risk scopes, and fails closed to lint, typecheck, the full unit suite, RAG fixture validation, and relevant build/domain gates for executable or unknown scope. If the diff has not changed, do not run `verify:cheap` first merely to repeat the same coverage. - Do not stack focused tests, full tests, typecheck, lint, build, and browser checks unless each catches a distinct plausible regression. Do not rerun an unchanged successful gate. Since 2026-08-21 that last rule is enforced rather than remembered: `scripts/gate-receipts.mjs` memoises `lint`, `typecheck` and non-coverage Vitest runs against a content signature, so an identical re-run on unchanged content exits 0 immediately instead of repeating the work. A reused receipt must be reported as "reused receipt from