[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M73BMV64HCFSQQ344FPNH2QF":3,"skill-same:01M73BMV64HCFSQQ344FPNH2QF":66},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":6,"ownerHtmlUrl":49,"ownerBlogUrl":6,"ownerDescription":50,"updatedAt":51,"install":52,"resources":65},"01M73BMV64HCFSQQ344FPNH2QF","upgrade-project",null,"Upgrade an existing L2\u002FL3 project to the current template version. Use when: upgrading a variant-based project, syncing template improvements, refreshing scripts\u002Fagents\u002Fskills\u002Fdocs\u002Fcommands.","5throck\u002Fai-workspace-standards","5throck","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F10958964?v=4","01M73BFEH0V0VS483TW4JD49JW","01M73BFEJ5VQZJHJSFTVPAZGDM",25,"AGPL-3.0","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fupgrade-project\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: upgrade-project\ndescription: \"Upgrade an existing L2\u002FL3 project to the current template version. Use when: upgrading a variant-based project, syncing template improvements, refreshing scripts\u002Fagents\u002Fskills\u002Fdocs\u002Fcommands.\"\nversion: 1.6.2\nstatus: active\nscope: workspace\nowner: pm\nlast_updated: 2026-10-26\nlast_reviewed: 2026-10-31\nrelates_to:\n  - skill: promote-variant\n    type: follows\n  - skill: project-resync\n    type: composes_with\nmetadata:\n  type: scaffolding\n  triggers:\n    - upgrade project\n    - upgrade template\n    - sync project with template\n    - refresh project\n    - update project infrastructure\n---\n\n# Upgrade Project\n\nUpgrades an existing project created from a variant template to match the current template version.\n\n## When to Use\n\n- The workspace template has been updated with new scripts, agent improvements, or security fixes\n- A project needs to receive the latest governance or automation infrastructure\n- Periodic maintenance to keep projects in sync with template evolution\n\n## Prerequisites\n\n- The project must have been created from a `co-*` variant template\n- The project must be a git repository\n- `bun` must be installed\n\n## Script\n\n**Script**: `scripts\u002Fupgrade-project.ts` (see the `@version` header in the script)\n**Location**: Workspace root only (`L0` per ADR-0073 Amendments 1, 3 and 4 — projects do not carry a copy; from inside a project use `bun ..\u002F..\u002Fscripts\u002Fupgrade-project.ts .`)\n**Usage**: `bun scripts\u002Fupgrade-project.ts \u003Cproject-path> [--variant \u003Cname>] [--platform claude|antigravity|codex|all] [--dry-run] [--prune-removed] [--rollback] [--yes] [--skip-context-commonization] [--force-context-sync]`\n\n### Arguments\n\n| Argument | Required | Description |\n|----------|----------|-------------|\n| `\u003Cproject-path>` | Yes | Path to the target project. A path that resolves to the workspace ROOT is rejected (root is L0, not a project); targets outside `Projects\u002F` print a warning |\n| `--variant \u003Cname>` | No | Auto-detected from `.claude\u002Ftemplate-version.txt` |\n| `--platform \u003Cval>` | No | `claude`, `antigravity`, `codex`, or `all` — all three platforms (default: `all`; `both` was renamed to `all` in v1.34.0) |\n| `--dry-run` | No | Analyze without making changes |\n| `--prune-removed` | No | Remove files present in project but absent from template (falls back to a direct delete when `git rm` fails on untracked files) |\n| `--rollback` | No | Restore pre-upgrade git stash snapshot; exits 1 when the restore fails. Under `--dry-run` it prints a no-op plan instead |\n| `--yes` | No | Skip the proceed prompt when `template-version.txt` is missing |\n| `--skip-context-commonization` | No | Opt out of the CONTEXT_COMMONIZATION pass for this run |\n| `--force-context-sync` | No | Take the template `docs\u002Fcontext.md` even when the project copy carries project-only content (the discarded section count is logged) |\n| `--changelog-entry` | No | Opt-in (default OFF): scaffold one editable `chore(upgrade): template sync` bullet at the top of the project CHANGELOG's `[Unreleased]` section for this delivery (idempotent per template version; apply-mode only — refused under `--dry-run`; spec 2026-10-29-delivery-bookkeeping-engine A3). The daily resync runner and operator upgrade sessions pass it by convention |\n\n## How It Works\n\nThe upgrade tool classifies files into categories:\n\n| Category | Behavior | Examples |\n|----------|----------|---------|\n| **LOCKED** | Unconditional overwrite | Git hooks, `.gitleaks.toml`, `.gitattributes` |\n| **MERGE** | Section-based merge via markers | `CLAUDE.md`, `GEMINI.md`, `.gitignore`, `agents\u002Fpm.md` |\n| **DOCS_MERGE** | Section-based merge (managed blocks) | `AGENTS.md`, `docs\u002F\u003Cvariant>.context.md` |\n| **DOCS_OVERWRITE** | Plain overwrite (no blocks) | `docs\u002Fphase-definitions.md` |\n| **VARIANT_DOCS_SYNC** *(folded v1.22.0)* | No longer a separate pass — its files (`docs\u002Fcontext.md` and the shared docs pair set) are delivered by **TEMPLATE TREE SYNC**'s default SYNC policy with identical inline-version\u002Fhash\u002Fconflict semantics | — |\n| **TEMPLATE TREE SYNC** | Default-policy delivery for template files no dedicated pass claims: add-if-missing, then inline-version\u002Fhash update with conflict warning. `JSON_MERGE` deep-merges platform settings (project-only array entries preserved; template hook entries whose command references a path absent from the project are dropped — the trail-migration guard, design 2026-10-31-graft-trail-migration R2.4); `ADD_IF_MISSING` seeds (`.codex\u002Fconfig.toml`, graft surfaces) never overwrite, and when the project carries `.trail\u002F` (the trail-migration marker) the graft-era seeds (`.mcp.json`, `graft-hooks.cjs`, `graft-statusline.cjs`) are RETIRED — `SEED_SKIP` (retired-surface), never re-seeded; `WORKSPACE` seeds (`docs\u002Fdesigns\u002F`, `docs\u002Flifecycle\u002F`, …) are add-if-missing only | Rest of the `docs\u002F` tree (`user-guide`, variant domain docs, `countries\u002FKR.md`, `skill-graph.overrides.json`), `.github\u002F`, `.claude`\u002F`.gemini\u002Fsettings.json`, `.mcp.json`, `opencode.json`, `.editorconfig`, platform `skills.json` |\n| **ENV_SAMPLE SYNC** *(since v1.23.0)* | Country-aware MERGE delivery of `.env.sample`: template content with `# >>> country-scoped:\u003CCC>` blocks pruned to the project's detected country (region-neutral = all blocks stripped, matching scaffold posture); same-NAME keys superseded by the template line, project-only keys preserved under a marker section (idempotent); standard conflict warning on locally-modified copies | `.env.sample` |\n| **CONTEXT_COMMONIZATION** *(since v1.20.0)* | After `docs\u002Fcontext.md` refreshes, near-duplicate top-level sections of `docs\u002F\u003Cvariant>.context.md` are pruned: token-overlap >= 0.65 → REMOVE (logged), >= 0.30 → REVIEW (manual Context Commonization Review, ADR-0050 Part 3 — never auto-removed), below → silent. Sections containing managed COMMON-*\u002FVARIANT-INJECT content downgrade to REVIEW; managed zones and the version footer are excluded. Comparison reads the template source, so dry-run verdicts match apply | `docs\u002F\u003Cvariant>.context.md` |\n| **GOVERNANCE FILES SYNC** *(since v1.12.0)* | Strictly add-if-missing delivery of top-level governance files from the variant template, then `templates\u002Fcommon`. An existing project file is always preserved (licenses are intentionally forkable) | `LICENSE`, `SECURITY.md` |\n| **COMMANDS_SYNC** | Hash-based sync | `.claude\u002Fcommands\u002F*.md`, `.gemini\u002Fcommands\u002F*.md` |\n| **SYNC_IF_NEWER** | Version-based update | Scripts (`.ts`), agents (`.md`), skills (`SKILL.md`) |\n| **PRESERVE** | Never touched | `README.md`, `src\u002F` |\n| **OVERWRITE** | Governance files | `docs\u002F_common\u002Fsecurity.md` |\n\n> **Path note**: the `docs\u002F...` paths in the tables above (`docs\u002Fcontext.md`, `docs\u002Fphase-definitions.md`, `docs\u002Fengagement-orchestration.md`, `docs\u002Fteam-configuration-guide.md`, `docs\u002F_common\u002Fsecurity.md`, etc.) live inside the generated variant project being upgraded, not at the workspace root.\n\n**Coverage is deny-list by design** ([2026-09-11-upgrade-policy-coverage-design.md](..\u002F..\u002Fdocs\u002Fdesigns\u002F2026-09-11-upgrade-policy-coverage-design.md)): the classification for every template path lives in `scripts\u002Flib\u002Fupgrade-policy.ts`, and the fallback policy *delivers by default* — a file added to the template without a dedicated upgrade pass still reaches existing projects instead of silently falling through. `bun scripts\u002Fcheck-upgrade-coverage.ts [--variant \u003Cname>] [--strict] [--json]` reports (and with `--strict` gates) the classification matrix over the whole effective template tree: placeholder tokens in delivered files, WS-07 contamination (`docs\u002Fcontext.md` inside a variant template), and JSON health of `JSON_MERGE` targets.\n\n### Supported Managed Block Markers\n\nThe merge engine recognizes these marker patterns for section-based merge:\n\n| Marker | Open | Close | Use Case |\n|--------|------|-------|----------|\n| WORKSPACE-MANAGED | `\u003C!-- WORKSPACE-MANAGED[:desc] -->` | `\u003C!-- \u002FWORKSPACE-MANAGED -->` | Generic managed sections |\n| COMMON-CLAUDE | `\u003C!-- COMMON-CLAUDE:START -->` | `\u003C!-- COMMON-CLAUDE:END -->` | CLAUDE.md shared sections |\n| COMMON-GEMINI | `\u003C!-- COMMON-GEMINI:START -->` | `\u003C!-- COMMON-GEMINI:END -->` | GEMINI.md shared sections |\n| COMMON-CODEX | `\u003C!-- COMMON-CODEX:START -->` | `\u003C!-- COMMON-CODEX:END -->` | CODEX.md shared sections (managed-block-merge v1.2.0) |\n| COMMON-HERMES | `\u003C!-- COMMON-HERMES:START -->` | `\u003C!-- COMMON-HERMES:END -->` | HERMES.md shared sections, ADR-0093 (managed-block-merge v1.3.0) |\n| VARIANT-INJECT | `\u003C!-- VARIANT-INJECT:label -->` | `\u003C!-- END VARIANT-INJECT -->` | Variant template injection points |\n| COMMON-AGENTS | `\u003C!-- COMMON-AGENTS:START -->` | `\u003C!-- COMMON-AGENTS:END -->` | AGENTS.md shared sections |\n| COMMON-CONTEXT | `\u003C!-- COMMON-CONTEXT:START -->` | `\u003C!-- COMMON-CONTEXT:END -->` | Common coding-guidelines zone merged into `docs\u002F\u003Cvariant>.context.md` (since v1.26.0 — previously projects had no delivery channel for that zone) |\n| DYNAMIC_SKILLS | `\u003C!-- DYNAMIC_SKILLS_START -->` | `\u003C!-- DYNAMIC_SKILLS_END -->` | Skill registry tables |\n\nKeyed markers (WORKSPACE-MANAGED, VARIANT-INJECT) match project blocks by their `: label` suffix and insert labeled blocks the project lacks; unlabeled blocks match positionally.\n\n### Safety Mechanisms\n\n1. **Pre-upgrade git stash (tracked + untracked)**: apply mode runs `git stash push -u` creating `pre-upgrade-snapshot-YYYYMMDD`; since v1.28.0 untracked files are included, so every CONFLICT file has rollback coverage. A failed stash is a hard error (exit 1) — it is never treated as \"working tree clean\"\n2. **Pre-scan conflict semantics (v1.28.0)**: the locally-modified file set is snapshotted BEFORE the stash runs, so `--dry-run` CONFLICT verdicts match the apply run instead of being silently downgraded to UPDATE once the tree is stashed clean\n3. **Honest exit codes (v1.28.0)**: the script exits 1 when the pre-upgrade stash fails, when `--rollback` cannot restore the stash, or when the post-upgrade security summary is FAILED — a scripted consumer never sees a green exit for a red run\n4. **Root-target guard (v1.27.0)**: a `\u003Cproject-path>` resolving to the workspace ROOT is rejected with an error (the 2026-09-12 root-upgrade incident delivered the whole template\u002FL1 tree through exactly this hole); targets outside `Projects\u002F` warn\n5. **`--dry-run` mode**: full analysis with zero writes; bootstrap artifacts are only verified on apply (they are materialized there), so dry runs skip the security checklist instead of reporting spurious failures\n6. **Security bootstrap verification**: post-upgrade check of `.gitleaks.toml`, hooks, `.gitattributes`, `.gitignore`, and `core.hooksPath` (auto-fixed when drifted)\n7. **Local modification detection**: warns when overwriting files that were locally modified before the upgrade started\n8. **Post-upgrade sync-skills.ts**: automatically distributes platform skills after upgrade\n\n### `docs\u002Fcontext.md` Version Sync\n\n`docs\u002Fcontext.md` (the immutable common project-context file) carries an inline `*context.md\nversion: X.Y*` footer that the TEMPLATE TREE SYNC pass compares against `templates\u002Fcommon\u002Fdocs\u002Fcontext.md`'s\nfooter on every upgrade run — if the project's copy is behind, it's updated automatically. Since v1.25.0\nthe overwrite is guarded: before copying, the pass detects project-only top-level sections (headings\nabsent from the template, outside COMMON-*\u002FVARIANT-INJECT managed zones) or a missing version footer\n(a fully restructured file). When project-only content exists, the copy is SKIPPED with a loud\nCONTEXT PRESERVE log unless `--force-context-sync` takes the template version anyway (logging the\ndiscarded section count). \"Immutable\" means don't hand-edit it for project-specific content (that\nbelongs in `docs\u002F\u003Cvariant>.context.md`) — it does not mean the file never changes; this is the\nsanctioned, conflict-aware channel for it to receive non-breaking governance\u002Finfra updates over time.\n`docs\u002F\u003Cvariant>.context.md`'s `\u003C!-- VARIANT-INJECT -->`-wrapped sections (in DOCS_MERGE, above) are\nthe equivalent mechanism for that file's shared-guidance subset.\n\nAs the number of variants grows, unrelated `docs\u002F\u003Cvariant>.context.md` files independently\nconverging on similar wording is expected. `scripts\u002Faudit.ts`'s cross-variant context\ncommonization check (WARN-only) flags sections with high textual overlap across variants as\ncandidates for promotion into `docs\u002Fcontext.md` (if shared by most variants) or a shared skill\n(if shared by only a subset) — run it after scaffolding a new variant, or at minimum every 5\nvariants \u002F quarterly. Full procedure: `skills\u002Fcontext-commonization-review\u002FSKILL.md`. Full rationale: ADR-0050 Part 3.\n\n## Step-by-Step Procedure\n\nRun the upgrader from the workspace root (`bun scripts\u002Fupgrade-project.ts Projects\u002F\u003Cp> ...`).\n\n1. **Check version**: `cat Projects\u002F\u003Cp>\u002F.claude\u002Ftemplate-version.txt`\n2. **Dry run**: `bun scripts\u002Fupgrade-project.ts Projects\u002F\u003Cp> --dry-run --prune-removed`\n3. **Ensure a clean tree**: the pre-upgrade stash reverts uncommitted changes, so land local work first via the project's own pipeline: `cd Projects\u002F\u003Cp> && bun scripts\u002Fdev-sync.ts --body-file \u003Cbody> \"\u003Cmsg>\"`\n4. **Run upgrade**: `bun scripts\u002Fupgrade-project.ts Projects\u002F\u003Cp> --prune-removed` (`--prune-removed` is mandatory to retire stale engine copies; see project-resync Step 4)\n5. **Review**: `cd Projects\u002F\u003Cp> && git status && git diff --cached`\n6. **Land**: from the project, `bun scripts\u002Fdev-sync.ts --body-file \u003Cbody> \"chore: upgrade template to vX.Y.Z\"`\n7. **Verify**: in the project, confirm `.claude\u002Ftemplate-version.txt` shows the new version, then run `bun scripts\u002Faudit.ts` and `bun scripts\u002Fverify-scripts.ts --verify`. Both must exit 0. If ghost entries appear, the project's `scripts\u002FSCRIPTS.md` may need manual cleanup (see the Tier 3 SCRIPTS.md Filtering section of the script-lifecycle governance docs at the workspace root).\n\n### Rollback\n\n```bash\nbun scripts\u002Fupgrade-project.ts \u003Cproject> --rollback   # exits 1 if the restore fails\n# or manually:\ngit stash list\ngit stash pop stash@{0}\n```\n\n## See Also\n\n- [Project Upgrade Guide](..\u002F..\u002Fdocs\u002Fguides\u002Fproject-upgrade-guide.md)\n- [Variant Conversion Guide](..\u002F..\u002Fdocs\u002Fguides\u002Fvariant-conversion-guide.md)\n- [Fork Model (ADR-0031)](..\u002F..\u002Fdocs\u002Fadr\u002F0031-l1-l2-fork-model.md)\n\n## Related\n\n- **project-resync**: fleet-level cycle that invokes this skill (Step 4). Loop: project-review (diagnose) → project-resync (fleet sync\u002Fbackport) → upgrade-project (deliver) → project-review baseline-only (verify).\n","# Upgrade Project\n\nUpgrades an existing project created from a variant template to match the current template version.\n\n## When to Use\n\n- The workspace template has been updated with new scripts, agent improvements, or security fixes\n- A project needs to receive the latest governance or automation infrastructure\n- Periodic maintenance to keep projects in sync with template evolution\n\n## Prerequisites\n\n- The project must have been created from a `co-*` variant template\n- The project must be a git repository\n- `bun` must be installed\n\n## Script\n\n**Script**: `scripts\u002Fupgrade-project.ts` (see the `@version` header in the script)\n**Location**: Workspace root only (`L0` per ADR-0073 Amendments 1, 3 and 4 — projects do not carry a copy; from inside a project use `bun ..\u002F..\u002Fscripts\u002Fupgrade-project.ts .`)\n**Usage**: `bun scripts\u002Fupgrade-project.ts \u003Cproject-path> [--variant \u003Cname>] [--platform claude|antigravity|codex|all] [--dry-run] [--prune-removed] [--rollback] [--yes] [--skip-context-commonization] [--force-context-sync]`\n\n### Arguments\n\n| Argument | Required | Description |\n|----------|----------|-------------|\n| `\u003Cproject-path>` | Yes | Path to the target project. A path that resolves to the workspace ROOT is rejected (root is L0, not a project); targets outside `Projects\u002F` print a warning |\n| `--variant \u003Cname>` | No | Auto-detected from `.claude\u002Ftemplate-version.txt` |\n| `--platform \u003Cval>` | No | `claude`, `antigravity`, `codex`, or `all` — all three platforms (default: `all`; `both` was renamed to `all` in v1.34.0) |\n| `--dry-run` | No | Analyze without making changes |\n| `--prune-removed` | No | Remove files present in project but absent from template (falls back to a direct delete when `git rm` fails on untracked files) |\n| `--rollback` | No | Restore pre-upgrade git stash snapshot; exits 1 when the restore fails. Under `--dry-run` it prints a no-op plan instead |\n| `--yes` | No | Skip the proceed prompt when `template-version.txt` is missing |\n| `--skip-context-commonization` | No | Opt out of the CONTEXT_COMMONIZATION pass for this run |\n| `--force-context-sync` | No | Take the template `docs\u002Fcontext.md` even when the project copy carries project-only content (the discarded section count is logged) |\n| `--changelog-entry` | No | Opt-in (default OFF): scaffold one editable `chore(upgrade): template sync` bullet at the top of the project CHANGELOG's `[Unreleased]` section for this delivery (idempotent per template version; apply-mode only — refused under `--dry-run`; spec 2026-10-29-delivery-bookkeeping-engine A3). The daily resync runner and operator upgrade sessions pass it by convention |\n\n## How It Works\n\nThe upgrade tool classifies files into categories:\n\n| Category | Behavior | Examples |\n|----------|----------|---------|\n| **LOCKED** | Unconditional overwrite | Git hooks, `.gitleaks.toml`, `.gitattributes` |\n| **MERGE** | Section-based merge via markers | `CLAUDE.md`, `GEMINI.md`, `.gitignore`, `agents\u002Fpm.md` |\n| **DOCS_MERGE** | Section-based merge (managed blocks) | `AGENTS.md`, `docs\u002F\u003Cvariant>.context.md` |\n| **DOCS_OVERWRITE** | Plain overwrite (no blocks) | `docs\u002Fphase-definitions.md` |\n| **VARIANT_DOCS_SYNC** *(folded v1.22.0)* | No longer a separate pass — its files (`docs\u002Fcontext.md` and the shared docs pair set) are delivered by **TEMPLATE TREE SYNC**'s default SYNC policy with identical inline-version\u002Fhash\u002Fconflict semantics | — |\n| **TEMPLATE TREE SYNC** | Default-policy delivery for template files no dedicated pass claims: add-if-missing, then inline-version\u002Fhash update with conflict warning. `JSON_MERGE` deep-merges platform settings (project-only array entries preserved; template hook entries whose command references a path absent from the project are dropped — the trail-migration guard, design 2026-10-31-graft-trail-migration R2.4); `ADD_IF_MISSING` seeds (`.codex\u002Fconfig.toml`, graft surfaces) never overwrite, and when the project carries `.trail\u002F` (the trail-migration marker) the graft-era seeds (`.mcp.json`, `graft-hooks.cjs`, `graft-statusline.cjs`) are RETIRED — `SEED_SKIP` (retired-surface), never re-seeded; `WORKSPACE` seeds (`docs\u002Fdesigns\u002F`, `docs\u002Flifecycle\u002F`, …) are add-if-missing only | Rest of the `docs\u002F` tree (`user-guide`, variant domain docs, `countries\u002FKR.md`, `skill-graph.overrides.json`), `.github\u002F`, `.claude`\u002F`.gemini\u002Fsettings.json`, `.mcp.json`, `opencode.json`, `.editorconfig`, platform `skills.json` |\n| **ENV_SAMPLE SYNC** *(since v1.23.0)* | Country-aware MERGE delivery of `.env.sample`: template content with `# >>> country-scoped:\u003CCC>` blocks pruned to the project's detected country (region-neutral = all blocks stripped, matching scaffold posture); same-NAME keys superseded by the template line, project-only keys preserved under a marker section (idempotent); standard conflict warning on locally-modified copies | `.env.sample` |\n| **CONTEXT_COMMONIZATION** *(since v1.20.0)* | After `docs\u002Fcontext.md` refreshes, near-duplicate top-level sections of `docs\u002F\u003Cvariant>.context.md` are pruned: token-overlap >= 0.65 → REMOVE (logged), >= 0.30 → REVIEW (manual Context Commonization Review, ADR-0050 Part 3 — never auto-removed), below → silent. Sections containing managed COMMON-*\u002FVARIANT-INJECT content downgrade to REVIEW; managed zones and the version footer are excluded. Comparison reads the template source, so dry-run verdicts match apply | `docs\u002F\u003Cvariant>.context.md` |\n| **GOVERNANCE FILES SYNC** *(since v1.12.0)* | Strictly add-if-missing delivery of top-level governance files from the variant template, then `templates\u002Fcommon`. An existing project file is always preserved (licenses are intentionally forkable) | `LICENSE`, `SECURITY.md` |\n| **COMMANDS_SYNC** | Hash-based sync | `.claude\u002Fcommands\u002F*.md`, `.gemini\u002Fcommands\u002F*.md` |\n| **SYNC_IF_NEWER** | Version-based update | Scripts (`.ts`), agents (`.md`), skills (`SKILL.md`) |\n| **PRESERVE** | Never touched | `README.md`, `src\u002F` |\n| **OVERWRITE** | Governance files | `docs\u002F_common\u002Fsecurity.md` |\n\n> **Path note**: the `docs\u002F...` paths in the tables above (`docs\u002Fcontext.md`, `docs\u002Fphase-definitions.md`, `docs\u002Fengagement-orchestration.md`, `docs\u002Fteam-configuration-guide.md`, `docs\u002F_common\u002Fsecurity.md`, etc.) live inside the generated variant project being upgraded, not at the workspace root.\n\n**Coverage is deny-list by design** ([2026-09-11-upgrade-policy-coverage-design.md](..\u002F..\u002Fdocs\u002Fdesigns\u002F2026-09-11-upgrade-policy-coverage-design.md)): the classification for every template path lives in `scripts\u002Flib\u002Fupgrade-policy.ts`, and the fallback policy *delivers by default* — a file added to the template without a dedicated upgrade pass still reaches existing projects instead of silently falling through. `bun scripts\u002Fcheck-upgrade-coverage.ts [--variant \u003Cname>] [--strict] [--json]` reports (and with `--strict` gates) the classification matrix over the whole effective template tree: placeholder tokens in delivered files, WS-07 contamination (`docs\u002Fcontext.md` inside a variant template), and JSON health of `JSON_MERGE` targets.\n\n### Supported Managed Block Markers\n\nThe merge engine recognizes these marker patterns for section-based merge:\n\n| Marker | Open | Close | Use Case |\n|--------|------|-------|----------|\n| WORKSPACE-MANAGED | `\u003C!-- WORKSPACE-MANAGED[:desc] -->` | `\u003C!-- \u002FWORKSPACE-MANAGED -->` | Generic managed sections |\n| COMMON-CLAUDE | `\u003C!-- COMMON-CLAUDE:START -->` | `\u003C!-- COMMON-CLAUDE:END -->` | CLAUDE.md shared sections |\n| COMMON-GEMINI | `\u003C!-- COMMON-GEMINI:START -->` | `\u003C!-- COMMON-GEMINI:END -->` | GEMINI.md shared sections |\n| COMMON-CODEX | `\u003C!-- COMMON-CODEX:START -->` | `\u003C!-- COMMON-CODEX:END -->` | CODEX.md shared sections (managed-block-merge v1.2.0) |\n| COMMON-HERMES | `\u003C!-- COMMON-HERMES:START -->` | `\u003C!-- COMMON-HERMES:END -->` | HERMES.md shared sections, ADR-0093 (managed-block-merge v1.3.0) |\n| VARIANT-INJECT | `\u003C!-- VARIANT-INJECT:label -->` | `\u003C!-- END VARIANT-INJECT -->` | Variant template injection points |\n| COMMON-AGENTS | `\u003C!-- COMMON-AGENTS:START -->` | `\u003C!-- COMMON-AGENTS:END -->` | AGENTS.md shared sections |\n| COMMON-CONTEXT | `\u003C!-- COMMON-CONTEXT:START -->` | `\u003C!-- COMMON-CONTEXT:END -->` | Common coding-guidelines zone merged into `docs\u002F\u003Cvariant>.context.md` (since v1.26.0 — previously projects had no delivery channel for that zone) |\n| DYNAMIC_SKILLS | `\u003C!-- DYNAMIC_SKILLS_START -->` | `\u003C!-- DYNAMIC_SKILLS_END -->` | Skill registry tables |\n\nKeyed markers (WORKSPACE-MANAGED, VARIANT-INJECT) match project blocks by their `: label` suffix and insert labeled blocks the project lacks; unlabeled blocks match positionally.\n\n### Safety Mechanisms\n\n1. **Pre-upgrade git stash (tracked + untracked)**: apply mode runs `git stash push -u` creating `pre-upgrade-snapshot-YYYYMMDD`; since v1.28.0 untracked files are included, so every CONFLICT file has rollback coverage. A failed stash is a hard error (exit 1) — it is never treated as \"working tree clean\"\n2. **Pre-scan conflict semantics (v1.28.0)**: the locally-modified file set is snapshotted BEFORE the stash runs, so `--dry-run` CONFLICT verdicts match the apply run instead of being silently downgraded to UPDATE once the tree is stashed clean\n3. **Honest exit codes (v1.28.0)**: the script exits 1 when the pre-upgrade stash fails, when `--rollback` cannot restore the stash, or when the post-upgrade security summary is FAILED — a scripted consumer never sees a green exit for a red run\n4. **Root-target guard (v1.27.0)**: a `\u003Cproject-path>` resolving to the workspace ROOT is rejected with an error (the 2026-09-12 root-upgrade incident delivered the whole template\u002FL1 tree through exactly this hole); targets outside `Projects\u002F` warn\n5. **`--dry-run` mode**: full analysis with zero writes; bootstrap artifacts are only verified on apply (they are materialized there), so dry runs skip the security checklist instead of reporting spurious failures\n6. **Security bootstrap verification**: post-upgrade check of `.gitleaks.toml`, hooks, `.gitattributes`, `.gitignore`, and `core.hooksPath` (auto-fixed when drifted)\n7. **Local modification detection**: warns when overwriting files that were locally modified before the upgrade started\n8. **Post-upgrade sync-skills.ts**: automatically distributes platform skills after upgrade\n\n### `docs\u002Fcontext.md` Version Sync\n\n`docs\u002Fcontext.md` (the immutable common project-context file) carries an inline `*context.md\nversion: X.Y*` footer that the TEMPLATE TREE SYNC pass compares against `templates\u002Fcommon\u002Fdocs\u002Fcontext.md`'s\nfooter on every upgrade run — if the project's copy is behind, it's updated automatically. Since v1.25.0\nthe overwrite is guarded: before copying, the pass detects project-only top-level sections (headings\nabsent from the template, outside COMMON-*\u002FVARIANT-INJECT managed zones) or a missing version footer\n(a fully restructured file). When project-only content exists, the copy is SKIPPED with a loud\nCONTEXT PRESERVE log unless `--force-context-sync` takes the template version anyway (logging the\ndiscarded section count). \"Immutable\" means don't hand-edit it for project-specific content (that\nbelongs in `docs\u002F\u003Cvariant>.context.md`) — it does not mean the file never changes; this is the\nsanctioned, conflict-aware channel for it to receive non-breaking governance\u002Finfra updates over time.\n`docs\u002F\u003Cvariant>.context.md`'s `\u003C!-- VARIANT-INJECT -->`-wrapped sections (in DOCS_MERGE, above) are\nthe equivalent mechanism for that file's shared-guidance subset.\n\nAs the number of variants grows, unrelated `docs\u002F\u003Cvariant>.context.md` files independently\nconverging on similar wording is expected. `scripts\u002Faudit.ts`'s cross-variant context\ncommonization check (WARN-only) flags sections with high textual overlap across variants as\ncandidates for promotion into `docs\u002Fcontext.md` (if shared by most variants) or a shared skill\n(if shared by only a subset) — run it after scaffolding a new variant, or at minimum every 5\nvariants \u002F quarterly. Full procedure: `skills\u002Fcontext-commonization-review\u002FSKILL.md`. Full rationale: ADR-0050 Part 3.\n\n## Step-by-Step Procedure\n\nRun the upgrader from the workspace root (`bun scripts\u002Fupgrade-project.ts Projects\u002F\u003Cp> ...`).\n\n1. **Check version**: `cat Projects\u002F\u003Cp>\u002F.claude\u002Ftemplate-version.txt`\n2. **Dry run**: `bun scripts\u002Fupgrade-project.ts Projects\u002F\u003Cp> --dry-run --prune-removed`\n3. **Ensure a clean tree**: the pre-upgrade stash reverts uncommitted changes, so land local work first via the project's own pipeline: `cd Projects\u002F\u003Cp> && bun scripts\u002Fdev-sync.ts --body-file \u003Cbody> \"\u003Cmsg>\"`\n4. **Run upgrade**: `bun scripts\u002Fupgrade-project.ts Projects\u002F\u003Cp> --prune-removed` (`--prune-removed` is mandatory to retire stale engine copies; see project-resync Step 4)\n5. **Review**: `cd Projects\u002F\u003Cp> && git status && git diff --cached`\n6. **Land**: from the project, `bun scripts\u002Fdev-sync.ts --body-file \u003Cbody> \"chore: upgrade template to vX.Y.Z\"`\n7. **Verify**: in the project, confirm `.claude\u002Ftemplate-version.txt` shows the new version, then run `bun scripts\u002Faudit.ts` and `bun scripts\u002Fverify-scripts.ts --verify`. Both must exit 0. If ghost entries appear, the project's `scripts\u002FSCRIPTS.md` may need manual cleanup (see the Tier 3 SCRIPTS.md Filtering section of the script-lifecycle governance docs at the workspace root).\n\n### Rollback\n\n```bash\nbun scripts\u002Fupgrade-project.ts \u003Cproject> --rollback   # exits 1 if the restore fails\n# or manually:\ngit stash list\ngit stash pop stash@{0}\n```\n\n## See Also\n\n- [Project Upgrade Guide](..\u002F..\u002Fdocs\u002Fguides\u002Fproject-upgrade-guide.md)\n- [Variant Conversion Guide](..\u002F..\u002Fdocs\u002Fguides\u002Fvariant-conversion-guide.md)\n- [Fork Model (ADR-0031)](..\u002F..\u002Fdocs\u002Fadr\u002F0031-l1-l2-fork-model.md)\n\n## Related\n\n- **project-resync**: fleet-level cycle that invokes this skill (Step 4). Loop: project-review (diagnose) → project-resync (fleet sync\u002Fbackport) → upgrade-project (deliver) → project-review baseline-only (verify).\n",{"name":5,"owner":23,"scope":24,"status":25,"version":26,"metadata":27,"relates_to":35,"description":7,"last_updated":42,"last_reviewed":43},"pm","workspace","active","1.6.2",{"type":28,"triggers":29},"scaffolding",[30,31,32,33,34],"upgrade project","upgrade template","sync project with template","refresh project","update project infrastructure",[36,39],{"type":37,"skill":38},"follows","promote-variant",{"type":40,"skill":41},"composes_with","project-resync",1792972800000,1793404800000,"main","1162ccc568cf90c01b3886d6143cbfd851a37883",".agents\u002Fskills\u002Fupgrade-project",9,"https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards","https:\u002F\u002Fgithub.com\u002F5throck","Experienced in digital transformation, enterprise IT, startup acceleration, and business strategy. Focused on building practical systems that connect technolo","2026-11-14 21:22:34",{"source":8,"skillName":5,"commands":53,"prompt":63,"zipAvailable":64},[54,57,60],{"tool":55,"command":56},"npx","npx skills add 5throck\u002Fai-workspace-standards --skill upgrade-project",{"tool":58,"command":59},"bunx","bunx skills add 5throck\u002Fai-workspace-standards --skill upgrade-project",{"tool":61,"command":62},"pnpm","pnpm dlx skills add 5throck\u002Fai-workspace-standards --skill upgrade-project","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fupgrade-project\u002FSKILL.md",true,[],[67,75,80,85,90,95],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":74},"01M7BBJDYHJMGTJYSC37JVWY8S","i18n-layout","Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL\u002Fbidi 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\u002FBOM issues surface.","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":76,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":74},"01M7BBJ9XHAAS1AVGKZZ841VBZ","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.hermes\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":81,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":74},"01M7BBJ5C3X8TKFKG5R9P9P49W","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.gemini\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":86,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":74},"01M7BBJ1B52X0QMJ2QVBMPJB37","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.codex\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":91,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":74},"01M7BBHX91BW2Q2R276MRX5AW3","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.claude\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[],{"skillNo":96,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":74},"01M7BBHQWGXPSFRWN1PRC2NMMV","https:\u002F\u002Fgithub.com\u002F5throck\u002Fai-workspace-standards\u002Fblob\u002Fmain\u002Ftemplates\u002Fco-work\u002F.agents\u002Fskills\u002Fi18n-layout\u002FSKILL.md",[],[]]