docs(dream): pgserve v2.4 cohort batch execution plan#74
Conversation
DREAM.md scaffolds the 3-wish cohort dispatch tracked under PG task #6. Phase 1 dispatched on a fresh worktree off wish/pgserve-singleton-no-proxy. Layers: - L1: singleton G1 (foundation — admin.json writer module) - L2: singleton G2-G9 + cutover G1-G10 (parallel, mostly WIP'd) + canonical G1 - L3: cutover G11/G19/G20 (Tier A/B installers) - L4: cutover G12 + canonical G2/G3 - L5: cutover G13-G15 + canonical G4 - L6: cutover G16-G18 (docs + byte-equality CI + final validation) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR adds ChangesDREAM Execution Plan
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 97fe66bcd5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | merge_order | slug | branch | wish_path | depends_on | | ||
| |-------------|------|--------|-----------|------------| | ||
| | 1 | `pgserve-singleton-no-proxy` | `wish/pgserve-singleton-no-proxy` | `.genie/wishes/pgserve-singleton-no-proxy/WISH.md` | (foundation — no internal deps; cross-wish: none) | | ||
| | 2 | `autopg-distribution-cutover` | `wish/autopg-cutover-transport-absorb` | `.genie/wishes/autopg-distribution-cutover/WISH.md` | cross-wish: `pgserve-singleton-no-proxy` G1 (G11/G19/G20 only) | |
There was a problem hiding this comment.
Point cutover wish_path at an existing document
The cohort table references .genie/wishes/autopg-distribution-cutover/WISH.md, but this repository snapshot does not contain that path, so readers cannot open the acceptance criteria for the cutover wish from this plan. Because Phase 1/2 execution depends on that artifact, this broken reference can cause implementers to proceed without the source-of-truth wish spec or review the wrong criteria.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Code Review
This pull request introduces a new .genie/DREAM.md file to coordinate the pgserve v2.4 cohort batch execution. The review identified a potential typo in the group numbering (G11.6 vs G11) and raised an architectural concern regarding the placement of the supervisor configuration field, suggesting it should reside in settings.json rather than admin.json to maintain a clear separation between authentication secrets and operational configuration.
|
|
||
| ## Critical execution constraints | ||
|
|
||
| 1. **Cutover wish has 11/18 groups WIP'd already.** Engineer must `git log --oneline wish/autopg-cutover-transport-absorb` first; any group whose subject matches `wip: autopg-distribution-cutover#N` is DONE — verify acceptance criteria, do NOT re-implement. New code goes only on G11.6, G12-G18, G19, G20. |
There was a problem hiding this comment.
The reference to G11.6 appears to be a typo or refers to an undefined sub-group. The execution layers defined in Layer 3 (line 30) only mention G11.
|
|
||
| 4. **No parallel writes to ~/.autopg/admin.json.** It's a single-host config file. Tier A install (cutover G11) is mutually exclusive with Tier B install (cutover G20). Tests must use isolated `XDG_CONFIG_HOME` fixtures. | ||
|
|
||
| 5. **Cohort signal: `~/.autopg/admin.json.supervisor` field**. Schema enum: `"pm2" | "systemd-user" | "launchd" | "external"`. Any worker writing this field must use the writer module from singleton G1, not roll their own. |
There was a problem hiding this comment.
There is a potential architectural discrepancy regarding the use of admin.json. In src/cli-install.cjs (lines 42-50), admin.json is defined as a restricted-access file (mode 0600) specifically for storing scrypt-hashed admin passwords. However, this plan suggests adding a supervisor configuration field to it. Since settings.json (defined in src/settings-schema.cjs) is the established store for general configuration and already contains a supervision section, the supervisor signal would be more appropriately placed there to maintain separation between authentication secrets and operational configuration.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.genie/DREAM.md:
- Line 26: The "11 of these are ALREADY WIP'd on the cutover branch (commits
c72dab8 → 7e04f7b)" note is ambiguous because the visible cutover list shows
G1–G10; update the sentence to explicitly enumerate the 11 completed group IDs
(e.g., "G1, G2, ..., G11") or replace with a precise reference to the commits by
listing the commit subjects included between commits c72dab8 and 7e04f7b so
readers know exactly which items are already done; ensure the text around the
existing "cutover list" and the parenthetical commit range is updated to remove
ambiguity.
- Around line 19-49: The fenced code block in DREAM.md is unlabeled (```), which
triggers markdownlint MD040; update the opening fence for that block to include
a language tag (e.g., change the opening "```" to "```text") so the entire block
is treated as plain text and the linter will pass; locate the triple-backtick
fenced block shown under the layer diagram and add the language label to the
opening fence only.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ``` | ||
| Layer 1 (foundation) | ||
| └─ singleton G1 (postmaster -k -p 5432, dual-transport, admin.json writer module src/lib/admin-json.js) | ||
|
|
||
| Layer 2 (parallel after L1; cutover G1-G10 are independent of singleton, so could go earlier — but keep linear for human-readable progress) | ||
| ├─ singleton G2-G9 (delete bun proxy, CLI verbs, cosign primitives, blocklist, self-healing update, roles+grants, migration tooling, tests/docs) | ||
| ├─ cutover G1-G10 (admin SCRAM, pg_hba B1, schema rename, delete proxy modules, autopg create-app, audit, bun-build binaries, cosign sign, CDN publish, install.sh) | ||
| │ NOTE: 11 of these are ALREADY WIP'd on the cutover branch (commits c72dab8 → 7e04f7b). Engineer must read existing commits and only implement what's missing. | ||
| └─ canonical G1 (libraries: pm2-args.js + admin-json.js + uninstall.js) | ||
|
|
||
| Layer 3 (depends on L2) | ||
| ├─ cutover G11 (autopg install Tier A — pm2 register, depends on singleton G1's admin.json writer) | ||
| ├─ cutover G19 (autopg serve dual-transport binding + runtime.json discovery) | ||
| └─ cutover G20 (autopg service install Tier B — systemd-user/launchd, hard MIGRATE contract) | ||
|
|
||
| Layer 4 (depends on L3) | ||
| ├─ cutover G12 (autopg update 13-stage pipeline) | ||
| ├─ canonical G2 (genie install + pm2 supervision; cross-wish dep on cutover G11+G20) | ||
| └─ canonical G3 (omni install reconfig + migration; cross-wish dep on cutover G11+G20) | ||
|
|
||
| Layer 5 (depends on L4) | ||
| ├─ cutover G13 (Genie consumer migration — DATABASE_URL from autopg.env) | ||
| ├─ cutover G14 (Omni consumer migration + release pipelines) | ||
| ├─ cutover G15 (Final pgserve@2.260503.0 npm advisory) | ||
| └─ canonical G4 (Brain ingestion + ADR) | ||
|
|
||
| Layer 6 (final) | ||
| ├─ cutover G16 (Documentation + migration guide unified) | ||
| ├─ cutover G17 (SHARED-DESIGN.md byte-equality CI lint) | ||
| └─ cutover G18 (Cutover validation — Felipe-host + doctor 11/11 + sentinel signoff) | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the fenced block to satisfy markdownlint (MD040).
This block is currently an unlabeled fence; add a language (e.g., text) to clear lint and keep docs CI clean.
Proposed fix
-```
+```text
Layer 1 (foundation)
└─ singleton G1 (postmaster -k -p 5432, dual-transport, admin.json writer module src/lib/admin-json.js)
@@
Layer 6 (final)
├─ cutover G16 (Documentation + migration guide unified)
├─ cutover G17 (SHARED-DESIGN.md byte-equality CI lint)
└─ cutover G18 (Cutover validation — Felipe-host + doctor 11/11 + sentinel signoff)
-```
+```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| Layer 1 (foundation) | |
| └─ singleton G1 (postmaster -k -p 5432, dual-transport, admin.json writer module src/lib/admin-json.js) | |
| Layer 2 (parallel after L1; cutover G1-G10 are independent of singleton, so could go earlier — but keep linear for human-readable progress) | |
| ├─ singleton G2-G9 (delete bun proxy, CLI verbs, cosign primitives, blocklist, self-healing update, roles+grants, migration tooling, tests/docs) | |
| ├─ cutover G1-G10 (admin SCRAM, pg_hba B1, schema rename, delete proxy modules, autopg create-app, audit, bun-build binaries, cosign sign, CDN publish, install.sh) | |
| │ NOTE: 11 of these are ALREADY WIP'd on the cutover branch (commits c72dab8 → 7e04f7b). Engineer must read existing commits and only implement what's missing. | |
| └─ canonical G1 (libraries: pm2-args.js + admin-json.js + uninstall.js) | |
| Layer 3 (depends on L2) | |
| ├─ cutover G11 (autopg install Tier A — pm2 register, depends on singleton G1's admin.json writer) | |
| ├─ cutover G19 (autopg serve dual-transport binding + runtime.json discovery) | |
| └─ cutover G20 (autopg service install Tier B — systemd-user/launchd, hard MIGRATE contract) | |
| Layer 4 (depends on L3) | |
| ├─ cutover G12 (autopg update 13-stage pipeline) | |
| ├─ canonical G2 (genie install + pm2 supervision; cross-wish dep on cutover G11+G20) | |
| └─ canonical G3 (omni install reconfig + migration; cross-wish dep on cutover G11+G20) | |
| Layer 5 (depends on L4) | |
| ├─ cutover G13 (Genie consumer migration — DATABASE_URL from autopg.env) | |
| ├─ cutover G14 (Omni consumer migration + release pipelines) | |
| ├─ cutover G15 (Final pgserve@2.260503.0 npm advisory) | |
| └─ canonical G4 (Brain ingestion + ADR) | |
| Layer 6 (final) | |
| ├─ cutover G16 (Documentation + migration guide unified) | |
| ├─ cutover G17 (SHARED-DESIGN.md byte-equality CI lint) | |
| └─ cutover G18 (Cutover validation — Felipe-host + doctor 11/11 + sentinel signoff) | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 19-19: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.genie/DREAM.md around lines 19 - 49, The fenced code block in DREAM.md is
unlabeled (```), which triggers markdownlint MD040; update the opening fence for
that block to include a language tag (e.g., change the opening "```" to
"```text") so the entire block is treated as plain text and the linter will
pass; locate the triple-backtick fenced block shown under the layer diagram and
add the language label to the opening fence only.
| Layer 2 (parallel after L1; cutover G1-G10 are independent of singleton, so could go earlier — but keep linear for human-readable progress) | ||
| ├─ singleton G2-G9 (delete bun proxy, CLI verbs, cosign primitives, blocklist, self-healing update, roles+grants, migration tooling, tests/docs) | ||
| ├─ cutover G1-G10 (admin SCRAM, pg_hba B1, schema rename, delete proxy modules, autopg create-app, audit, bun-build binaries, cosign sign, CDN publish, install.sh) | ||
| │ NOTE: 11 of these are ALREADY WIP'd on the cutover branch (commits c72dab8 → 7e04f7b). Engineer must read existing commits and only implement what's missing. |
There was a problem hiding this comment.
Clarify the “11 already WIP’d” reference to avoid execution mistakes.
Line 26 says “11 of these,” but the nearby cutover list is G1-G10; this is easy to misread. Consider explicitly listing the 11 completed group IDs (or pointing to exact commit subjects) in this section.
Also applies to: 53-53
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.genie/DREAM.md at line 26, The "11 of these are ALREADY WIP'd on the
cutover branch (commits c72dab8 → 7e04f7b)" note is ambiguous because the
visible cutover list shows G1–G10; update the sentence to explicitly enumerate
the 11 completed group IDs (e.g., "G1, G2, ..., G11") or replace with a precise
reference to the commits by listing the commit subjects included between commits
c72dab8 and 7e04f7b so readers know exactly which items are already done; ensure
the text around the existing "cutover list" and the parenthetical commit range
is updated to remove ambiguity.
DREAM.md scaffolds the v2.4 cohort batch execution. Tracks PG task #6.
Cohort
Status
Engineer engineer@dream-pgserve-v2-4 dispatched on Layer 1 (singleton G1 foundation).
Plan
See .genie/DREAM.md for the full layer-by-layer execution plan + critical constraints (cutover wish has 11/18 groups already WIP'd; cohort contract files co-owned).
Summary by CodeRabbit
Note: This release contains no user-facing changes or new features.