Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
## Problem and resulting behavior

<!-- Describe the concrete problem, final behavior, scope, and material limitations. -->

## Task and verification evidence

- Worktree / branch:
- Base SHA / tested head SHA:
- Local checks and results:
- CI results for this head:
- Screenshots for UI changes:
- Missing prerequisites, skipped checks, and remaining limitations:

<!-- Documentation-only: docs:check plus diff, command, and link review.
Run applicable implementation checks for code, test, tooling, or CI changes.
Preview/production publication needs authorization; FlareMail PRE is not required.
Exclude tokens, raw mutation payloads, Workspace documents, and private configs. -->

## Review gate (update before merge)

- [ ] Codex Code Review completed for the current head; author and SHA verified.
- [ ] Security Review and other required reviews completed when enabled;
actual repository configuration checked.
- [ ] Review SHA, completion times, and evidence links recorded below.
- [ ] Valid blocking findings resolved; false positives explained with evidence.
- [ ] Required CI checks passed for the current head; new commits reviewed again.

Review evidence:

## Merge and completion (update after authorized merge)

<!-- Default: rebase merge pinned with --match-head-commit; no --admin bypass.
Wait for MERGED, verify merge SHA and patches in origin/main, then sync a
clean main checkout with --ff-only. Retain unmerged work and unsaved files.
Remove this task's worktree and branches only after integration is proven;
remote deletion requires an explicit lease pinned to the merged PR head.
Follow AGENTS.md and docs/wiki/Development.md for checks and exceptions.
Merge and cleanup do not deploy production. -->

- Merge authorization / PR URL / original head / merge SHA:
- Main integration and sync evidence:
- Worktree and local/remote branch cleanup, retention, or blockers:
90 changes: 89 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,91 @@
# Codex Context - SubMan

## Default Development Workflow

Use this workflow for every feature, fix, refactor, test, configuration, and
documentation change, including small updates:

**Dedicated local worktree + task branch -> local implementation and verification
-> atomic commit -> push and PR -> completed review and resolved findings
-> rebase merge into `main` -> verify and sync main -> remove the merged task
worktree and local/remote branches.**

- Before editing, inspect cwd, branch, upstream, working tree, and
`git worktree list`. Fetch and verify the latest `origin/main`, then create a
dedicated worktree and new `feat/<topic>`, `fix/<topic>`, or `docs/<topic>`
branch. Resume an existing task in its own worktree/branch. Do not develop on
`main` or switch the user's original checkout to the task branch.
- Place worktrees outside the repository, in a sibling or writable temporary
directory. Record the absolute path, branch, and base SHA. Isolate dependencies,
generated output, local Worker/DO state, browser state, and server ports. Do not
share writable build directories or automatically copy private configs/tokens.
- Preserve unrelated changes. Do not reset, stash, rebase, force-push, or delete
another task's work. Keep unmerged worktrees and branches for continuation.
- Validate locally and create an atomic Conventional Commit before any authorized
push/PR. Target PRs at `main`; include the problem, resulting behavior, base and
tested SHAs, validation evidence, and limitations. Use a temporary body file
with `--body-file` for multiline GitHub CLI descriptions.
- After opening a PR or updating its head, actively check Codex bot review.
Every PR, including documentation, requires completed Code Review of the
current head and resolution of valid blocking findings. Verify the actual bot
author (`chatgpt-codex-connector[bot]`, sometimes displayed without `[bot]`),
reviewed SHA, completion evidence, and inline findings. Also require Security
Review and any other configured required reviews when enabled; verify actual
repository configuration rather than assuming FlareMail's settings apply.
- Check each review item and its commit in `Codex Review Summary` and associated
reviews/comments. A single summary status/head SHA, `COMMENTED`, a reaction,
`CLEAN` mergeability, empty Actions checks, or an older review does not prove
completion. Review not appearing yet does not prove it is disabled. New commits
require new review and affected checks. Record review SHA, completion time, and
links; explain false positives with evidence. If review is pending, failed, or
cannot be verified, retain the PR/branch/worktree and report the blocker. Do not
bypass review by waiting out a timeout or enabling auto-merge early.
- Push, PR creation, merge, direct pushes to `main`, Wiki publication, and
deployment require authorization covering those actions. This workflow defines
order, not additional authorization; do not ask again for an already authorized
action within the same scope. Ordinary development does not authorize remote
publication or production deployment. SubMan keeps its existing CI and local
checks; FlareMail's PRE requirement is not a SubMan gate.

### Rebase Merge and Cleanup

1. Before an authorized merge, verify the target `main`, PR head, commits/files,
mergeability, required checks, and completed current-head reviews. Default to
`gh pr merge <PR> --rebase --match-head-commit <VERIFIED_HEAD_SHA>` unless the
user specifies another strategy. Do not use `--admin` to bypass gates. A queue
or auto-merge request is not a completed merge; wait for actual `MERGED` state.
2. Record PR URL, original head, and merge SHA. Fetch `origin/main` and verify it
contains the merge SHA and all task changes. Rebase rewrites commit identities;
use the PR merge record plus patch/content comparison, such as `git range-diff`
of the original and rebased ranges. Original-head ancestry alone is inadequate.
Repeat affected checks when conflict resolution or integration changes content.
3. Sync the original checkout with `git merge --ff-only origin/main` only if it
is on `main`, clean, and can fast-forward. Preserve a dirty/diverged checkout
and report it without reset, stash, or automatic rebase. Independently safe
cleanup of a verified merged task may still proceed.
4. After a verified authorized merge, clean up this task by default unless the
user requests retention. Verify task branches still point to the merged PR
head with no new commits. Check staged, unstaged, untracked, and valuable
ignored files; preserve private configuration and validation evidence, and
stop temporary services. From a retained checkout, use
`git worktree remove <PATH>` without `--force`, then `git branch -d <BRANCH>`.
Never remove the main checkout or another task's worktree.
5. Delete a remaining remote task branch only with an explicit lease pinned to
the verified merged PR head:
`git push --force-with-lease=refs/heads/<BRANCH>:<VERIFIED_HEAD_SHA> origin :refs/heads/<BRANCH>`.
This permits conditional deletion, not history overwrites. Do not use
unconditional `--delete` or `--force`. If absent, record it; if the lease fails,
preserve the branch and report it without retrying against an unmerged head.
6. If local `-d` refuses only because rebase changed ancestry, `-D` is permitted
only after proving PR `MERGED`, merge SHA in main, unchanged task head, and
equivalent patches/content. A successful `-d` alone is not integration proof.
Unsaved files, unmerged commits, another worktree using the branch, or a user
retention request stop the affected cleanup. Report PR URL, final SHA,
validation, main sync, cleanup, and remaining blockers. Merge/cleanup do not
deploy production.

Commands and examples: [development guide](docs/wiki/Development.md).

## Product

SubMan manages VLESS, VMess, and related proxy resources. The sole business
Expand Down Expand Up @@ -215,7 +301,9 @@ green. Vite is for UI iteration; use `dev:cf` for Worker/DO runtime evidence.
- Keep code identifiers and comments ASCII.
- Add behavior tests before changing established protocol behavior.
- Commit each independent feature, UI change, refactor, or bug fix immediately
with an atomic Conventional Commit.
after applicable verification with an atomic Conventional Commit in its task
worktree. Documentation-only changes require `bun run docs:check` plus diff,
command, and link review; runtime checks apply when implementation changes.
- Keep README concise. Maintain detailed guides in the bilingual Wiki sources
indexed by `docs/wiki/Home.md`; record changes in both `docs/wiki/Changelog.md`
and `docs/wiki/Changelog.zh-CN.md`. Run `bun run docs:check` before committing.
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ See the [user guide](docs/wiki/User-Guide.md) for setup and recovery.

## Local development

Use a dedicated worktree and task branch for every change. PRs require current-head
review before an authorized rebase merge; verify main, then clean up merged task
branches and worktrees. Follow the [development workflow](docs/wiki/Development.md#worktree-and-pr-workflow).

Use Bun **1.3.14**:

```bash
Expand Down
3 changes: 3 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ Token 默认仅在当前会话保存,持久保存需主动选择。

## 本地开发

每项改动使用独立 worktree 和任务分支。PR 完成当前 head 的 review 后按授权 rebase 合并,
核对主分支后清理已合并任务的分支和 worktree,详见[开发流程](docs/wiki/Development.zh-CN.md#worktree-与-pr-工作流)。

使用 Bun **1.3.14**:

```bash
Expand Down
9 changes: 9 additions & 0 deletions docs/wiki/Changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,15 @@ production deployment and real-provider acceptance require separate evidence.

## Unreleased

### 2026-10-26 - Worktree and PR development workflow

- Adopted FlareMail's task isolation, current-head Codex review, rebase merge,
main verification/sync, and merged worktree/branch cleanup conventions.
- Added a PR template and bilingual workflow instructions, including conditional
remote branch deletion and rebase-aware integration checks.
- Kept SubMan's CI, Bun version, and publication/deployment authorization rules;
repository instructions do not configure GitHub review integrations or rulesets.

### 2026-10-26 - API and sing-box-vps compatibility review

- Clarified tiered Gist discovery and nonempty PATCH inputs in OpenAPI and the
Expand Down
8 changes: 8 additions & 0 deletions docs/wiki/Changelog.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@

## 未发布

### 2026-10-26 - Worktree 与 PR 开发工作流

- 参考 FlareMail,统一任务隔离、当前 head 的 Codex review、rebase 合并、
主分支核对/同步及已合并 worktree/分支清理约定。
- 增加 PR 模板和双语操作指南,明确远端分支条件删除与 rebase 后的整合核对。
- 保留 SubMan 的 CI、Bun 版本和发布/部署授权规则;
仓库约定不等于已配置 GitHub review 集成或 ruleset。

### 2026-10-26 - API 与 sing-box-vps 兼容性核对

- 在 OpenAPI 和中英文 API、Agent 参考中明确分层 Gist 发现策略与非空 PATCH 要求,
Expand Down
131 changes: 131 additions & 0 deletions docs/wiki/Development.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,130 @@

English | [简体中文](Development.zh-CN.md) · [Wiki home](Home.md)

## Worktree and PR workflow

Every task, including small fixes and documentation, uses this sequence:

**Dedicated worktree + task branch -> local implementation and verification
-> atomic commit -> push and PR -> completed review and resolved findings
-> rebase merge into `main` -> verify and sync main -> remove merged task
branches and worktree.**

Push, PR creation, merge, direct pushes to `main`, Wiki publication, and deployment
require authorization covering those actions. The sequence does not grant it;
existing authorization within the same scope does not need confirmation again.
SubMan retains its current CI and local checks. FlareMail's PRE acceptance gate
is not required here, and ordinary development does not publish or deploy.

Before editing, inspect the original checkout, fetch and verify `origin/main`,
then create a new task branch and separate checkout. Replace the example topic
and path for each task:

```bash
pwd
git status --short --branch
git rev-parse --abbrev-ref --symbolic-full-name '@{u}'
git worktree list
git fetch origin main
git rev-parse origin/main
git worktree add -b feat/topic ../SubMan-topic origin/main
cd ../SubMan-topic
```

Use `fix/<topic>`, `docs/<topic>`, or another Conventional Commit type as
appropriate. Record the absolute worktree path, branch, and base SHA. Resume an
existing task in its existing worktree; use another base only when requested.
Keep the original checkout intact and do not develop directly on `main`.
Preserve unrelated changes without reset, stash, or rewriting another task's history.

Install locked dependencies in the task worktree. Keep `.svelte-kit`, `build`,
`.wrangler` (including local DO SQLite), browser state, and ports isolated.
Do not share writable generated directories or copy private configs/credentials
automatically. Implement, run applicable checks below, and create an atomic
Conventional Commit. With authorization, push the task branch and open a PR to
`main` using the repository PR template. Describe the problem, final behavior,
base and tested SHAs, validation evidence, and limitations. For multiline GitHub
CLI bodies, write a temporary file and pass `--body-file`.

## Review before merge

Every PR, including documentation/instruction changes, requires completed Codex
Code Review of the current head. After PR creation or any new commit, actively
check whether review has started. Verify actual repository review configuration;
FlareMail's enabled integrations do not establish SubMan's settings. Require
Security Review and any other configured required reviews when enabled. Missing
review activity does not prove an integration is disabled.

Verify the actual author (`chatgpt-codex-connector[bot]`, sometimes shown without
`[bot]`), reviewed commit, completion time, and result links. Inspect each review
item's status and commit in `Codex Review Summary`, submitted reviews, and inline
findings. A single summary status/head SHA does not establish every review's
completion. `CLEAN`, empty Actions checks, `COMMENTED`, reactions, and old-head
reviews are insufficient. Required CI checks and bot review are separate gates.

Fix valid blocking findings and rerun affected checks; document evidence for false
positives or inapplicable findings. Any new commit requires review of the new head.
Pending, failed, or unverifiable review means retaining the PR, branch, and worktree
and reporting the blocker. Elapsed time does not waive review. Do not enable
auto-merge before all gates have passed.

## Rebase merge and cleanup

For an authorized merge, verify the PR targets `main`, inspect its head SHA,
commits/files, mergeability, required CI checks, and current-head reviews. Default
to rebase unless another strategy was requested; lock the merge to the verified
head:

```bash
gh pr merge <PR> --rebase --match-head-commit <VERIFIED_HEAD_SHA>
```

Do not bypass checks with `--admin`. A merge queue or auto-merge request is not
completion; confirm PR state `MERGED` before cleanup. Record the PR URL, original
head SHA, and merge SHA. Fetch `origin/main` and verify it contains the merge SHA
and all task changes. Rebase changes SHA identities: compare original and rebased
commit ranges with patch/content checks such as `git range-diff`. Neither original
head ancestry nor a successful push proves integration. Do not compare the entire
task tree to a main branch that also contains unrelated changes. Content changes
from conflict resolution or integration require affected verification again.

From the preserved original checkout, sync only when it is on `main`, clean,
and can fast-forward:

```bash
git merge --ff-only origin/main
```

Keep dirty/diverged main checkouts intact and report the limitation; do not reset,
stash, or automatically rebase. Independently safe task cleanup may still proceed.
After a verified authorized merge, cleanup is part of completion unless the user
requests retention:

1. Verify remaining local and remote task branches still point to the merged PR
head with no later commits. Inspect staged, unstaged, untracked, and valuable
ignored files. Preserve validation evidence and private configuration outside
the disposable worktree; stop its temporary services. Never remove another
task's worktree or the main checkout.
2. From a retained checkout, run `git worktree remove <PATH>` without `--force`,
then `git branch -d <BRANCH>`. Do not combine cleanup with the merge command;
verify each result separately.
3. Delete a remaining remote branch only with a lease pinned to the verified
merged PR head:
`git push --force-with-lease=refs/heads/<BRANCH>:<VERIFIED_HEAD_SHA> origin :refs/heads/<BRANCH>`.
This is conditional deletion, not permission to overwrite history. Do not use
unconditional `--delete` or `--force`. If already absent, record that result.
A rejected lease means preserving the branch and reporting it; do not retry
deletion using a newer unmerged head.
4. If `-d` refuses solely because rebase changed ancestry, `-D` is allowed only
after proving PR `MERGED`, merge SHA in main, unchanged task head, and equivalent
patches/content. A successful `-d` alone is not integration proof. Unmerged
commits, unsaved files, another worktree using the branch, or a retention
request stop the affected cleanup.
5. Verify PR state, local/remote main SHAs, working tree status, and removal of
task branches/worktree. Report PR URL, final SHA, validation, sync and cleanup
results, and blockers. Retain unmerged tasks. Merge and cleanup do not deploy
production.

## Toolchain and local servers

Use Bun **1.3.14**, matching `package.json` and CI:
Expand Down Expand Up @@ -32,6 +156,13 @@ tests use synthetic data and mocks; do not add a real GitHub token for test writ

## Verification

For documentation/instruction-only changes, run `bun run docs:check` and review
the diff, commands, and links. Runtime tests and remote deployment are not needed.
Implementation, test, tooling, or CI changes require applicable checks below;
report missing prerequisites or failures rather than claiming a pass. Run checks
that share generated files (`check`, build, Worker tests, type generation, and
browser tests) sequentially in each worktree.

```bash
bun run docs:check
bun test
Expand Down
Loading
Loading