## Step 18: Documentation sync (via subagent, before PR creation) **Dispatch /document-release as a subagent** using the Agent tool with `subagent_type: "general-purpose"`. The subagent gets a fresh context window — zero rot from the preceding 17 steps. It also runs the **full** `/document-release` workflow (with CHANGELOG clobber protection, doc exclusions, risky-change gates, named staging, race-safe PR body editing) rather than a weaker reimplementation. **Sequencing:** This step runs AFTER Step 17 (Push) and BEFORE Step 19 (Create PR). The PR is created once from final HEAD with the `## Documentation` section baked into the initial body. No create-then-re-edit dance. **Subagent prompt:** > You are executing the /document-release workflow after a code push. Read the full skill file `${HOME}/.claude/skills/gstack/document-release/SKILL.md` and execute its complete workflow end-to-end, including CHANGELOG clobber protection, doc exclusions, risky-change gates, and named staging. Do NOT attempt to edit the PR body — no PR exists yet. Branch: ``, base: ``. > > After completing the workflow, output a single JSON object on the LAST LINE of your response (no other text after it): > `{"files_updated":["README.md","CLAUDE.md",...],"commit_sha":"abc1234","pushed":true,"documentation_section":""}` > > If no documentation files needed updating, output: > `{"files_updated":[],"commit_sha":null,"pushed":false,"documentation_section":null}` **Parent processing:** 1. Parse the LAST line of the subagent's output as JSON. 2. Store `documentation_section` — Step 19 embeds it in the PR body (or omits the section if null). 3. If `files_updated` is non-empty, print: `Documentation synced: {files_updated.length} files updated, committed as {commit_sha}`. 4. If `files_updated` is empty, print: `Documentation is current — no updates needed.` **If the subagent fails or returns invalid JSON:** Print a warning and proceed to Step 19 without a `## Documentation` section. Do not block /ship on subagent failure. The user can run `/document-release` manually after the PR lands. --- ## Step 19: Create PR/MR **Idempotency check:** Check if a PR/MR already exists for this branch. **If GitHub:** ```bash gh pr view --json url,number,state -q 'if .state == "OPEN" then "PR #\(.number): \(.url)" else "NO_PR" end' 2>/dev/null || echo "NO_PR" ``` **If GitLab:** ```bash glab mr view -F json 2>/dev/null | jq -r 'if .state == "opened" then "MR_EXISTS" else "NO_MR" end' 2>/dev/null || echo "NO_MR" ``` If an **open** PR/MR already exists: **update** the PR body using `gh pr edit --body-file "$PR_BODY_FILE"` (GitHub) or `glab mr update -d ...` (GitLab). Always regenerate the PR body from scratch using this run's fresh results (test output, coverage audit, review findings, adversarial review, TODOS summary, documentation_section from Step 18). Never reuse stale PR body content from a prior run. **Run the same redaction scan-at-sink (PR body + title) as the create path (Step 19) before editing — scan the temp file, then `gh pr edit --body-file` from it.** **Always update the PR title to start with `v$NEW_VERSION`.** PR titles use the workspace-aware format `v :

` — version ALWAYS first, no exceptions, no "custom title kept intentionally" escape hatch. The shared helper `bin/gstack-pr-title-rewrite.sh` is the single source of truth for the rule. 1. Read the current title: `CURRENT=$(gh pr view --json title -q .title)` (or `glab mr view -F json | jq -r .title`). 2. Compute the corrected title: `NEW_TITLE=$(~/.claude/skills/gstack/bin/gstack-pr-title-rewrite.sh "$NEW_VERSION" "$CURRENT")`. The helper handles three cases: title already correct (no-op), title has a different `v` prefix (replace it), or title has no version prefix (prepend one). 3. If `NEW_TITLE` differs from `CURRENT`, run `gh pr edit --title "$NEW_TITLE"` (or `glab mr update -t "$NEW_TITLE"`). 4. **Self-check:** re-fetch the title and assert it starts with `v$NEW_VERSION `. If it does not, retry the edit once. If still wrong, surface the failure to the user. This keeps the title truthful when Step 12's queue-drift detection rebumps a stale version, and forces the format on PRs that were created without it. Print the existing URL and continue to Step 20. If no PR/MR exists: create a pull request (GitHub) or merge request (GitLab) using the platform detected in Step 0. The PR/MR body should contain these sections: ``` ## Summary ..HEAD --oneline` to enumerate every commit. Exclude the VERSION/CHANGELOG metadata commit (that's this PR's bookkeeping, not a substantive change). Group the remaining commits into logical sections (e.g., "**Performance**", "**Dead Code Removal**", "**Infrastructure**"). Every substantive commit must appear in at least one section. If a commit's work isn't reflected in the summary, you missed it.> ## Test Coverage ## Pre-Landing Review ## Design Review ## Eval Results ## Greptile Review ## Scope Drift ## Plan Completion ## Linked Spec -$$, the spawned worktree IS where /ship runs). SPEC_FILE=$(grep -l "^spec_branch: $CURRENT_BRANCH$" "$SPEC_ARCHIVES"/*.md 2>/dev/null | head -1) [ -z "$SPEC_FILE" ] && exit # no spec; omit this section entirely SPEC_ISSUE=$(grep "^spec_issue_number:" "$SPEC_FILE" | cut -d' ' -f2) [ -z "$SPEC_ISSUE" ] && exit # spec archive exists but no issue number; omit # CONDITIONAL Closes #N (codex F4): only add when Plan Completion above is "complete". # If the plan completion gate from Step 8 reports any deferred or failed items, emit: # "Linked to #$SPEC_ISSUE (partial delivery — NOT auto-closing; close manually after follow-up)" # If Plan Completion is fully complete, emit: # "Closes #$SPEC_ISSUE" # and include the Closes #N line in the PR body so GitHub auto-closes on merge.> This PR delivers the spec at . Spec filed: > (partial delivery — not auto-closing). Deferred items: . Close # manually after follow-up lands.> ## Verification Results ## TODOS ## Documentation ## Test plan - [x] All Rails tests pass (N runs, 0 failures) - [x] All Vitest tests pass (N tests) 🤖 Generated with [Claude Code](https://claude.com/claude-code) ``` #### Redaction scan (PR body + title) — runs before create AND edit The PR body is world-readable on a public repo. Scan-at-sink before sending: write the composed body to a temp file, scan THAT file with the shared engine, and pass the same file to `gh`/`glab`. Wrap any Codex / Greptile / eval output sections in tool-attributed fences (` ```codex-review ` / ` ```greptile `) so the engine WARN-degrades the example credentials those tools quote instead of blocking the PR (a live-format credential inside the fence still blocks). ```bash REDACT_VIS=$(~/.claude/skills/gstack/bin/gstack-config get redact_repo_visibility 2>/dev/null) [ -z "$REDACT_VIS" ] && REDACT_VIS=$(gh repo view --json visibility -q .visibility 2>/dev/null | tr 'A-Z' 'a-z') REDACT_VIS="${REDACT_VIS:-unknown}" PR_BODY_FILE=$(mktemp) cat > "$PR_BODY_FILE" <<'PR_BODY_EOF' PR_BODY_EOF ~/.claude/skills/gstack/bin/gstack-redact --from-file "$PR_BODY_FILE" --repo-visibility "$REDACT_VIS" --self-email "$(git config user.email 2>/dev/null)" --json case $? in 3) echo "BLOCKED — credential in PR body. Rotate + redact, do not create the PR."; exit 1 ;; 2) echo "MEDIUM findings — confirm per finding (sterner on public) before proceeding." ;; esac # Also scan the title (short, single-line): printf '%s' "v$NEW_VERSION :

" | ~/.claude/skills/gstack/bin/gstack-redact --repo-visibility "$REDACT_VIS" --json ``` HIGH blocks (exit 3, no skip). MEDIUM → AskUserQuestion (PII subset offers `--auto-redact`). Same scan runs before the `gh pr edit --body` path (Step 17). **If GitHub:** create from the SCANNED file (exact bytes scanned = bytes sent): ```bash # PR title MUST start with v$NEW_VERSION — enforced on every run, no exceptions. # (See Step 19 idempotency block + bin/gstack-pr-title-rewrite.sh for the rule.) gh pr create --base --title "v$NEW_VERSION :

" --body-file "$PR_BODY_FILE" rm -f "$PR_BODY_FILE" ``` **If GitLab:** ```bash # MR title MUST start with v$NEW_VERSION — enforced on every run, no exceptions. # (See Step 19 idempotency block + bin/gstack-pr-title-rewrite.sh for the rule.) glab mr create -b -t "v$NEW_VERSION :

" -d "$(cat <<'EOF' EOF )" ``` **If neither CLI is available:** Print the branch name, remote URL, and instruct the user to create the PR/MR manually via the web UI. Do not stop — the code is pushed and ready. **Output the PR/MR URL** — then proceed to Step 20. ---