[Governance] Establish fork repository development specifications, issue tracking, and dual-end collaboration workflow #2

Activity

1. github-actions

   changed the title [-][Governance] 建立 fork 仓库开发规范、Issue 跟踪与双端协作工作流[/-] [+][Governance] Establish fork repository development specifications, issue tracking, and dual-end collaboration workflow[/+] on Sep 20, 2026
2. github-actions commented on Sep 20, 2026

   

   github-actionsBot

   on Sep 20, 2026 – with GitHub Actions

   Last edited by github-actions

   More actions

   _{Automated translation bookkeeping — detected language: Simplified Chinese.}
3. leonclab commented on Sep 21, 2026

   

   leonclab

   on Sep 21, 2026

   Last edited by github-actions

   OwnerAuthor

   More actions

   交付记录：官方基线对齐与 fork 镜像同步机制

   结论：位于 leonclab/opencodex 的远端基线已与官方 lidge-jun/opencodex 完全对齐，默认分支已切换为 dev，并沉淀了可一键执行、可自检的镜像同步脚本。

   1. 同步状态（已回读校验）

   分支	同步前	同步后	官方 upstream	差异	校验
   origin/dev	分支不存在	34ddb4d5f	upstream/dev 34ddb4d5f	0 / 0	✅ SHA 完全一致
   origin/main	584059132（v2.28.0）	7c625fc97	upstream/main 7c625fc97	0 / 0	✅ 纯 fast-forward

   • origin/dev：新建分支，首次推送 upstream/dev@d6c256ebef3dfb277c09a827e00b2329f41aac87；随后官方又前进 1 个提交（fix(release): pipeline correctness… #5388），由同步脚本自动前推至 34ddb4d5fdfebd94ba585b98e3ee31713c4f68cc。
   • origin/main：5840591322117f3ee9568b35b135a6d4339f7711..7c625fc9755c9824653ab944190e243091a2c85c，共 4260 个提交，fork 首页的 “4260 commits behind” 滞后提示已消除。
   • 校验方式：git rev-list --left-right --count origin/<branch>...upstream/<branch> 两侧均为 0 0，且 SHA 字符串相等，而非仅看提交计数。

   2. 默认分支

   gh repo view leonclab/opencodex --json defaultBranchRef 返回 {"name":"dev"}；本地 origin/HEAD 已同步指向 dev。

   注意顺序：改默认分支必须在 origin/dev 建立之后执行，否则会因分支不存在而失败。

   3. 常态化同步机制

   新增脚本 ~/.codex/bin/ocx-fork-mirror.sh。与既有 ocx-sync-upstream.sh 的分工：后者负责本机运行分支与 ocx service restart，本脚本只负责 fork 远端镜像，两者互不触碰。

   ocx-fork-mirror.sh check          # 只读漂移检查：已同步退出 0，有漂移退出 3
   ocx-fork-mirror.sh sync           # 仅 fast-forward 推送 upstream 的 dev/main 到 origin
   ocx-fork-mirror.sh sync --force   # 官方改写历史时，用 force-with-lease 把镜像分支拉回对齐

   契约（与主控线程既定纪律一致）：origin/dev、origin/main 为纯镜像，不承载任何本地提交；开发任务从 dev 拉出 codex/issue-<id>-<slug>，验证通过后直接向 upstream/dev 提报 PR。

   行为约束：默认拒绝非 fast-forward 推送，并明确提示需 --force；sync 成功后自动回读远端并断言 origin/<branch> == upstream/<branch>；目录非 git 仓库、参数非法、镜像分支领先上游分别以退出码 1/2/1 失败，漂移检查以 3 报告，不静默通过。

   验证证据

   • 隔离功能测试：在 /tmp 内构造上游仓 + 空 fork 仓，9 个场景全部通过——空 fork 首次建分支、fast-forward 前推、幂等 check 返回 0、漂移 check 返回 3、拒绝非 FF 且 fork 侧 stray 提交保持不变、--force 以 force-with-lease 拉回对齐、非法参数返回 2、路径不存在返回 1。
   • 真实仓库运行（当日实测）：

   === REAL check ===   📊 dev: 落后 1 / 领先 0  (origin=d6c256ebe → upstream=34ddb4d5f)   [check exit=3]
   === REAL sync ===    d6c256ebe..34ddb4d5f  upstream/dev -> dev
   ---- 同步后校验 ----
   ✅ origin/dev == upstream/dev (34ddb4d5f)
   ✅ origin/main == upstream/main (7c625fc97)
   [sync exit=0]
   第二次 check：✅ dev: 已对齐 ✅ main: 已对齐  [exit=0]
   

   4. 待决定 / 未完成项（均不在本次授权范围）

   1. 是否加定时自动化：当前机制是“开工或验收前跑一条命令”的纪律。若要无人值守定期同步，需要新的明确授权，因为它是定期的 GitHub 写入并涉及凭据与网络权限。
   2. tags 未镜像：本次只对齐 dev/main 两个分支，origin 上仍没有官方 tag（v2.5x–v2.60.0）。
   3. 本地 dev 分支仍在 d2808c061（2026-09-16），属本机运行环境范畴，由 ocx-sync-upstream.sh 负责，本次未改动。
   4. 本 Issue 正文尚无 Agent Provenance 映射表（该约定晚于本 Issue 创建）。本评论已按约定附上映射表与标签，是否把表回填进正文，请 Leon / 主控决定。

   Agent Provenance

   Agent	Role	Contribution	Profile	Model	Evidence
   codex（主控线程 01a0bf58）	main, planner	裁决基线对齐方案与 fork 跟踪纪律，拆解并派发本施工任务	unverified	unverified	本 Issue 正文与拆解评论
   codex（施工线程）	implementer, tester	新建 origin/dev、fast-forward origin/main、切换默认分支、编写并验证 ocx-fork-mirror.sh	unverified	unverified	本评论的实测输出；引用 SHA 34ddb4d5f / 7c625fc97

   Profile/Model 记 unverified 的原因：本线程 surface 未返回 effective model receipt，~/.opencodex/usage.jsonl 只按 conversationId 哈希记录，无法确定条目归属本线程，故按规范不填写推测值。

   Translated Message

   Original language: Chinese (Simplified)

   Delivery Record: Official Baseline Alignment and Fork Mirror Synchronization Mechanism

   Conclusion: The remote baseline located at leonclab/opencodex is now fully aligned with the official lidge-jun/opencodex, the default branch has been switched to dev, and a self-executable, self-checking mirror synchronization script has been established.

   1. Synchronization Status (Verified by Re-reading)

   Branch	Before Sync	After Sync	Official upstream	Difference	Verification
   origin/dev	Branch does not exist	34ddb4d5f	upstream/dev 34ddb4d5f	0 / 0	✅ SHA perfectly identical
   origin/main	584059132 (v2.28.0)	7c625fc97	upstream/main 7c625fc97	0 / 0	✅ Pure fast-forward

   • origin/dev: Newly created branch, initially pushed upstream/dev@d6c256ebef3dfb277c09a827e00b2329f41aac87; subsequently the official repository advanced by 1 commit (fix(release): pipeline correctness… #5388), automatically fast-forwarded by the sync script to 34ddb4d5fdfebd94ba585b98e3ee31713c4f68cc.
   • origin/main: 5840591322117f3ee9568b35b135a6d4339f7711..7c625fc9755c9824653ab944190e243091a2c85c, total of 4260 commits, the fork homepage's outdated "4260 commits behind" indicator has been eliminated.
   • Verification method: git rev-list --left-right --count origin/<branch>...upstream/<branch> both sides show 0 0, and SHA strings are equal, rather than just checking commit count.

   2. Default Branch

   gh repo view leonclab/opencodex --json defaultBranchRef returns {"name":"dev"}; local origin/HEAD has been synchronized to point to dev.

   Note the order: changing the default branch must be executed after origin/dev is established, otherwise it will fail because the branch does not exist.

   3. Ongoing Synchronization Mechanism

   New script added: ~/.codex/bin/ocx-fork-mirror.sh. Division of labor with existing ocx-sync-upstream.sh: the latter is responsible for local branch execution and ocx service restart, this script is only responsible for fork remote mirroring, they do not interfere with each other.

   ocx-fork-mirror.sh check          # Read-only drift check: exit 0 if synchronized, exit 3 if drift detected
   ocx-fork-mirror.sh sync           # Fast-forward push upstream dev/main to origin only
   ocx-fork-mirror.sh sync --force   # When official rewrites history, use force-with-lease to pull mirror branch back into alignment

   Contract (consistent with main control thread established discipline): origin/dev, origin/main are pure mirrors, no local commits; development tasks branch from dev to codex/issue-<id>-<slug>, submit PR directly to upstream/dev after verification.

   Behavior constraints: non-fast-forward pushes are rejected by default with clear prompts requiring --force; after sync succeeds, automatically re-read remote and assert origin/<branch> == upstream/<branch>; exit codes 1/2/1 for non-git directory/invalid parameters/mirror branch ahead of upstream respectively, drift check reports 3, no silent pass-through.

   Verification Evidence

   • Isolated functional testing: constructed upstream repo + empty fork repo in /tmp, all 9 scenarios passed—empty fork's first branch creation, fast-forward advancement, idempotent check returning 0, drift check returning 3, rejecting non-FF with fork-side stray commits remaining unchanged, --force using force-with-lease to pull back into alignment, invalid parameters returning 2, non-existent path returning 1.
   • Real repository execution (tested same day):

   === REAL check ===   📊 dev: 1 behind / 0 ahead  (origin=d6c256ebe → upstream=34ddb4d5f)   [check exit=3]
   === REAL sync ===    d6c256ebe..34ddb4d5f  upstream/dev -> dev
   ---- Verification after sync ----
   ✅ origin/dev == upstream/dev (34ddb4d5f)
   ✅ origin/main == upstream/main (7c625fc97)
   [sync exit=0]
   Second check: ✅ dev: aligned ✅ main: aligned  [exit=0]
   

   4. Pending Decisions / Incomplete Items (all outside scope of this authorization)

   1. Whether to add scheduled automation: Current mechanism is "run one command before work starts or before acceptance" discipline. If unattended periodic synchronization is needed, explicit new authorization is required, as it involves periodic GitHub writes and credentials/network permissions.
   2. Tags not mirrored: This session only aligned dev/main two branches, origin still has no official tags (v2.5x–v2.60.0).
   3. Local dev branch still at d2808c061 (2026-09-16), belongs to local runtime environment scope, managed by ocx-sync-upstream.sh, not modified in this session.
   4. This Issue body still lacks Agent Provenance mapping table (that convention was established after this Issue was created). This comment has attached the mapping table and labels per convention; whether to backfill the table into the issue body is for Leon/main control to decide.

   Agent Provenance

   Agent	Role	Contribution	Profile	Model	Evidence
   codex (main control thread 01a0bf58)	main, planner	Decided baseline alignment plan and fork tracking discipline, decomposed and dispatched this construction task	unverified	unverified	This Issue body and decomposition comments
   codex (construction thread)	implementer, tester	Created origin/dev, fast-forwarded origin/main, switched default branch, wrote and verified ocx-fork-mirror.sh	unverified	unverified	Test output in this comment; referenced SHA 34ddb4d5f / 7c625fc97

   Reason for unverified Profile/Model: this thread's surface did not return effective model receipt, ~/.opencodex/usage.jsonl only records by conversationId hash, cannot determine entry attribution to this thread, therefore per specification does not fill in speculative values.
4. leonclab

   added

   agent/codexWork involved the Codex agentWork involved the Codex agent

   role/implementerImplementation responsibilityImplementation responsibility

   role/testerVerification and testing responsibilityVerification and testing responsibility

   stage/ready-for-leonCurrent stage: waiting for Leon decisionCurrent stage: waiting for Leon decision

   on Sep 21, 2026
5. leonclab commented on Sep 22, 2026

   

   leonclab

   on Sep 22, 2026

   Last edited by github-actions

   OwnerAuthor

   More actions

   交付记录：方案 A（GitHub Actions 定时同步官方基线工作流）

   结论：已在特性分支 codex/issue-2-sync-upstream-workflow 中完成 GitHub Actions 定时同步工作流的落地，并通过 YAML 语法检验、基线逻辑推演与仓库级 CI 门禁回归。提交已推送到 origin (leonclab/opencodex)。

   ---

   1. 工作流设计与配置明细

   工作流文件：.github/workflows/sync-upstream.yml

   • 触发机制：
     • schedule: - cron: '0 20 * * *'：每天 UTC 20:00（北京时间次日凌晨 04:00）无人值守自动运行。
     • workflow_dispatch：支持在 GitHub Actions 网页端随时手动一键触发。
   • 并发与权限：
     • permissions: contents: write：具备向 fork 仓库镜像分支推送的权限。
     • concurrency: group: sync-upstream-baseline, cancel-in-progress: false：避免并发执行引起推送竞态。
     • timeout-minutes: 10：防挂起超时保护。
   • 纯 Fast-Forward 同步契约：
     • 动态添加/更新上游引用 upstream: https://github.com/lidge-jun/opencodex.git。
     • 获取 upstream 与 origin 的 dev、main 分支最新提交。
     • 计算 ahead（领先上游提交数）与 behind（落后上游提交数）：
       • 完全对齐 (behind==0 && ahead==0)：输出对齐提示，跳过推送；
       • 正常落后 (behind>0 && ahead==0)：纯 fast-forward 推送最新上游 refspec (refs/remotes/upstream/$branch:refs/heads/$branch) 到 origin；
       • 非 Fast-Forward 异常 (ahead>0)：打印警告并以退出码 1 中止，触发 GitHub Actions 运行失败报警邮件通知管理员，严防 fork 污染或历史分叉。
   • 同步后双端一致性校验：
     • 同步后自动重新拉取 origin，逐一断言 origin/dev == upstream/dev 与 origin/main == upstream/main 的 commit SHA。

   ---

   2. 验证证据

   1. YAML 语法与解析验证：
      • 使用 Bun 原生 YAML 解析器完成全量解析，结构符合 GitHub Actions Schema 规范，无语法或标量类型错误。
   2. 基线逻辑与真实分支比对实测：
      • 提取逻辑脚本针对当前真实远程引用执行干跑测试：
        • dev 分支准确识别到 upstream/dev 领先 32 个提交（由于官方主仓又有更新），触发 fast-forward 模拟；
        • main 分支识别到完全对齐（0 behind / 0 ahead），保持不变；
        • 逻辑判定退出码为 0。
   3. CI 门禁与工作流规范回归：
      • 运行 bun test tests/ci-workflows/repo-hygiene.test.ts tests/ci-workflows/ci-concurrency-groups.test.ts tests/ci-workflows/file-size-ratchet.test.ts tests/ci-workflows/structure-ssot.test.ts，全部 60 个测试用例 100% 通过：
        • 确认未引入任何 submodule 依赖；
        • 确认工作流 Actions 引用精确锁定为 40 字符 SHA (actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683)，符合 opencodex 严格的不可变依赖安全规则；
        • 文件尺寸与结构 SSOT 检查全部合规。
   4. 提交与 Agent Provenance 验证：
      • 经由 agent_git_commit.py 包装器提交，验证 Author 保留为 leon80900 <80900400+leon80900@users.noreply.github.com>；
      • 规范 trailer 自动注入且唯一：Agent-Generated-By: Codex；
      • 最终 commit SHA: 4acad892f。

   ---

   3. 后续步骤建议

   1. 特性分支 codex/issue-2-sync-upstream-workflow 已推送到 origin。
   2. 创建 PR 合入 leonclab/opencodex:dev（作为默认分支）。PR 合入到默认分支后，GitHub Actions 定时调度器即会在每日凌晨 04:00 自动生效执行。

   Agent Provenance

   Agent	Role	Contribution	Profile	Model	Evidence
   codex（主控线程 01a0bf58）	main, planner	裁决基线对齐方案与 fork 跟踪纪律，拆解并派发本施工任务	unverified	unverified	Issue #2 任务拆解与分派指令
   codex（施工线程 01a0c6b4）	implementer, tester	实现 .github/workflows/sync-upstream.yml 工作流、本地测试验证、提交标准 commit 并推送特性分支	unverified	unverified	commit 4acad892f，分支 codex/issue-2-sync-upstream-workflow

   Translated Message

   Original language: Simplified Chinese

   Delivery Record: Plan A (GitHub Actions Scheduled Synchronization of Upstream Baseline Workflow)

   Conclusion: Completed the implementation of GitHub Actions scheduled synchronization workflow in the feature branch codex/issue-2-sync-upstream-workflow, verified through YAML syntax validation, baseline logic deduction, and repository-level CI gate regression testing. Commits have been pushed to origin (leonclab/opencodex).

   ---

   1. Workflow Design and Configuration Details

   Workflow file: .github/workflows/sync-upstream.yml

   • Trigger Mechanisms:
     • schedule: - cron: '0 20 * * *': Automatic unattended execution daily at 20:00 UTC (04:00 Beijing Time next day).
     • workflow_dispatch: Support for manual one-click trigger anytime from GitHub Actions web interface.
   • Concurrency and Permissions:
     • permissions: contents: write: Permission to push to the fork repository mirror branch.
     • concurrency: group: sync-upstream-baseline, cancel-in-progress: false: Prevent concurrent execution race conditions.
     • timeout-minutes: 10: Timeout protection against hanging.
   • Pure Fast-Forward Synchronization Contract:
     • Dynamically add/update upstream reference upstream: https://github.com/lidge-jun/opencodex.git.
     • Fetch latest commits of dev and main branches from both upstream and origin.
     • Calculate ahead (commits ahead of upstream) and behind (commits behind upstream):
       • Perfect alignment (behind==0 && ahead==0): Output alignment notification, skip push;
       • Normal lag (behind>0 && ahead==0): Pure fast-forward push of latest upstream refspec (refs/remotes/upstream/$branch:refs/heads/$branch) to origin;
       • Non-fast-forward anomaly (ahead>0): Print warning and abort with exit code 1, trigger GitHub Actions failure alert email notification to administrators, strictly prevent fork contamination or historical divergence.
   • Dual-endpoint Consistency Verification Post-Synchronization:
     • Automatically re-fetch origin after synchronization, sequentially assert that origin/dev == upstream/dev and origin/main == upstream/main by commit SHA.

   ---

   2. Verification Evidence

   1. YAML Syntax and Parsing Verification:
      • Completed full parsing using Bun native YAML parser; structure complies with GitHub Actions Schema specification, no syntax or scalar type errors.
   2. Baseline Logic and Real Branch Comparison Testing:
      • Extracted logic script executed dry-run test against current real remote references:
        • dev branch accurately identified upstream/dev is 32 commits ahead (due to official upstream repository updates), triggered fast-forward simulation;
        • main branch identified as perfectly aligned (0 behind / 0 ahead), remained unchanged;
        • Logic judgment exit code is 0.
   3. CI Gate and Workflow Specification Regression:
      • Executed bun test tests/ci-workflows/repo-hygiene.test.ts tests/ci-workflows/ci-concurrency-groups.test.ts tests/ci-workflows/file-size-ratchet.test.ts tests/ci-workflows/structure-ssot.test.ts, all 60 test cases passed at 100%:
        • Confirmed no submodule dependencies introduced;
        • Confirmed workflow Actions references precisely pinned to 40-character SHA (actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683), complying with opencodex's strict immutable dependency security rules;
        • File size and structure SSOT checks all compliant.
   4. Commit and Agent Provenance Verification:
      • Submitted via agent_git_commit.py wrapper, Author verified as leon80900 <80900400+leon80900@users.noreply.github.com>;
      • Specification trailer automatically injected and unique: Agent-Generated-By: Codex;
      • Final commit SHA: 4acad892f.

   ---

   3. Recommended Follow-up Steps

   1. Feature branch codex/issue-2-sync-upstream-workflow has been pushed to origin.
   2. Create a PR to merge into leonclab/opencodex:dev (as the default branch). After the PR merges into the default branch, the GitHub Actions scheduled dispatcher will automatically take effect and execute daily at 04:00 AM.

   Agent Provenance

   Agent	Role	Contribution	Profile	Model	Evidence
   codex (main thread 01a0bf58)	main, planner	Determined baseline alignment plan and fork tracking discipline, decomposed and dispatched this construction task	unverified	unverified	Issue #2 task decomposition and dispatch instructions
   codex (implementation thread 01a0c6b4)	implementer, tester	Implemented .github/workflows/sync-upstream.yml workflow, local test verification, standard commit submission, and feature branch push	unverified	unverified	commit 4acad892f, branch codex/issue-2-sync-upstream-workflow