fix(skills): generate absolute manuscript URLs in publish PR body (#1235)

a8ad9820e89070e3adf084299c73bb2a5a5b797e · 2026-05-12 11:58:16 -0700 · Trevin Chow

* fix(skills): generate absolute manuscript URLs in publish PR body

PR bodies produced by /printing-press-publish were emitting relative
paths like `library/<category>/<slug>/.manuscripts/...`, which GitHub
resolved against the PR page URL and rendered as broken
`https://github.com/.../pull/library/...` links (see
mvanhorn/printing-press-library#497).

Capture HEAD_SHA after the push and require the Manuscripts section to
emit full `https://github.com/mvanhorn/printing-press-library/blob/<sha>/...`
URLs that point at specific files (not directories). The skill rewrites
the body with a fresh SHA on every update path, so links stay current
across force-pushes the skill performs.

* fix(skills): make per-file manuscript bullets unambiguous in template

Greptile P2 on #1235: the two-row template in the Manuscripts section
could be read as authoritative even though the prose said "one per
file," so an agent might emit exactly two bullets regardless of how
many files were in research/ and proofs/.

Replaced the prose preamble with a `<!-- one bullet per file -->`
comment marker, doubled each example row, and added explicit
"… (one bullet for each remaining file)" ellipsis rows for both
research/ and proofs/. Pattern is now unambiguous: the visible
template demonstrates repetition, not a fixed two-bullet shape.

Files touched

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

Diff

commit a8ad9820e89070e3adf084299c73bb2a5a5b797e
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Tue May 12 11:58:16 2026 -0700

    fix(skills): generate absolute manuscript URLs in publish PR body (#1235)
    
    * fix(skills): generate absolute manuscript URLs in publish PR body
    
    PR bodies produced by /printing-press-publish were emitting relative
    paths like `library/<category>/<slug>/.manuscripts/...`, which GitHub
    resolved against the PR page URL and rendered as broken
    `https://github.com/.../pull/library/...` links (see
    mvanhorn/printing-press-library#497).
    
    Capture HEAD_SHA after the push and require the Manuscripts section to
    emit full `https://github.com/mvanhorn/printing-press-library/blob/<sha>/...`
    URLs that point at specific files (not directories). The skill rewrites
    the body with a fresh SHA on every update path, so links stay current
    across force-pushes the skill performs.
    
    * fix(skills): make per-file manuscript bullets unambiguous in template
    
    Greptile P2 on #1235: the two-row template in the Manuscripts section
    could be read as authoritative even though the prose said "one per
    file," so an agent might emit exactly two bullets regardless of how
    many files were in research/ and proofs/.
    
    Replaced the prose preamble with a `<!-- one bullet per file -->`
    comment marker, doubled each example row, and added explicit
    "… (one bullet for each remaining file)" ellipsis rows for both
    research/ and proofs/. Pattern is now unambiguous: the visible
    template demonstrates repetition, not a fixed two-bullet shape.
---
 skills/printing-press-publish/SKILL.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/skills/printing-press-publish/SKILL.md b/skills/printing-press-publish/SKILL.md
index 467898c3..6a891c31 100644
--- a/skills/printing-press-publish/SKILL.md
+++ b/skills/printing-press-publish/SKILL.md
@@ -734,6 +734,16 @@ git push --force-with-lease -u origin feat/<api-slug>
 git push -u origin feat/<api-slug>
 ```
 
+### Capture the pushed commit SHA
+
+After pushing, capture the head commit SHA. This is used to build durable manuscript links in the PR body (see "Build the PR description" below).
+
+```bash
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+The SHA stays resolvable on `mvanhorn/printing-press-library` for the life of the PR (GitHub mirrors fork-PR head commits to `refs/pull/<N>/head` on the upstream), and remains valid after the PR is merged and the branch is deleted. Each invocation of this skill captures a fresh `HEAD_SHA` after its push and rewrites the body, so links stay current across updates the skill performs. If the branch is force-pushed outside this skill, re-run `/printing-press-publish` to refresh the body — the prior links will still resolve, but they'll point at the manuscript contents from before the out-of-band push.
+
 ### Create or update PR
 
 Read `access` and `gh_user` from `$PUBLISH_CONFIG`. These determine how `gh pr create` is called.
@@ -747,7 +757,7 @@ Build the PR description from:
 - The manifest's `novel_features` array from the packaged CLI after Step 6
 - The `help_output` captured in Step 4
 - The CLI's README (first 2-3 paragraphs, or note that README is missing)
-- Links to `.manuscripts/<run-id>/research/` and `.manuscripts/<run-id>/proofs/` within the PR branch
+- Links to every file under `.manuscripts/<run-id>/research/` and `.manuscripts/<run-id>/proofs/`. Each link must be a full `https://github.com/mvanhorn/printing-press-library/blob/<HEAD_SHA>/library/<category>/<api-slug>/.manuscripts/<run-id>/<subdir>/<filename>` URL — never a relative path (GitHub resolves those against `…/pull/`, producing broken `…/pull/library/…` URLs) and never a directory (the blob view requires a file). Enumerate the actual files; do not invent or skip them.
 - The validation results from Step 4
 - A Gaps section listing any missing manifest fields
 
@@ -821,8 +831,14 @@ $ <cli-name> --help
 
 ### Manuscripts
 
-- [Research Brief](<link to library/<category>/<api-slug>/.manuscripts/<run-id>/research/>)
-- [Shipcheck Results](<link to library/<category>/<api-slug>/.manuscripts/<run-id>/proofs/>)
+<!-- One bullet per file, NOT one per directory. Repeat the research/ row for every file in research/, and the proofs/ row for every file in proofs/. Use a human label that matches the file (e.g. `Research Brief`, `Absorb Manifest`, `Novel Features Brainstorm`, `Phase 5 Acceptance`). Substitute `<HEAD_SHA>` with the value captured after push. Do NOT use relative paths. -->
+
+- [<label>](https://github.com/mvanhorn/printing-press-library/blob/<HEAD_SHA>/library/<category>/<api-slug>/.manuscripts/<run-id>/research/<filename>)
+- [<label>](https://github.com/mvanhorn/printing-press-library/blob/<HEAD_SHA>/library/<category>/<api-slug>/.manuscripts/<run-id>/research/<filename>)
+- … (one bullet for each remaining file in `.manuscripts/<run-id>/research/`)
+- [<label>](https://github.com/mvanhorn/printing-press-library/blob/<HEAD_SHA>/library/<category>/<api-slug>/.manuscripts/<run-id>/proofs/<filename>)
+- [<label>](https://github.com/mvanhorn/printing-press-library/blob/<HEAD_SHA>/library/<category>/<api-slug>/.manuscripts/<run-id>/proofs/<filename>)
+- … (one bullet for each remaining file in `.manuscripts/<run-id>/proofs/`)
 
 ### Validation Results

← e40389ef fix(cli): default Accept to application/json instead of */* · back to Cli Printing Press · fix(cli): always quote SQL identifiers emitted by safeSQLNam c05d3bc7 →