docs: UPSTREAM-RHYTHM.md — Zeta's fork-first batched PR cadence#137
Merged
docs: UPSTREAM-RHYTHM.md — Zeta's fork-first batched PR cadence#137
Conversation
2 tasks
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: da91bbdb6e
ℹ️ 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".
There was a problem hiding this comment.
Pull request overview
Adds a Zeta-specific documentation page describing the project’s fork-first, batched PR workflow (AceHack fork as the day-to-day target, with periodic bulk sync PRs into the Lucent-Financial-Group org), intended as the configuration companion to the factory-generic fork-pr-workflow skill.
Changes:
- Introduces
docs/UPSTREAM-RHYTHM.mddocumenting the batched fork-first cadence and rationale. - Provides concrete
ghCLI command sequences for the default PR flow, bulk sync, and forward-sync. - Lists “bypass” exceptions and proposes a cadence monitor heuristic.
AceHack
force-pushed
the
land-upstream-rhythm-doc
branch
from
da91bbd to
c49f1ef
Compare
Member
Author
|
Addressed the three review findings in the force-pushed commit:
Not self-resolving the conversations — that's the human maintainer's move on review. 🤖 Generated with Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c49f1efb61
ℹ️ 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".
AceHack
added a commit
that referenced
this pull request
Apr 23, 2026
… paths - Replace remaining "Aaron" attribution with "the human maintainer" role-ref (line 7 trigger line) - Mark `docs/aurora/` as landing via PR #144 in the ownership table; file does not yet exist on main - Collapse the 4 dangling per-user memory paths in "Composes with" to a single acknowledgement that those rules live in the per-user memory layer (`~/.claude/projects/<slug>/memory/`), not in-repo Matches the same pattern applied to #137 and #153. Per Aaron's "just move forward for now" — addressing legitimate review findings without bypassing branch protection. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The fork-pr-workflow skill defers the upstream-cadence choice to project-level config. This is Zeta's config: - Default PR target: AceHack/Zeta:main (free CI, free Copilot) - Bulk sync AceHack/main -> LFG/main every ~10 PRs (one PR, not N) - Five named exceptions for direct-to-LFG (security P0, external contributor, Aaron explicit, CI-repair, the bulk-sync PR itself) - Concrete gh commands for each case - Proposed cadence-monitor FACTORY-HYGIENE row Resolves a phantom pointer in memory/feedback_fork_pr_cost_model_prs_land_on_acehack_sync_to_lfg_in_bulk.md which cited docs/UPSTREAM-RHYTHM.md as an intended target. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
AceHack
force-pushed
the
land-upstream-rhythm-doc
branch
from
c49f1ef to
af98671
Compare
| # preserves the ancestry relationship the forward-sync | ||
| # needs and keeps ahead/behind counts accurate for the | ||
| # cadence monitor. | ||
| gh pr merge <N> --repo Lucent-Financial-Group/Zeta --auto --merge |
There was a problem hiding this comment.
P1: This command hard-codes specific GitHub user/org names (e.g., Lucent-Financial-Group, AceHack). Repo convention is that docs should avoid direct contributor names and instead use role refs/placeholders; consider rewriting these examples to use placeholders like <FORK_OWNER> / <UPSTREAM_OWNER> and explain what they map to for this repo.
Comment on lines
189
to
190
| > and flag if AceHack is >15 commits ahead (over-threshold) or | ||
| > >30 days since last sync (stale-threshold). |
There was a problem hiding this comment.
P1: The cadence-monitor instruction says to flag “>30 days since last sync”, but the compare call shown here doesn’t provide (or extract) an elapsed-days signal on its own. Either add the additional steps/JQ needed to compute staleness from commit timestamps, or remove the 30-day check from this proposed monitor so it’s not misleading.
Suggested change
| > and flag if AceHack is >15 commits ahead (over-threshold) or | |
| > >30 days since last sync (stale-threshold). | |
| > and flag if AceHack is >15 commits ahead (over-threshold). |
Comment on lines
+198
to
+200
| per-user agent memory (not checked into the repo; see | ||
| `docs/CONTRIBUTOR-PERSONAS.md` on the memory split between | ||
| in-repo artifacts and per-user agent state). The load-bearing |
There was a problem hiding this comment.
P1: This section points readers to docs/CONTRIBUTOR-PERSONAS.md for the “memory split”, but that doc doesn’t mention per-user agent memory or any in-repo vs per-user memory split. Please either add the relevant explanation to that doc, or update this reference to the correct document that defines the split.
Suggested change
| per-user agent memory (not checked into the repo; see | |
| `docs/CONTRIBUTOR-PERSONAS.md` on the memory split between | |
| in-repo artifacts and per-user agent state). The load-bearing | |
| per-user agent memory, which is not checked into the repo; | |
| only in-repo artifacts live in the repository, while | |
| per-user agent state remains outside it. The load-bearing |
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
…ase sequencing (D→A→E) (#150) * research: multi-repo refactor — 5 candidate shapes + recommended 3-phase sequencing Aaron's 2026-04-23 directive: *"we can even wait on the demo until we have refactored into our multi repo shape... that seems very structural and like we should do it sooner rather than later, but it's up to you."* Per `memory/feedback_factory_reuse_packaging_decisions_consult_aaron.md`, big shaping decisions need consultation. This doc IS the consultation prep — prior-art + candidates + trade-offs + my recommendation. ## What lands `docs/research/multi-repo-refactor-shapes-2026-04-23.md` — ~230 lines covering: ### Prior art surveyed - AI-agent-factory patterns (Claude Code plugins, Anthropic skills, OpenAI Agents SDK, Semantic Kernel) - Template / overlay (GitHub templates, Cookiecutter, Nix flakes) - Monorepo tools (Nx, Turborepo, Lerna, pnpm, Bazel, .NET solutions) - OSS splits that worked (VS Code, Rust, Kubernetes) vs failed (early Android, Eclipse) - **Lesson extracted:** split when there's a clear consumer boundary + tooling enforces it; stay monorepo when things co-evolve tightly. Zeta + factory is at the transition point. ### Current monorepo inventory Classifies every top-level directory as generic-factory vs Zeta-specific vs Aurora-specific. Real separation exists but with boundary overlap. ### Five candidate architectures - **A. Template-repo** — clone-and-customize; no update flow. Easy to land, but adopters diverge. - **B. Git submodule** — updates flow, but submodule UX is rough. - **C. Plugin / package (NPM-like)** — version-pinned dependency model. Familiar, but slow update cadence. - **D. Formalised monorepo** — namespaced boundaries, no extraction. Cheapest, doesn't enable reuse. - **E. Overlay pattern** — factory-apply tool + publishable components. Best of both worlds, but requires tool investment. ### My recommended sequence: D → A → E - **Phase 1 (now): D** — reorganise the monorepo into `factory/` + `library/` + `aurora/` + `research/` top-level directories. Enforce via CI lint. Cheap, clarifies the mental model, unblocks future extraction without committing to it. - **Phase 2 (first adopter): A** — extract `factory/` as a GitHub template repo. Standard OSS playbook. - **Phase 3 (adopters > 3): E** — invest in `factory-apply` tool + overlay discipline when update-flow friction is real. ### Aurora-specific consideration Aurora lives in the current `zeta` repo through Phase 1. At Phase 2, `zeta-aurora` gets extracted concurrently with the factory extraction, giving Amara a dedicated repo she can read end-to-end in her deep-research mode. ### Questions for Aaron Five open questions where packaging choices genuinely need his input: 1. Sequencing (D-A-E vs alternates) 2. Phase 2 trigger definition ("first adopter appears" is vague) 3. Aurora repo timing (Phase 1 / 2 / later) 4. Naming (`zeta-factory` vs `agent-factory` vs `glass-halo-factory`) 5. In-flight PRs handling during extraction ## My choice to ship this now Aaron said packaging decisions need consultation; my job is to *prepare* the consultation with prior-art + candidates + trade-offs + recommendation. That's what this doc is. Aaron reviews on his cadence (per his 2026-04-23 framing that he has a decision log he reviews often and nudges when he disagrees). ## What this does NOT do - Does NOT start any extraction work. Phase 1 reorganisation is MY recommendation, not a unilateral decision. Aaron's review gates Phase 1 execution. - Does NOT commit to Phase 2 / 3 timing — those depend on adopter signals that don't exist yet. - Does NOT propose novel split-discipline tooling without prior-art anchoring — every candidate is grounded in a shipped OSS pattern. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * pr-150: address review findings — anonymize contributor, mark pending paths - Replace remaining "Aaron" attribution with "the human maintainer" role-ref (line 7 trigger line) - Mark `docs/aurora/` as landing via PR #144 in the ownership table; file does not yet exist on main - Collapse the 4 dangling per-user memory paths in "Composes with" to a single acknowledgement that those rules live in the per-user memory layer (`~/.claude/projects/<slug>/memory/`), not in-repo Matches the same pattern applied to #137 and #153. Per Aaron's "just move forward for now" — addressing legitimate review findings without bypassing branch protection. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * drain: resolve 4 threads on #150 Collapse remaining dangling memory path reference in "Why this matters" section. The factory-reuse-beyond-Zeta constraint is acknowledged as living in the per-user memory layer rather than citing a specific in-repo file that doesn't exist. The other three threads are addressed by the prior commit (3028a0e): - Copilot attribution scrub (PRRT_kwDOSF9kNM59IRe3): rejected per Otto-256 — docs/research/** is history-class, first-name attribution permitted. The prior commit had already scrubbed remaining "Aaron" prose to "the human maintainer" voluntarily; no further action. - Copilot broken refs (PRRT_kwDOSF9kNM59IRff): the four memory paths collapsed in "Composes with"; this commit handles the one remaining inline citation. - Copilot aurora-row (PRRT_kwDOSF9kNM59IRf7): inventory row marked "lands via PR #144" in the prior commit. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
GOVERNANCE.md §23docs/UPSTREAM-*files🤖 Generated with Claude Code