feat(skills): add divergence check to polish skill setup (#380)

6727d0d8a5dbbeda949b6e7d436b60b4e7e316dc · 2026-04-29 00:57:40 -0700 · Trevin Chow

Polish previously assumed the internal copy at ~/printing-press/library/<api>/
was canonical, but that breaks once the CLI has been published — anyone editing
the public library repo directly creates drift the internal copy can't see.
Polishing a stale internal copy and re-publishing would silently overwrite
public-only fixes.

Adds a divergence-check step to /printing-press-polish setup, after CLI
resolution and before Phase 1 baseline diagnostics. The skill prose tells
the agent the what and why without prescribing how — the agent picks
platform-appropriate tools (mdfind, locate, find, etc.) to scan for a
clone of mvanhorn/printing-press-library, validates each candidate by
its git remote, and falls back gracefully when no clone is present
(the dominant case for users who didn't generate the CLI originally).

Resolution is one-way: sync public→internal on user opt-in, then
internal stays canonical for the rest of polish. The publish step does
not get its own check — running publish without polish is the user
explicitly opting out of the safety net. Single entry point, simpler
flow, no decision tree branching.

When internal has files modified after its .printing-press.json
timestamp, the prompt hedges explicitly so the user knows syncing
will overwrite their pending local polish work.

Files touched

M skills/printing-press-polish/SKILL.md

Diff

commit 6727d0d8a5dbbeda949b6e7d436b60b4e7e316dc
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Wed Apr 29 00:57:40 2026 -0700

    feat(skills): add divergence check to polish skill setup (#380)
    
    Polish previously assumed the internal copy at ~/printing-press/library/<api>/
    was canonical, but that breaks once the CLI has been published — anyone editing
    the public library repo directly creates drift the internal copy can't see.
    Polishing a stale internal copy and re-publishing would silently overwrite
    public-only fixes.
    
    Adds a divergence-check step to /printing-press-polish setup, after CLI
    resolution and before Phase 1 baseline diagnostics. The skill prose tells
    the agent the what and why without prescribing how — the agent picks
    platform-appropriate tools (mdfind, locate, find, etc.) to scan for a
    clone of mvanhorn/printing-press-library, validates each candidate by
    its git remote, and falls back gracefully when no clone is present
    (the dominant case for users who didn't generate the CLI originally).
    
    Resolution is one-way: sync public→internal on user opt-in, then
    internal stays canonical for the rest of polish. The publish step does
    not get its own check — running publish without polish is the user
    explicitly opting out of the safety net. Single entry point, simpler
    flow, no decision tree branching.
    
    When internal has files modified after its .printing-press.json
    timestamp, the prompt hedges explicitly so the user knows syncing
    will overwrite their pending local polish work.
---
 skills/printing-press-polish/SKILL.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/skills/printing-press-polish/SKILL.md b/skills/printing-press-polish/SKILL.md
index f9627980..1620101f 100644
--- a/skills/printing-press-polish/SKILL.md
+++ b/skills/printing-press-polish/SKILL.md
@@ -114,6 +114,23 @@ if [ -n "$SPEC_PATH" ]; then
 fi
 ```
 
+### Divergence check
+
+The internal copy at `$CLI_DIR` can drift from the public library (`mvanhorn/printing-press-library`) copy if anyone edited the public repo directly after this CLI was last published. Polishing a stale internal copy and re-publishing later would overwrite those public-only fixes.
+
+Find the public library clone on the user's machine. Honor `$PRINTING_PRESS_LIBRARY_PUBLIC` if set, otherwise locate a clone however fits this platform. Validate by checking the git remote points at `mvanhorn/printing-press-library` — other directories may share the name (forks, accidental name collisions). If multiple valid clones exist, prefer the most recently modified; ask the user to disambiguate only if still unclear.
+
+Outcomes:
+
+- **No clone found** → user doesn't have public locally; proceed silently on internal.
+- **Clone found but doesn't contain this CLI** → never published or under a different name; proceed silently on internal.
+- **Found and `diff -r` is empty** → in sync; proceed silently on internal.
+- **Found and divergent** → don't compute "which side is newer" (file mtimes lie, internal isn't a git repo). Show the user the divergent files and ask via AskUserQuestion: **sync public→internal**, or **proceed without syncing**. If the user picks sync, copy public's version of the divergent files into internal, then continue polish.
+
+Before showing the sync prompt, check whether internal has files modified after its `.printing-press.json` timestamp (the user has been polishing locally without publishing). If yes, hedge the prompt explicitly: syncing will overwrite their pending local work. Let them decide whether to keep their local edits or pull public's.
+
+After sync (or skip), the rest of polish operates on `$CLI_DIR` as canonical. The eventual `/printing-press-publish` step pushes internal back to public; no second divergence check is needed there.
+
 ## Phase 1: Baseline diagnostics
 
 ```bash

← a9ca3f80 refactor(skills): extract Phase 4.85 into printing-press-out · back to Cli Printing Press · feat(cli): tools-audit checks MCP descriptions in tools-mani fee6802e →