vc:publish

# vc-publish

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`.

### Step 3: Resolve Both File Sets

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).

8. Run the resolver against the **dev repo** to get the dev file list:
   ```bash
   node <kitRepoPath>/resolve-manifest.mjs --root <devRepoRoot> --json
   ```
   Extract `files` (dev managed files).

   **Note:** The resolver uses the manifest from the `--root` directory. Since the dev repo has a copy of `vc-manifest.json`, the resolver works against it. If the dev repo doesn't have the resolver script, copy it from the kit repo first or use the kit repo's copy with `--root` pointing to the dev repo.

### Step 4: Compute Diff

9. Compare the two resolved file sets:
   - Files in dev `files` but NOT in kit `files`: **new** (will be added to kit).
   - Files in kit `files` but NOT in dev `files`: **removed** (will be removed from kit).
   - Files in both: compare content via `diff`. Classify as **modified** or **unchanged**.
   - `merge` files (CLAUDE.md, AGENTS.md): always flag for content review regardless of diff status.

### 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, manifest schema changes, breaking workflow changes

### Step 7: Apply Changes

12. On confirm:
    - Copy all **modified** and **new** managed files from current repo to kit repo checkout.
    - For each **removed** file: delete it from the kit repo checkout.
    - **CLAUDE.md and AGENTS.md stripping**: Do NOT copy the current repo's project-specific versions directly. Instead:
      1. Read the current repo's CLAUDE.md/AGENTS.md.
      2. Read the kit repo's existing harness-only version as base.
      3. Apply only methodology/structural changes from the dev repo to the kit's harness-only version.
      4. Strip all project-specific content:
         - Technology stack details (frameworks, databases, versions)
         - Feature list / "Current features" entries
         - Project-specific context groups
         - Hardcoded package manager (replace with generic)
         - MCP server instructions (project-specific config)
         - Project-specific routing rules
         - Absolute paths (`/Users/...`)
         - Product name references (the project's product name and repo/directory name)
      5. Verify the result is harness-only methodology with no project leaks.
    - Update `vc-manifest.json`: bump `version` field per the chosen bump type. **No other manifest changes needed** -- glob patterns are stable, new files are automatically included.
    - Create symlinks if missing (`.agents/skills -> ../.claude/skills`).

### Step 8: Leak Detection

13. Verify no project-specific content leaked into the kit repo. This is a
    **resolved-set, two-check** gate that scans the full shipped TEXT surface, not
    just `CLAUDE.md`/`AGENTS.md`.

    **Resolve the shipped set** via the kit's resolver, then restrict to TEXT
    surfaces:

    ```bash
    node <kitRepoPath>/resolve-manifest.mjs --root <kitRepoPath> --json
    ```

    Take the resolved `files` and keep only TEXT surfaces:
    - `.claude/skills/**` matching `*.md`, `*.cjs`, `*.mjs`, `*.py`, `*.js`, `*.json`
    - `.claude/agents/**` matching `*.md`
    - `.codex/**`
    - `process/development-protocols/**`
    - plus `CLAUDE.md`, `AGENTS.md`

    Exclude binaries and `**/node_modules/**`.

    **Check (a) -- product-name grep over the resolved text set.** Scan for the
    product names in the grep