pensieve-sync-to-main

Pensieve Sync to Main

Use only inside the Pensieve repository itself.

This skill syncs changes from experimental or zh into main, preserves contributor history, and ensures main remains the English release branch. This is a maintainer release flow, not a default pipeline that should be seeded into every Pensieve user project.

Hard Rules

• main must remain English-only and release-grade.
• Preserve source-branch commit history; do not squash contributor history unless the user explicitly asks.
• Code logic must stay identical across language branches; only text content may differ.
• Do not translate code identifiers, paths, protocol names, command names, frontmatter keys, or Markdown link targets unless the branch rules below explicitly require it.
• When the worktree has unrelated local changes, do not run destructive git cleanup commands.

Branch Strategy

• experimental: development branch
• zh: Chinese release branch
• main: English release branch

Default source branch is zh unless the user explicitly specifies experimental. Default remote is kingkongshot.

Translation Scope

Chinese content in these files must be translated into English:

• README.md
• SKILL.md
• .src/references/*.md
• .src/tools/*.md
• .src/templates/**/*.md

These files are synced directly by default; translate only if user-visible Chinese appears on the English branch:

• Scripts and code
• JSON/YAML configuration
• Deleted files
• Binary assets

Workflow

1. Confirm scope

1. Check current state:

   git branch --show-current
   git status --short
   git remote -v
   

2. Confirm source branch:

   git fetch kingkongshot
   git diff --stat main..kingkongshot/<source-branch>
   

3. Classify changed files as: needs translation, direct sync, deletion, binary/config.
4. If the worktree has unrelated local changes, report them before switching branches.

2. Create sync branch

1. Start from latest main:

   git checkout main
   git pull kingkongshot main
   git checkout -b sync/zh-to-main-<date>[-topic]
   

2. Merge the source branch to preserve history:

   git merge kingkongshot/<source-branch> -X theirs --no-edit
   

3. If the user explicitly asks to sync only a few files, use targeted checkout:

   git checkout kingkongshot/<source-branch> -- <file>
   

4. Resolve conflicts before translating.

3. Translate

Rules:

• Translate all Chinese prose into English.
• Preserve Markdown structure, frontmatter, code blocks, command syntax, and HTML tags.
• Preserve intentionally bilingual matching regexes, such as the Exploration Reduction compatibility check.
• Installation commands in English-branch docs must use git clone -b main, not git clone -b zh.
• English-branch language-switch links should point back to the Chinese README.
• Translate Chinese strings in scripts only when they are user-visible on the English branch.

Validation:

rg -n --pcre2 '\p{Han}' README.md SKILL.md .src docs

After translation, results may only include intentionally retained Chinese, such as language-switch links or bilingual regexes.

4. Validate, commit, and open PR

1. Run checks that exist in the current repository:

   git diff --check
   

2. Commit:

   git add -A
   git commit -m "translate: sync <source-branch> to main"
   

3. Push and create a PR:

   git push kingkongshot sync/zh-to-main-<date>[-topic]
   gh pr create --repo kingkongshot/Pensieve --base main --head sync/zh-to-main-<date>[-topic]
   

4. Unless the user explicitly delegated the full release flow, ask for confirmation before merging the PR.

Failure Fallback

• Merge conflicts remain: stop, list conflict files, and resolve them directly. Prefer source-branch content, then translate.
• Chinese remains after translation: inspect each item, translate it, or explain why it is intentionally retained.
• Push rejected: fetch, rebase the sync branch onto latest kingkongshot/main, then retry.
• GitHub CLI authentication fails: report the exact authentication error; do not switch to an unknown remote.