Vc Update

Step 10: Apply Changes

On user confirmation, run in two parts:

Isolation guarantee (Parts A/B): $VC_UPDATE_TMPDIR is a read-only clone — no changes are made to it between calls. The project root is also not mutated before Part B runs. Both invocations therefore see the same sync plan, so the backup in Part A covers the exact set that Part B will overwrite.

Part A — Back up files that will be modified or deleted (toModify + toDelete lists):

Before applying, back up every file in toModify AND every file in toDelete so both overwritten content and deleted files are recoverable:

node "$VC_UPDATE_TMPDIR/compute-sync-plan.mjs" \
  --root "$PROJECT_ROOT" \
  --kit-root "$VC_UPDATE_TMPDIR" \
  --json | PROJECT_ROOT="$PROJECT_ROOT" node -e "
    const plan = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
    const fs = require('fs'), path = require('path');
    const root = process.env.PROJECT_ROOT;
    const backupDir = path.join(root, '.vibecode-backup');
    // Rotate any prior backup so re-runs never silently overwrite it
    if (fs.existsSync(backupDir) && fs.readdirSync(backupDir).length > 0) {
      const rotated = path.join(root, '.vibecode-backup-' + Math.floor(Date.now() / 1000));
      fs.renameSync(backupDir, rotated);
      console.log('Existing backup rotated to ' + path.relative(root, rotated) + '/');
    }
    for (const rel of [...plan.toModify, ...plan.toDelete]) {
      const src = path.join(root, rel);
      if (!fs.existsSync(src)) continue;
      const dst = path.join(backupDir, rel);
      const stat = fs.statSync(src);
      if (stat.isDirectory()) {
        fs.cpSync(src, dst, { recursive: true });
      } else {
        fs.mkdirSync(path.dirname(dst), { recursive: true });
        fs.copyFileSync(src, dst);
      }
    }
  "
# Note: this backup step assumes a POSIX shell. On Windows, skip or adapt it — /dev/stdin is unavailable.

(This preserves the pre-update versions of both overwritten and removed files, so any content is recoverable from .vibecode-backup/. If a .vibecode-backup/ directory already exists from a prior run, it is rotated to a timestamped name (.vibecode-backup-{unix-ts}/) before the new backup is written, so earlier backups are never overwritten.)

Part B — Apply the full plan with the single mechanical command:

node "$VC_UPDATE_TMPDIR/compute-sync-plan.mjs" \
  --root "$PROJECT_ROOT" \
  --kit-root "$VC_UPDATE_TMPDIR" \
  --resolver "$VC_UPDATE_TMPDIR/resolve-manifest.mjs" \
  --apply

--apply deterministically executes the computed plan:

• toAdd / toModify: mkdir -p parent + copy from kit to project. toPreserve entries (merge/copyIfMissing survivors) are never touched.
• toDelete: each entry is removed — directories via rmSync({recursive:true,force:true}), files via rmSync({force:true}).
• Empty-parent sweep: after all deletions, every ancestor directory of every deleted path is walked deepest-first and rmdirSync'd if empty. This is the guaranteed cleanup that prevents hollow deprecated skill dirs (e.g. empty references/, scripts/ subdirs) from surviving after a skill is removed.
• Snapshot: writes .vc-installed-files (sorted managedFiles — the files list from resolve-manifest; legacyDeletions are re-derived each run and not persisted).
• Version: writes .vc-version (manifest version string).
• .gitignore guard: after writing the version, apply ensures the project-root .gitignore contains .vibecode-backup*/ (additive — creates the file if absent, appends the glob form .vibecode-backup*/ if the glob form is missing even if a non-glob .vibecode-backup/ line already exists, no-ops if the glob form is already present). This prevents rotated backup dirs (.vibecode-backup-{ts}/) from being accidentally committed.
• staleWarnings (Type 1 — non-vc- namespace): paths in the prior snapshot that are not in the vc- namespace — moved to toPreserve, never deleted. Message form: 'X' in prior snapshot but not in kit namespace — preserved (verify manually).
• staleWarnings (Type 2 — vc- namespace, WARNING: prefix): vc- namespace paths that are in toDelete but not in the known ownedPaths/legacyDeletions — these ARE deleted. The warning is advisory: if the user has a custom vc- skill at that path, rename it before updating.

Do NOT hand-loop rm or cp commands — use only the --apply invocation above. The mechanical implementation guarantees correct empty-dir cleanup on every run, including directory-shaped deletions and deeply nested deprecated skill subdirs.

Part C — Symlinks (handled separately, unchanged):

For each entry in symlinks:

• If a real directory exists at the path: rm -rf it first.
• If a wrong symlink exists: rm it first.
• Create the symlink: ln -s {target} {path}

Part D — Safe legacy layout migration:

Sequencing — safe-migration (Part D) RUNS BEFORE legacyDeletions are applied. This ordering ensures user report/reference content is moved into task folders before the deprecated layout dirs (e.g. process/general-plans/reports, process/_seeds/.../references) are removed by the manifest's legacyDeletions pass. Never delete a deprecated layout dir until Part D has migrated its safe contents — otherwise user content would be lost.

After the harness files and symlinks are updated, migrate safe old-layout process artifacts into task folders:

• Scope:
  • flat *_PLAN_*.md files directly under process/general-plans/active/ and process/features/*/active/
  • sibling process/general-plans/reports/, process/general-plans/references/
  • sibling process/features/*/reports/, process/features/*/references/
• Safe inference rules: migrate automatically only when exactly one destination task folder can be inferred in the same scope by one of:
  • basename starts with one task slug and only one matching {slug}_{date}/ folder exists
  • basename or path contains an exact {slug}_{date} token matching one task folder
  • there is exactly one task folder total in that scope
  • exactly one task-folder plan references the legacy artifact path or basename
• Unsafe cases: leave in place and report when multiple candidates match, multiple plans reference the artifact, the file is clearly shared across tasks, or no task folder exists yet in that scope.
• Destination filename: preserve the original filename unless a same-name file already exists, then append -migrated.
• Cleanup: after all safe migrations, delete any now-empty legacy sibling reports/ or references/ dir. The target end-state is that each feature folder and process/general-plans/ keep only active/, completed/, and backlog/ unless unresolved legacy artifacts remain.

Part E — Clean up:

rm -rf "$VC_UPDATE_TMPDIR"

If --apply exits non-zero (permission error, missing kit file):

• Print the error message.
• Suggest running chmod on the affected path or checking file ownership.
• The command exits 1; do not treat a partial run as success.

Step 11: Print Applied Changes Summary and Post-Update NOTICE

vc-update complete: v{currentVersion} -> v{remoteVersion}

Applied:
  5 files modified
  2 files added
  1 file removed
  1 symlink fixed
  1 merge file preserved (review .claude/settings.json manually)

Snapshot written to .vc-installed-files
Version written to .vc-version: {remoteVersion}

If safe legacy artifacts were migrated, append lines such as:

Layout migration:
  4 legacy artifacts moved into task folders
  3 empty legacy dirs removed
  2 legacy artifacts left for manual review

After printing the summary, run three post-update checks and print a NOTICE block:

Check A — .agents/skills symlink vs real directory:

[ -L .agents/skills ] && echo "symlink" || echo "real-dir"

If the result is real-dir (Windows fallback — a real directory instead of a symlink), re-sync it now so it stays current with the updated .claude/skills/:

cp -r .claude/skills/. .agents/skills/

Print: NOTICE: .agents/skills is a real directory (Windows fallback) — re-synced from .claude/skills/

If it is a symlink, skip this step (the symlink already resolves to the updated .claude/skills/).

Check B — .claude/settings.json merge-preserved hooks gap:

If .claude/settings.json was in toPreserve (it was merge-protected), print the following NOTICE block verbatim so the user knows exactly what to add:

NOTICE: .claude/settings.json was preserved (merge-protected). New hooks added in
this release will NOT fire until you add them manually.

Missing hooks most likely absent from your v2.x install:

  PostToolUse (Write)  → post-write-plan-check.mjs   — validates plan artifact structure on every plan write
  PostToolUse (Bash)   → post-commit-lint.mjs         — lints commit messages for conventional-commit prefix
  Stop                 → stop-validator-sweep.cjs      — runs core validators on session end
  SubagentStart        → subagent-init.cjs             — injects compact context into every subagent

Paste-ready hooks block: see https://github.com/withkynam/vibecode-pro-max-kit/blob/main/MIGRATION.md#action-required-settingsjson-hooks
or diff .claude/settings.json .vibecode-backup/.claude/settings.json

If .claude/settings.json was NOT in toPreserve (it was freshly written), skip this notice.

Check C — orphaned old-layout / seed-template dirs (5 target classes):

Scan for orphaned deprecated layout dirs across these 5 classes:

1. process/general-plans/reports and process/general-plans/references (general-plans sibling dirs).
2. process/features/*/reports and process/features/*/references (feature-scoped sibling dirs).
3. process/development-protocols/references (deprecated protocol references dir).
4. process/_seeds/features/_feature-template/reports and process/_seeds/features/_feature-template/references (seed feature-template dirs).
5. process/_seeds/general-plans/reports and process/_seeds/general-plans/references (seed general-plans dirs).

Also scan for any flat *_PLAN_*.md file living directly in process/general-plans/active/ or process/features/*/active/ (not inside a {slug}_{date}/ subfolder).

For each orphaned dir found, log a line to .vc-orphaned-dirs.log in the project root:

DATE | DIR_PATH | STATUS: [EMPTY | USER_CONTENT | UNKNOWN]

• EMPTY — dir exists but has no files.
• USER_CONTENT — dir contains user files not yet migrated.
• UNKNOWN — could not classify (permission error, symlink, etc.).

After logging, print a stdout summary:

Found N orphaned dirs. See .vc-orphaned-dirs.log for details. Run vc-setup Merge Mode to migrate and cleanup.

If any orphaned dir or flat-plan signal is found after the safe migration pass, also print:

NOTICE: Some old-layout process/ artifacts could not be migrated safely.
The safe cases were already moved into task folders. Review the remaining
legacy paths manually — they are ambiguous, shared, or missing a clear task
folder destination.

If no orphaned dirs and no flat-plan signals are found, print nothing for Check C (no .vc-orphaned-dirs.log line written).

Recommended: run validators

After the NOTICE block, print:

Recommended next step — run the five core validators:

  node .claude/skills/vc-audit-vc/scripts/validate-agent-parity.mjs
  node .claude/skills/vc-audit-vc/scripts/validate-skills.mjs
  node .claude/skills/vc-audit-vc/scripts/validate-kit-portability.mjs
  node .claude/skills/vc-audit-context/scripts/validate-context-discovery.mjs
  node .claude/skills/vc-context-discovery/scripts/discover-skills.mjs

Rules

• VC_KIT_SOURCE: when set, overrides the remote URL for cloning. Used verbatim as the git clone source argument. No validation. Enables local testing and forks.
• process/_seeds/ is a legacy optional scaffold surface. If a remote release still includes it, treat it as managed reference and overwrite it entirely on update. Its absence in the live repo is valid.
• Real working files outside _seeds/ are preserved by default. The only allowed process/ mutations inside vc-update are the safe old-layout migrations described in Step 8 / Step 10 Part D for process/general-plans/ and process/features/*/.
• Always show the dry-run diff before applying. Never apply without user confirmation.
• Clean up the temp clone directory even on error or abort.
• If .vc-version is missing, treat as version 0.0.0 (first update, apply everything).
• CLAUDE.md and AGENTS.md are harness-only files -- overwritten freely on update. Project-specific content belongs in process/context/all-context.md, not in these files.
• Files in the merge list (e.g. .claude/settings.json) are never overwritten if they exist locally. Show the diff for manual review.
• Files in the copyIfMissing list are only installed if they don't already exist locally.
• Removals are detected by comparing the local .vc-installed-files snapshot against the new resolved file list.

Migration from v2.x

Kit v3.0.0 introduces the legacyDeletions key in resolveGlob()'s JSON output (Step 4 above). This note applies to users who are upgrading FROM a kit v2.x install that still has an OLD SKILL.md (one that predates v3.0.0 and does not reference compute-sync-plan.mjs). When such a user runs vc-update, the remote resolver already emits legacyDeletions in its JSON output. The current SKILL.md (this file, v3.0.0+) reads and applies that field in Step 6 via compute-sync-plan.mjs. No local SKILL.md change is required on the user's side — the update process itself installs the new SKILL.md in the same run.

The one-shot migration on next vc-update from kit v3.0.0:

1. Resolver emits legacyDeletions: [".claude/skills/vc-team", ".claude/skills/vc-chrome-devtools", ...] in the JSON output.
2. Step 6 applies those deletions in addition to the normal snapshot diff.
3. The 11 deprecated skill dirs (vc-team, vc-chrome-devtools, vc-docs, vc-repomix, vc-preview, vc-merge-worktree, vc-tech-graph, vc-watzup, vc-xia, vc-mcp-management, vc-context-engineering) plus 5 deprecated protocol paths are removed from the local install in one pass.
4. Snapshot is written with the new v3.0.0 file list — subsequent updates use normal diff logic.

Very old installs (SKILL.md predating legacyDeletions support): use install.sh for a clean reinstall instead of vc-update.

Reference

For detailed algorithm, error handling matrix, and edge cases, see references/vc-update.md.