From c3d98241a70e1966f73e362c92e40f42af163dac Mon Sep 17 00:00:00 2001 From: Amruth Pillai Date: Sat, 5 Sep 2026 23:42:11 +0200 Subject: [PATCH] docs: begin independent reviews --- docs/execution/approved-issue-plans-ledger.md | 10 +++++--- docs/execution/briefs/review-plan-02.md | 25 +++++++++++++++++++ docs/execution/briefs/review-plan-07.md | 25 +++++++++++++++++++ 3 files changed, 56 insertions(+), 4 deletions(-) create mode 100644 docs/execution/briefs/review-plan-02.md create mode 100644 docs/execution/briefs/review-plan-07.md diff --git a/docs/execution/approved-issue-plans-ledger.md b/docs/execution/approved-issue-plans-ledger.md index 64fbcd1fb..fb5d47189 100644 --- a/docs/execution/approved-issue-plans-ledger.md +++ b/docs/execution/approved-issue-plans-ledger.md @@ -34,12 +34,12 @@ state changes are outside scope. | Unit | Issues | Status / current validity | Owner | Worktree / branch | Base → head | Dependencies | Evidence | Tests | PR | Next action | Blockers | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 01 account login/recovery | #3166, #3164, #3078, #3046, #2897, #2837 | blocked | audit `task_855fbee0a803` | `codex-audit-backend-01-06` | `7a98f6662` → no source change | none | zero drift; live issues remain split; #3046/#3078 have merged #3095 candidate only | auth 42, email 6, focused/full API/server suites and affected typechecks/boundaries passed in audit | — | select exact auth/mail/API boundary only after current sanitized trace | current cloud digest, provider/account method, request/status trace, controlled mailbox | -| 02 hosted v4 recovery | #3181, #2760 | implementing | `task_bae016c4d1f2` / `ctx_303f5d1f1031` | `issue-3181-recovery-procedure`; target `codex/issue-3181-recovery-procedure` | `7a98f6662` → pending | #2760 identity branch depends on 01 evidence | partial source unit: zero drift; synthetic non-networked runbook/tool ready; real recovery and #2760 cause unproved | implementation verification pending | — | build pure compare tool and safeguards docs; independently review | actual recovery needs verified owner, available snapshot, reviewed legacy format, authorized private delivery | +| 02 hosted v4 recovery | #3181, #2760 | reviewing | implementation `task_bae016c4d1f2`; review `task_46be9a1a4d82` / `ctx_e9f651d38a65` | `codex/issue-3181-recovery-procedure` | `7a98f6662` → `3f53deca8` | #2760 identity branch depends on 01 evidence | pure comparator and safeguards committed locally; partial only; real recovery and #2760 cause unproved | implementer reports focused tests, full 19-task suite, typechecks, boundaries, Biome/Markdown/diff gates green; independent rerun active | — | resolve independent findings, fresh verify, publish unmerged PR | actual recovery needs verified owner, available snapshot, reviewed legacy format, authorized private delivery | | 03 MCP registration | #3398, #3153 | no-change | audit `task_855fbee0a803` | `codex-audit-backend-01-06` | `7a98f6662` → no source change | coordinate DB/startup with 05 | merged #3421 (`fe9b59e`) present on main; current schema/startup/auth contracts match plan | #3421 hosted checks successful; audit auth/server/API/DB tests, typechecks, boundaries passed | #3421 merged before run | deployment verification only | deployed digest/log correlation and exact Codex/Claude DCR/consent/PKCE/MCP retest unavailable | | 04 AI provider compatibility | #2732, #2766, #2723, #2708 | blocked | audit `task_855fbee0a803` | `codex-audit-backend-01-06` | `7a98f6662` → no source change | serialize edits to AI service | zero drift; historical #2708 Responses path and #2766 structured Test path absent; remaining tuples differ | focused API 96 and full API suites/typecheck/boundaries passed in audit | — | select wire/state/import/base-path unit only after exact current tuple fails | provider/model/base URL/path/version/action/error tuple and allowed endpoint unavailable | | 05 AI provider migrations | #3152 | blocked | audit `task_855fbee0a803` | `codex-audit-backend-01-06` | `7a98f6662` → no source change | coordinate DB/startup with 03 | zero drift; table schema, migration, startup ordering, Docker copy path coherent; `42P01` historical cause unresolved | audit API/server/DB tests, typechecks, boundaries passed; no real PostgreSQL migration fixture | — | choose config/packaging/startup/migration repair only after disposable reproduction | affected image layout/digest, working directory, DB schema/search path/journal, fresh+upgrade DB fixture | | 06 image storage delivery | #2684, #2778 | blocked | audit `task_855fbee0a803` | `codex-audit-backend-01-06` | `7a98f6662` → no source change | coordinate 12/15/25 renderer/image fixtures | #2684 ACL cause fixed by merged #3432 (`35cecf9`); #2778 Browserless path obsolete; current topology unproved | #3432 hosted checks successful; audit storage/upload/PDF tests, typechecks, boundaries passed | #3432 merged before run | deployment retest plus shared real-encoding/backend/render fixture before repair | deployed digest; disposable S3/Garage/SeaweedFS/MinIO/proxy and browser/server raster matrix unavailable | -| 07 AIO deployment | #2722 | pending implementation; requested feature declined | audit `task_9f27829ca50f` | planned `codex/issue-2722-postgres-docs` | `7a98f6662` → — | none | Q12 and runtime confirm one app process plus separate PostgreSQL; docs already cover core quickstart/backups, with topology/Unraid/reused-DB/upgrade gaps | audit markdown lint and Compose config passed | — | make exact two-file docs improvement without AIO/runtime changes or closing keyword | no AIO implementation permitted; optional Unraid host smoke unavailable | +| 07 AIO deployment | #2722 | reviewing | implementation `task_aee702e37eae`; review `task_b29de2cd974c` / `ctx_46d7f32205a1` | `codex/issue-2722-postgres-docs` | `7a98f6662` → `e37b73566` | none | two docs committed locally; separate PostgreSQL/no-AIO policy plus topology/Unraid/reused-DB/upgrade gaps addressed | implementer reports Compose config, Markdown lint, focused source/diff/scope gates green; independent rerun active | — | resolve independent findings, fresh verify, publish unmerged PR without closing keyword | no AIO implementation permitted; optional Unraid host smoke unavailable | | 08 root public resume | #2669 | plan amendment required before implementation | audit `task_9f27829ca50f` | planned `codex/issue-2669-root-resume` | `7a98f6662` → — | none | current password redirect rejects `/`; public view is slug-hook-bound; SSR canonical cannot import server env; expanded auth/canonical contract identified | audit focused API/web suites, typechecks, boundaries passed | — | amend ownership for identity-vs-return auth flow and server-derived canonical root, then dispatch coherent feature | engineering scope correction; feature remains narrower than arbitrary domain/TLS registry | | 09 external version backup | #2705 | pending implementation | audit `task_9f27829ca50f` | planned `codex/issue-2705-git-backup-docs` | `7a98f6662` → — | none | current resume, independent cover-letter, and account export shapes verified; manual local Git workflow approved | audit export/import suites, markdown lint, typechecks, boundaries passed | — | publish plain Git commands and format distinctions; validate in disposable local repo | no automatic sync, remote, or whole-account restore; agent-only `rtk` syntax forbidden in user docs | | 10 legacy link routing | #2836 | pending implementation after brief correction | audit `task_9f27829ca50f` | planned `codex/issue-2836-retired-slug-notices` | `7a98f6662` → — | none | prospective same-username slug-attempt notice remains coherent; exact DB/API/UI/E2E owner set verified | audit focused API/web suites, DB/API/web typechecks, boundaries passed | — | correct final E2E target to `public-sharing.spec.ts`, then implement migration/API/owner UI atomically | historical cause absent; no redirects/emails/recovery; prospective partial coverage only | @@ -77,10 +77,12 @@ state changes are outside scope. | Plans 07–11, 35 | `task_9f27829ca50f` / `ctx_11f7d7cf6d17` | `codex-audit-backend-07-11-35` | complete; worker release pending | 07/09/10/11 ready after named brief corrections; 08 needs engineering scope amendment; 35 diagnostic-only | | Plans 12–19 | `task_1c6582ccdeae` / `ctx_795fced595ef` | `codex-audit-rendering-12-19` | complete; worker release pending | 15A/16/19 implementation-ready; remaining causes split into diagnostics with named evidence gates | | Plans 20–34 | `task_47ed7eb02d48` / `ctx_50d8257459ab` | `codex-audit-builder-20-34` | complete; worker release pending | ready: 20A, 21, 22, 23A, 28 diagnostics, 32, 34; remaining plans split at evidence/design gates | -| Plan 07 implementation | `task_aee702e37eae` / `ctx_ed134b1d79ce` | `issue-2722-postgres-docs`; target `codex/issue-2722-postgres-docs` | starting | two-file docs change, verification, commit, independent review | +| Plan 07 implementation | `task_aee702e37eae` / `ctx_ed134b1d79ce` | `codex/issue-2722-postgres-docs` | implementation complete; worker released | commit `e37b73566`; two-file docs change; implementation report complete | | Plan 09 implementation | `task_e450ea143bfa` / `ctx_3b575cf1d5c7` | `issue-2705-git-backup-docs`; target `codex/issue-2705-git-backup-docs` | starting | two-file docs change, synthetic local-Git validation, commit, independent review | | Plan 11 implementation | `task_58d76423d364` / not dispatched | planned `codex/issue-3010-jsearch-docs` | waits on plans 07–11 audit | three-file docs change, source/test validation, commit, independent review | -| Plan 02 synthetic recovery | `task_bae016c4d1f2` / `ctx_303f5d1f1031` | `issue-3181-recovery-procedure`; target `codex/issue-3181-recovery-procedure` | implementing | pure deterministic compare tool, safeguards docs, TDD evidence, commit, independent review | +| Plan 02 synthetic recovery | `task_bae016c4d1f2` / `ctx_303f5d1f1031` | `codex/issue-3181-recovery-procedure` | implementation complete; worker released | commit `3f53deca8`; pure comparator, safeguards docs, TDD evidence | +| Plan 02 independent review | `task_46be9a1a4d82` / `ctx_e9f651d38a65` | same Plan 02 worktree | reviewing | findings-first review and independent verification | +| Plan 07 independent review | `task_b29de2cd974c` / `ctx_46d7f32205a1` | same Plan 07 worktree | reviewing | factual/safety review and independent validation | ## Existing PR and residual accounting diff --git a/docs/execution/briefs/review-plan-02.md b/docs/execution/briefs/review-plan-02.md new file mode 100644 index 000000000..c1a676dc5 --- /dev/null +++ b/docs/execution/briefs/review-plan-02.md @@ -0,0 +1,25 @@ +# Independent review: plan 02 synthetic recovery + +Review only; do not edit, commit, push, open PR, mutate issues, or spawn subagents. Read current worktree `AGENTS.md`, RTK, +issue/domain guidance, code-review/receiving-code-review/testing skills, implementation report +`.orchestration/plan-02-implementation.md`, and approved plan 02. Trust local planning checkout only when HEAD equals +`a2557b2ad40e06e1e63eb655f286e6a78fe6bf0d`; otherwise read +`git show a2557b2ad40e06e1e63eb655f286e6a78fe6bf0d:plans/02-hosted-v4-account-recovery.md`. + +Fetch current `origin/main` and GitHub issue/PR state. Confirm reviewed branch/commit and inspect complete +`origin/main...HEAD` diff. Treat prior report as a claim to verify. Review standards and approved-plan fidelity, especially: + +- Comparator is pure, deterministic, non-networked, non-writing, current-schema-only, and never implies owner/source + authenticity from hashes. Validate no import-time effects or accidental sensitive logging. +- Manifest contracts and tests correctly cover identical, old-only, divergent, owner/mapping/source blocks, malformed input, + determinism, immutability, and stable IDs/hashes. Seek false positives and weak self-fulfilling tests. +- Docs distinguish hosted operator authority from self-hosted authority, require owner verification/mapping/private delivery, + forbid overwrite/default public exposure, state no-source limits, and make no v4 conversion/recovery promise. +- Scope contains exactly four approved files. No private data or destructive recovery steps. + +Rerun focused tooling test/typecheck, relevant API/auth tests, affected typechecks, boundaries, narrow Biome/Markdown checks, +and `git diff --check`; rerun broader tests only where a finding needs proof. Record skipped gates. Findings first, ordered by +severity with exact file/line and concrete evidence. If none, state `No findings` and residual risks. + +Write `.orchestration/plan-02-review.md` with reviewed SHA/base, findings, commands/results, skipped gates, risks, and verdict +`ready for publication` or `changes required`. Final response at most ten lines. diff --git a/docs/execution/briefs/review-plan-07.md b/docs/execution/briefs/review-plan-07.md new file mode 100644 index 000000000..7514016c9 --- /dev/null +++ b/docs/execution/briefs/review-plan-07.md @@ -0,0 +1,25 @@ +# Independent review: plan 07 self-hosting documentation + +Review only; do not edit, commit, push, open PR, mutate issues, or spawn subagents. Read current worktree `AGENTS.md`, RTK, +issue/domain guidance, code-review/documentation skills, implementation report `.orchestration/plan-07-implementation.md`, +and approved plan 07. Trust local planning checkout only when HEAD equals +`a2557b2ad40e06e1e63eb655f286e6a78fe6bf0d`; otherwise use pinned `git show` for `plans/07-aio-deployment.md`. + +Fetch current `origin/main` and live issue/PR state. Confirm reviewed branch/commit and inspect complete +`origin/main...HEAD` diff. Verify every runtime/config claim against current Dockerfile, Compose, env validation/example, and +startup code. Review approved scope and reader safety: + +- State supported one-app-container plus separate PostgreSQL topology and no planned AIO image without claiming issue 2722 + implemented or closed. +- Smallest checklist and generic Unraid/homelab guidance use exact current service/path/port/env facts, warn that container + `localhost` is wrong for PostgreSQL, and never expose DB publicly or assert official Unraid support. +- Managed PostgreSQL reuse, optional Redis/S3 boundaries, database/upload backups, container updates, and PostgreSQL major + upgrades are accurate, non-duplicative, cross-linked, and safe for novice operators. +- Diff contains only two approved docs and retains existing MDX structure/links. + +Rerun focused `rg`, Compose config, Markdown lint, link inspection, and `git diff --check`. Record unavailable Unraid/Mintlify +checks as residual gates, not success. Findings first, ordered by severity with exact file/line and evidence. If none, state +`No findings` and residual risks. + +Write `.orchestration/plan-07-review.md` with reviewed SHA/base, findings, commands/results, skipped gates, risks, and verdict +`ready for publication` or `changes required`. Final response at most ten lines.