vc-publish

# vc-publish

> **Output style:** Follow `process/development-protocols/communication-standards.md` — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Push harness improvements from the current development repo to the remote kit repository (`vibecode-pro-max-kit`). This is the **maintainer** counterpart to `vc-update`.

- `vc-update` = **user** pulls latest harness INTO their project FROM the remote
- `vc-publish` = **maintainer** pushes improvements FROM the development repo TO the remote kit repo

## Prerequisites

- Local checkout of the kit repo (`git clone git@github.com:withkynam/vibecode-pro-max-kit.git`)
- `.vc-publish-config` file in the current repo root (see Configuration below)
- Git push access to the remote kit repo

## Configuration

Create `.vc-publish-config` in the repo root:

```json
{"kitRepoPath": "/path/to/vibecode-pro-max-kit"}
```

If this file is missing, ask the user for the kit repo checkout path and offer to create it.

## Workflow

### Step 1: Load Configuration

1. Read `.vc-publish-config` from the current repo root.
2. If missing, ask the user for the kit repo local checkout path.
3. Verify the path exists and contains `vc-manifest.json`.
4. Verify the kit repo worktree is clean (`git -C <kitRepoPath> status --porcelain`). If dirty, warn and ask whether to proceed or abort.

### Step 2: Read Manifest

5. Read `vc-manifest.json` from the kit repo checkout.
6. Extract the current `version`.
7. Before computing a version bump, check if the current kit version already matches the intended target version (e.g. `3.0.0`). If the kit `version` already equals the target: **skip the bump step entirely** and proceed directly to Step 3 with a `tag-as-is` note — do not increment the version. Record in the publish summary that the version was unchanged.

**Catalog-regen (pre-publish):** Before resolving files in Steps 3–4, regenerate the skills catalog in the dev repo:
```bash
node .claude/skills/vc-audit-context/scripts/generate-skills-catalog.mjs --write
```
This ensures `process/context/generated-skills-catalog.json` is current before it is copied into the kit repo.

### Step 3: Resolve Kit File Set

7. Run the resolver against the **kit repo** to get the kit file list:
   ```bash
   node <kitRepoPath>/resolve-manifest.mjs --root <kitRepoPath> --json
   ```
   Extract `files` (kit managed files) and `kitOnly` (kit-exclusive files).

   **Note:** `resolve-manifest.mjs` reads `vc-manifest.json` from its `--root` directory and also scans files from that same root. `vc-manifest.json` is NOT installed into dev/user projects by `install.sh`, so the resolver must always be pointed at the kit repo checkout (which does have it). There is no separate dev-repo resolver call — the dev-side file comparison happens inside `compute-sync-plan.mjs` in Step 4.

### Step 4: Compute Diff

9. **Computation via `compute-sync-plan.mjs`:** Use the shared computation core to produce the diff between the dev repo's managed files and the kit repo's current managed files.

   > **Direction note:** `compute-sync-plan.mjs` loads `vc-manifest.json` from `--kit-root` and runs the resolver with `--root <kit-root>`. Since `vc-manifest.json` lives in the kit repo (not the dev repo), `--kit-root` must always be the kit repo checkout. `--root` is the dev repo (the project being compared). This is the same direction as a normal install — vc-publish uses it to see what a fresh install FROM dev INTO the kit would change.

   ```bash
   # --root = dev repo (the "project" being compared against the kit source)
   # --kit-root = kit repo (where vc-manifest.json lives; source of truth for file lists)
   # --resolver overrides the resolver path because compute-sync-plan
   # would otherwise look for resolve-manifest.mjs inside --kit-root,
   # which IS the kit repo here, so --resolver is optional but explicit for clarity.
   node <kitRepoPath>/compute-sync-plan.mjs \
     --root <devRepoRoot> \
     --kit-root <kitRepoPath> \
     --resolver <kitRepoPath>/resolve-manifest.mjs \
     --json
   ```

   Parse the JSON output: `{ toAdd, toModify, toDelete, toPreserve, staleWarnings }`.
   - `toAdd` — files to copy from dev to kit (present in dev, not yet in kit).
   - `toModify` — files to overwrite in kit (tracked in both, content differs).
   - `toDelete` — files to remove from kit (no longer in dev managed set).
   - `toPreserve` — files to leave untouched (merge/copyIfMissing survivors, unchanged files).
   - `staleWarnings` — paths that failed the namespace guard — print to user; do NOT delete.

   The ownedPaths for the publish direction are the dev repo's resolved `ownedPaths`. CLAUDE.md and AGENTS.md are always in the `merge` category — they require special stripping regardless of diff status (see Step 7).

### Step 5: Print Diff Summary

10. Print a summary table:

```
vc-publish diff: current repo -> kit repo (v2.1.0)
================================================

FILES:
  [modified]  .claude/agents/vc-execute-agent.md  (+8 -3)
  [modified]  .claude/hooks/lib/scout-checker.cjs  (+2 -1)
  [new]       .claude/skills/vc-new-skill/SKILL.md
  [merge]     CLAUDE.md (needs content review)
  [merge]     AGENTS.md (needs content review)
  [unchanged] .claude/settings.json
  ... (350 more unchanged)

Total changes: 4 files modified, 1 new, 0 removed
```

### Step 6: STOP -- Confirm Publish

11. **STOP** and ask the user:
    - Confirm they want to publish these changes.
    - Specify version bump type: **patch**, **minor**, or **major**.
    - Optionally provide **release notes** (1–3 sentences for the GitHub Release body). Leave blank to auto-generate from the diff summary (e.g. "4 modified, 1 new, 0 removed.").
    - Or abort.

Version bump semantics:
- **Patch** (2.1.0 -> 2.1.1): hook fixes, skill doc updates, minor agent prompt tweaks
- **Minor** (2.1.0 -> 2.2.0): new skills, new agents, new development protocols
- **Major** (2.1.0 -> 3.0.0): CLAUDE.md structure changes, manife