sync
Runs the full project sync pipeline — lifecycle update, audit, L0→L1 publish, commit, push, and PR creation.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- sync
- owner
- automation-engineer
- scope
- common
- status
- active
- version
- 1.9.1
- metadata
- { "type": "process", "triggers": [ "sync", "/sync", "commit and push", "create PR" ] }
- description
- Runs the full project sync pipeline — lifecycle update, audit, L0→L1 publish, commit, push, and PR creation.
- l2_propagate
- true
- last_reviewed
- 1794441600000
- prerequisites
- Bun runtime
03 SKILL.md 正文
Skill: sync
Context
Runs the full project sync pipeline (scripts/dev-sync.ts). This is the single mandatory pathway for all workspace commits — it handles lifecycle finalization, audit gating, L0→L1 template propagation, git branch creation, commit, push, and PR creation in one orchestrated flow.
When to Use
- After completing any set of file changes that should be committed, pushed, and PR'd
- When the user says "commit", "push", "create PR", "/sync", or "finish this branch"
- At the end of any execution plan row or multi-agent task
- As the final step in any workspace governance workflow (Phase 5/6 of the Harness Engineering Workflow)
Output Format
- A git branch
pr/<timestamp>-<slug>created (or reused) frommain - A commit with the task-staged files plus pipeline-generated files and a conventional commit message
- An open GitHub PR with the agent-written body (Why / What Changed / Test Plan / Security Checklist / Notes)
- Console output listing each pipeline step and its result
Execution Steps
-
Stage the task files (BEFORE invoking the pipeline):
git add <task files>. Only explicitly task-staged files plus files the pipeline itself generates (memory log, VERSION_MANIFEST, propagation output, ...) are committable. Dev-sync snapshots the working tree at start and at commit time. Any working-tree change that is neither task-staged nor pipeline-generated is EXCLUDED from the commit by default (scoped staging, T-20261001-015 soak exit; design:docs/designs/2026-09-12-dev-sync-scoped-staging-design.md) — stage everything the commit needs explicitly. To restore the legacy WARN-soak sweep, setSYNC_SCOPED_STAGING=0or pass--warn-staging. Never rely ongit add -Ato pick up your edits. Never leave unrelated dirt in the tree when syncing. -
Write the PR body (the agent writes it — never shell out to an LLM CLI):
-
Inspect the change:
git diff HEAD~1 --statandgit diff HEAD~1 --name-only(first 30 files). -
Write the body in English using EXACTLY this structure (keep all section headers, fill placeholders):
Why
[1-3 sentences: what problem does this solve and why now?]
What Changed
[concise bullet list of actual changes — be specific, not generic]
Test Plan
- [ ]
bun scripts/audit.tspasses - [ ] [add relevant manual or automated test steps]
Security Checklist
- [ ] No secrets, credentials, or API keys committed
- [ ] No
.envfiles staged (use.env.samplefor templates) - [ ] Dependencies unchanged or reviewed for new CVEs
Notes
[Breaking changes, deployment steps, or reviewer guidance. Write 'None' if not applicable.]
- [ ]
-
Save it to
<git-dir>/sync-pr-body.md, where<git-dir>isgit rev-parse --git-dir(e.g..git/sync-pr-body.md) — outside the working tree so it is never committed.
-
-
Run the sync script with the provided arguments, passing the body file:
bun scripts/dev-sync.ts --body-file "$(git rev-parse --git-dir)/sync-pr-body.md" "$ARGUMENTS"Branch behavior (dev-sync 1.27.0+; T-20261012-011 / T-20261013-005):
- On
main/masterthe pipeline creates a freshpr/<timestamp>-<slug>branch from the staged set — the PR title derives from the full branch-vs-main diff (origin/main...HEAD), never the message alone, so the review surface stays represented. - On an existing branch it commits there — unless that branch's PR is CLOSED (unmerged), which is refused: a dead branch under-represents the review surface (#1509's 45 files re-landed as a 1-file #1510). Re-branch from main and re-run.
- Prefer fresh branches for superseding deliveries: a reused branch can hit GitHub-server-side merge conflicts that a local 3-way merge reports clean (#1526 case). When
gh pr update-branchrefuses, re-branch the identical diff from current main, open a new PR, close the old one as superseded. - When
gh pr viewfails with 403/GraphQL (cloud sessions), dev-sync resolves the open PR via the REST API (1.28.0).
- On
-
The pipeline executes the following steps in order:
| Step | Name | Fatal? | Description |
|---|---|---|---|
| 0 | CWD Guard | FATAL | Verifies script runs from workspace root; exits if CWD mismatches import.meta.dir/.. |
| 1 | Language Gate | FATAL | Commit message / PR title must be English (context.md S3); blocks non-English via language-guard.ts |
| 2 | Memory Session Entry | FATAL | Appends session summary (changes, decisions, open issues) to memory/YYYY-MM-DD.md |
| 2 | MEMORY.md Index Sync | FATAL | Updates memory/MEMORY.md index via sync-md.ts |
| 2.5 | scripts/README.md Generation | FATAL | Regenerates scripts/README.md via generate-scripts-readme.ts if the script exists |
| 3 | CHANGELOG.md Check | FATAL | Checks CHANGELOG.md [Unreleased] — blocks and exits if empty (agent must add entries first via /changelog or manual edit) |
| 3.6 | Deprecated Script Warnings | non-fatal | Scans SCRIPTS.md for deprecated scripts and prints warnings |
| 3.7 | L0/L1 Script Drift Check | non-fatal | Runs verify-scripts.ts --check-drift to detect drift between L0 and L1 script copies |
| 3.8 | Memory File Archival | non-fatal | Runs archive-memory.ts to archive old memory files |
| 3.9 | Spec Registry Check | FATAL (L0) | Runs audit.ts --spec-check --lifecycle-only — blocks on the spec-relevance Fail (code diff with no spec activity; ADR-0055 Stage 2) and any always-on audit Fail; stale/missing-spec stay WARN; escape hatch --spec-exempt=E1-E5 (AGENTS.md §5.1.1); substantive LLM-assisted work must reach this gate through the PM routing path (ADR-0078); a missing docs/specs/registry.json is a loud WARN (gate INACTIVE — Universal Design Gate, ADR-0074; activate via spec-register.ts; the registry seed ships to projects add-if-missing) |
| 3.95 | QA Pre-checks | non-fatal | Runs project tests (if package.json has test script) and warns if README_ko.md is missing |
| 3.95b | Typecheck Gate | FATAL (L0) | Runs scripts/typecheck.ts — tsc --noEmit over scripts/ against the zero-error baseline (scripts/helpers/typecheck-baseline.json; T-20260910-012). Root context only; L1+ contexts skip cleanly via the missing-baseline guard. Never raise the error count — fix the error instead |
| 3.96c | Session-Evidence Skill Review | non-fatal | Runs skill-session-review.ts — accumulates Observed Symptom + Evidence from the day's ## Skills Used section into memory/skill-review/ (diagnosis/candidate left empty for human triage); plus a non-fatal full skill-dependency-analysis.ts --report pass (SkillHone-inspired loop; design doc docs/designs/2026-09-06-skill-session-review-design.md) |
| 3.97 | Governance Reflection Gate | FATAL (L0) | Runs verify-adr-governance.ts --strict — blocks sync when post-cutoff Accepted ADRs lack governance-doc references (ADR-0059 Stages 2+2b: unlinked-ADR and marker-drift findings block); skipped in scaffolded projects (L0-only validator) |
| 4.5 | L0 to L1 Publish | FATAL (L0) / non-fatal (L1) | Propagates scripts, skills, commands, docs via propagate-to-templates.ts --apply; fatal only in L0 context (context.md present) |
| 4.52 | Template Dependency Sync | FATAL (L0) | Runs sync-template-deps.ts --apply — aligns shared dependency versions from root package.json into templates/common/package.json and regenerates bun.lock (shared keys only; root-only deps never added, template-only deps never removed); workspace-root gated |
| 4.62 | Cascade Re-publish | FATAL (L0) / non-fatal (L1) | Re-runs propagate-to-templates.ts --apply after skill sync — heals template platform skill copies (templates/common/.claude/.gemini/.agents/skills) changed by step 4.6 within the same sync; same gating and fatality as step 4.5 |
| 4.6 | Skill Sync to Platforms | non-fatal | Runs sync-skills.ts to distribute skills to .claude/skills/, .gemini/skills/, .agents/skills/; warnings only |
| 4.7 | VERSION_MANIFEST.md Generation | FATAL | Generates VERSION_MANIFEST.md via generate-version-manifest.ts |
| 4.85 | Version-Bump Test Gate | FATAL | When the task-staged change set bumps a version (a SKILL.md frontmatter version: line or a script @version header line changed), runs bun run test:unit BEFORE the audit gate; a failing suite blocks the sync. Skipped cleanly when package.json has no test:unit script (L1+ projects) and when nothing staged bumps a version. No escape env var — fix the tests or unstage the bump (detection: scripts/helpers/version-bump.ts; user directive 2026-10-08) |
| 4.9 | AUDIT GATE | FATAL | Runs audit.ts — must exit 0 before proceeding. Includes the auto-activating gates: skill-graph drift (ADR-0060) and upgrade coverage (check-upgrade-coverage.ts --strict, ADR-0073) |
| 5 | Branch Creation | FATAL | Creates pr/<timestamp>-<slug> branch if on main/master; reuses existing branch otherwise |
| 6 | Sensitive File Guard + Scoped Staging + Commit/Push | FATAL | Guards against .pem, .key, .env, credentials.json, etc.; scoped-staging check (S0/S1 tree snapshots — WARN-lists files that are neither task-staged nor pipeline-generated; excluded by default; SYNC_SCOPED_STAGING=0/--warn-staging restore the legacy sweep), then git add, git commit, git push |
| 7 | PR Creation | FATAL | If --body-file was passed, validates it (English) and opens the PR via gh pr create --body-file; otherwise falls back to gen-pr-body.ts template, .github/pull_request_template.md, then gh pr create --fill; idempotent — updates existing PR if one already exists for the branch |
- If audit fails, fix the reported issue before re-running.
Worktree Landing Variant
When concurrency evidence exists (shared tree dirty, shared checkout off main, or any open PR), land multi-file write batches from an isolated worktree instead of the shared checkout. Full rule set and rationale: docs/designs/2026-11-07-session-worktree-convention-design.md (T-20261106-010). PM bookkeeping (ticket moves, memory-log-only, CHANGELOG entries) and trivial single-file changes stay on the shared checkout.
- Concurrency check: run
git status --porcelain,git branch --show-current, andgh pr list --state open. Any hit selects this variant. - Create the worktree:
git fetch origin && git worktree add ../<repo-name>-worktrees/<slug> -b pr/<YYYYMMDD>-<slug> origin/main. Keep the path outside the repository tree: no.gitignorechange is needed and worktrees never appear in the repo's own untracked-file surface. - Install:
cd <worktree-path> && bun install. A fresh worktree has nonode_modules. - Work: perform all writes inside the worktree. Never edit shared-checkout paths from the worktree session.
- Stage + PR body: stage task files explicitly (step 0 scoped-staging rules unchanged). Write the PR body to
$(git rev-parse --git-dir)/sync-pr-body.md. Inside a worktree,git rev-parse --git-dirresolves to the worktree's private git dir (<repo>/.git/worktrees/<name>), so the body file is per-worktree and never collides with a concurrent session's file. - Sync: run
bun scripts/dev-sync.ts --body-file "$(git rev-parse --git-dir)/sync-pr-body.md" "$ARGUMENTS"from the worktree root. The CWD guard (step 0 of the pipeline) compares CWD against the script's own copy's parent directory (import.meta.diranchor), and each worktree owns a full checkout includingscripts/dev-sync.ts, so the guard passes by construction. This supersedes the 2026-11-03 "in-worktree dev-sync is impossible" observation, which was a CWD/script-root mismatch, not a fundamental incompatibility. On the pre-created branch, the pipeline commits there (step 2 branch behavior applies unchanged). - PR: the pipeline pushes and opens or updates the PR as usual. CI runs against the branch - identical to a shared-checkout landing.
- Cleanup: after the PR opens (or merges, per the finishing-branch discipline), run
git worktree remove <worktree-path>from the shared checkout. The shared tree is never touched during the session. - Report: state the worktree path, the branch, and the concurrency evidence observed at start in the task report.
Session Evidence Duty (## Skills Used)
While the session is still open — BEFORE invoking /sync — record the skills
actually loaded this session into memory/YYYY-MM-DD.md under ## Skills Used
(one block per skill; schema in the skill-lifecycle standards, §6.6
Session-Evidence Skill Review Loop, and docs/designs/2026-09-06-skill-session-review-design.md). If the section was not filled before
sync, the dev-sync step 2 skeleton is appended as a comment for later editing.
Step 3.96c consumes this evidence automatically; it never modifies skills.
Related Skills
scripts/dev-sync.ts— Core sync pipeline implementationskills/gateguard/SKILL.md— Pre-edit quality gate (run before edits that lead to sync)context.md §3— PR workflow and branch rules
PR Language Rule
All PR titles and bodies generated by this command must be written in English, regardless of the active session language. This applies to the agent-written body in step 1 and to any gh pr create / gh pr edit calls — dev-sync.ts blocks non-English bodies at the same language-guard gate used for commit messages.
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.